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, and deposit. For a typical master-account integration, register at least card (card lifecycle and transaction events) and account (account-balance events). If card deposits are enabled for your client, also register deposit to receive completed, failed, refunded, and chargeback outcomes. 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. An x-idempotency-key is included when the source operation supplied one; combine it with the event's stable payload identifier when deduplicating deliveries.

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 x-client-id, the optional x-idempotency-key, and your own request correlation ID. Do not log webhook signatures.
• 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 Card Deposits Into PayCA Accounts to fund an account through hosted card checkout.
• Use Webhook Handling Patterns together with Webhook Balance Effects for robust accounting flows.

Quick Reference #