This checklist keeps engineering and operations aligned when onboarding a new user into your PayCA programme.

1. Pre-flight

  • ✅ Webhook endpoints deployed and registered (POST /v1/webhooks).
  • ✅ BIN catalogue covers the currencies and fee structures needed.
  • ✅ Master client account selected/funded in each launch currency (list via GET /v2/accounts).
  • ✅ Internal CRM can store PayCA identifiers (userId, cardId, userAccountId).

2. Create the User Profile

curl -X POST "$PAYCA_BASE_URL/v1/users" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
        "userId": "<external-id>",
        "meta": {"kycTier": "plus", "segment": "pro"},
        "bins": [
          {
            "bin": "411111",
            "currencyCode": "USD",
            "provider": "visa",
            "settings": { "minCardBalance": "25.00" },
            "isTokenizable": true,
            "fees": {
              "minCardBalance": "25.00",
              "issueFee": "1.50",
              "monthlyFee": "0.00",
              "authorization": [{"range": "0-100", "value": "0.35"}],
              "decline": [{"range": "0-100", "value": "0.10"}]
            }
          }
        ]
     }'

Persist the response:

  • userId – PayCA user UUID (internal reference; used as {id} in user endpoints).
  • userAccountId – Ledger account for future transfers (debited like any other account).

3. Attach Compliance Metadata

Send compliance metadata on creation using meta (and fetch it back via GET /v1/users/{id}). Example:

{
  "meta": {
    "kycStatus": "verified",
    "annualVolume": "120000",
    "riskScore": "2"
  }
}

Metadata propagates to webhook payloads so downstream systems can react immediately to risk changes.

4. Issue Cards

  • Decide between virtual and physical.
  • Provide optional restrictions (daily limits, merchant category blocks) if your contract supports them.
  • Store cardId, linkedAccountId, and last4.

Webhook example on success:

{
  "event": "card_transaction",
  "data": {
    "type": "issued",
    "cardId": "card-123",
    "userId": "user-abc",
    "timestamp": "2025-06-02T09:12:33Z"
  }
}

5. Fund the User

  1. Ensure the master account you picked in step 1 has available balance (check via GET /v2/accounts).
  2. Move funds into the user account via POST /v1/users/transfer (idempotent).
  3. Verify the balance increase via GET /v1/users/{id}.

6. Monitor Early Activity

Signal Endpoint Action
Low balance /v1/users/{id} or user_account_transaction webhook Trigger auto top-up or notify ops.
Dormant cards /v1/cards?status=active&lastTransactionBefore=X Remind user to activate or close account.
High decline rate card_transaction webhooks Investigate KYC, merchant MCC, or balance issues.
Fee spikes account_transaction webhook (subtype=fee) Adjust BIN pricing or risk strategy.

7. Graduation to Production

Before moving the user to production:

  • KYC and AML checks successful.
  • Master account balances reconciled.
  • Webhook processing confirmed idempotent.
  • Support playbook updated with new user/contact details.
  • Incident runbooks include PayCA escalation paths.

Related Reading