Getting Started With PayCA

Who This Guide Is For

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

• A workstation with Go 1.23+ and curl or an API client such as Postman/Insomnia.
• Network access to the sandbox base URL shared by your PayCA account manager.
• Client credentials (x-client-id, x-client-secret) provisioned for the sandbox.

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

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.sandbox.payca.io"
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 Sandbox

Check that your credentials work and the API is reachable.

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

A healthy response reports the API build SHA and the database connection status. Capture the X-Request-ID header for support conversations.

Step 3 - Register Webhook Endpoints

For master-account integrations, subscribe to card and account webhook types:

• card -> card_transaction
• account -> account_transaction

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 with "type": "account" (you can use a separate URL).

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:

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