Getting Started With PayCA

Who This Guide Is For

New engineering teams integrating PayCA for the first time. You should already have:

• curl or any HTTP client (Postman, Insomnia, or your language's standard library). PayCA is consumed over plain HTTP/JSON — no language-specific SDK or runtime is required.
• Network access to the API base URL shared by your PayCA account manager.
• Client credentials (x-client-id, x-client-secret) provisioned for your tenant.

If you are renewing an existing integration, skip directly to Verify the API.

Step 1 - Configure Environment Variables

Store your sandbox credentials in environment variables or your preferred secrets manager so they never appear in plain-text scripts.

export PAYCA_BASE_URL="https://api.actisas.ee"
export PAYCA_CLIENT_ID="6f1dbe35-43f7-466a-9941-1c01c5f8a6e7"
export PAYCA_CLIENT_SECRET="9a025859-1d2d-4c0f-90f5-28707c0b9d56"

Replace the sample values with the credentials you received from PayCA.

Step 2 - Verify the API

First confirm the API is reachable. /health is a public unauthenticated probe — it returns {"status":"ok"} and is useful for uptime checks but does not validate credentials.

curl -si "$PAYCA_BASE_URL/health"

Then verify your credentials with an authenticated call. GET /v2/accounts is a good first request because it has no side effects:

curl -si \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  "$PAYCA_BASE_URL/v2/accounts"

A 200 response with your accounts confirms credentials are valid. Capture the X-Request-ID response header — include it in any support conversations so we can trace your request in our logs.

Step 3 - Register Webhook Endpoints

Webhooks are registered per type. The full set is card, account, user, kyc, funding, cardholder. For a typical master-account integration, register at least card (card lifecycle and transaction events) and account (account-balance events). You can point each type at the same URL or split them.

curl -s -X POST "$PAYCA_BASE_URL/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "url": "https://hooks.dev.example.com/payca/card",
    "type": "card"
  }'

Repeat the call with "type": "account" (and any other types you need).

PayCA signs every delivery with the x-signature header — verify it server-side before processing the payload. Each delivery also carries an x-idempotency-key so retried hooks can be deduplicated safely.

Step 4 - Pick a Master Funding Account

List your master accounts with GET /v2/accounts, then pick an account in the currency you want to issue and fund cards from.

curl -s "$PAYCA_BASE_URL/v2/accounts" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET"

Response snippet:

{
  "accounts": [
    {
      "id": "c1bb6c19-3f9c-4cf0-9a08-5f2d00d021f1",
      "currency": "USD",
      "balance": { "available": "125000.00", "pending": "0.00" },
      "status": "active",
      "bins": [
        { "bin": "411111", "provider": "visa", "isTokenizable": true }
      ]
    }
  ]
}

Use accounts[].id as the accountId for card issuance and card topups.

Step 5 - Issue a Card

Create a card using your master account, target BIN, and opening balance.

curl -s -X POST "$PAYCA_BASE_URL/v1/cards" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
        "accountId": "c1bb6c19-3f9c-4cf0-9a08-5f2d00d021f1",
        "bin": "411111",
        "balance": "50.00",
        "idempotencyKey": "issue-demo-001"
     }'

Request field cheatsheet:

B2C vs B2B BINs. Most BINs (visa/mastercard via our card providers) are B2C and do not need a cardholder. Provider W BINs are B2B and require a pass_audit cardholder before any card can be issued on them. Your account manager will tell you which BINs in your tenant are B2B; you can also infer this from the error response the first time you try to issue without cardholderId.

Step 6 - Retrieve Sensitive Card Data (Optional)

If your PCI process requires access to PAN and CVV, fetch them once and vault them immediately.

curl -s "$PAYCA_BASE_URL/v1/cards/<card-id>/sensitive" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET"

Step 7 - Top Up the Card

You can add additional balance from any active master account in the same currency.

curl -s -X POST "$PAYCA_BASE_URL/v1/cards/<card-id>/topup" \
  -H 'Content-Type: application/json' \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
        "accountID": "c1bb6c19-3f9c-4cf0-9a08-5f2d00d021f1",
        "amount": "75.00",
        "idempotencyKey": "card-topup-75"
     }'

Ensure the source account has enough available balance before calling the endpoint.

Step 8 - Run a Transaction End-to-End

Use the sandbox helper endpoint to simulate card activity.

curl -s -X POST "$PAYCA_BASE_URL/sandbox/transactions" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "cardId": "<card-id>",
    "currency": "USD",
    "type": "authorization",
    "amount": "42.55"
  }'

Follow it with a settle request using the returned linkedId and confirm webhook delivery plus ledger impact.

Step 9 - Instrument Observability

• Log every X-Request-ID and x-signature from webhook deliveries.
• Track referenceId across card_transaction and account_transaction for reconciliation.
• Expose metrics: authorization success rate, decline reasons, settlement lag, webhook latency.

Step 10 - Harden for Production

Where To Go Next

• Use the Sandbox Playbook to script and test multi-step scenarios.
• Review the Go-Live Runbook so launch readiness is aligned early.
• Read API Authentication & Request Hygiene for signing rules, pagination, and error handling.
• Deep dive into Programme Entities for object-level integration details.
• Use Webhook Handling Patterns together with Webhook Balance Effects for robust accounting flows.

Quick Reference