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.
  • ✅ Mirror account funded in each launch currency.
  • ✅ 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",
            "minCardBalance": "25.00",
            "fees": {
              "issueFee": "1.50",
              "authorization": [{"range": "0-100", "value": "0.35"}],
              "decline": [{"range": "0-100", "value": "0.10"}]
            }
          }
        ]
     }'

Persist the response:

  • id – PayCA user UUID (internal reference).
  • userAccountId – Ledger account for future transfers.
  • status – Defaults to pending; move to active, frozen, or blocked via status updates as onboarding progresses.

3. Attach Compliance Metadata

Use PATCH /v1/users/{id} to keep KYC or programme-specific tags up to date. Examples:

{
  "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. Confirm your tenant balance via GET /v1/users/stats (liquidity.balance).
  2. Transfer funds using POST /v1/users/transfer with an Idempotency-Key.
  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.
  • Tenant balances reconciled.
  • Webhook processing confirmed idempotent.
  • Support playbook updated with new user/contact details.
  • Incident runbooks include PayCA escalation paths.

Related Reading