Wasabi Cardholder Integration

Overview

Wasabi cards require a cardholder before a card can be issued. The cardholder goes through a two-stage approval:

1. PayCA review — cardholder is created with pending_review status and must be approved by a PayCA admin.
2. Provider audit — after PayCA approves, the cardholder is submitted to Wasabi and moves through wait_audit → pass_audit (or reject).

Only cardholders with status: "pass_audit" can be used to issue cards.

Cardholder Statuses

B2B Flow

B2B cardholders require basic personal data only. No KYC documents are needed — file IDs are uploaded manually via the file upload endpoint.

Step 1 — Create user

curl -s -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 '{
    "externalId": "usr-001",
    "meta": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "5551234567",
      "phoneCode": "+1",
      "birthday": "1990-01-15",
      "country": "US",
      "town": "NYC",
      "address": "123 Main St",
      "postCode": "10001"
    }
  }'

Use /v1/cardholders/regions for country codes and /v1/cardholders/cities for town codes.

Step 2 — Upload identity documents (optional, B2B only)

curl -s -X POST "$PAYCA_BASE_URL/v1/cardholders/files" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -F "file=@passport_front.jpg"

Save the returned fileId values and include them in the user meta as idFrontImg, idBackImg, idHoldImg.

Step 3 — Create cardholder

curl -s -X POST "$PAYCA_BASE_URL/v1/users/{userId}/cardholder" \
  -H 'Content-Type: application/json' \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "accountId": "<account-uuid>",
    "bin": "537100"
  }'

Response returns a CardholderResponse with status: "pending_review".

Step 4 — Wait for approval

Poll GET /v1/cardholders/{id} until status changes:

• pass_audit — proceed to card issuance.
• rejected_by_admin — rejected by PayCA; check description for the reason.
• reject — rejected by Wasabi; check description and statusFlowLocation.

Step 5 — Issue card

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": "<account-uuid>",
    "bin": "537100",
    "balance": "100.00",
    "idempotencyKey": "issue-001",
    "cardholderId": "<cardholder-uuid>"
  }'

3DS OTP codes are sent to the cardholder's email and phone.

B2C Flow

B2C cardholders require extended personal data and completed KYC verification. KYC documents are uploaded automatically from the KYC system when the cardholder is submitted to Wasabi.

Step 1 — Create user

Include all B2B fields plus B2C-specific fields:

curl -s -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 '{
    "externalId": "usr-002",
    "meta": {
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane@example.com",
      "phone": "5559876543",
      "phoneCode": "+1",
      "birthday": "1988-05-20",
      "gender": "F",
      "idType": "PASSPORT",
      "idNo": "AB1234567",
      "nationality": "US",
      "country": "US",
      "town": "LAX",
      "address": "456 Oak Ave",
      "postCode": "90001",
      "occupation": "IT"
    }
  }'

Use /v1/cardholders/occupations for occupation codes.

Step 2 — KYC verification

Upload identity documents and a selfie, then submit for review:

# Upload identity document
curl -s -X POST "$PAYCA_BASE_URL/v1/users/{userId}/kyc/documents" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -F "file=@passport.jpg" \
  -F "type=passport"

# Upload selfie with document
curl -s -X POST "$PAYCA_BASE_URL/v1/users/{userId}/kyc/documents" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -F "file=@selfie.jpg" \
  -F "type=selfie_with_document"

# Submit KYC for review
curl -s -X POST "$PAYCA_BASE_URL/v1/users/{userId}/kyc/submit" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET"

Wait for webhook with kycStatus: "completed" before proceeding.

Step 3 — Create cardholder

Same as B2B Step 3. KYC must be completed — the endpoint rejects requests if KYC is not completed.

Step 4 — Wait for approval

Same as B2B Step 4. After PayCA admin approves, KYC documents are automatically uploaded to Wasabi.

Step 5 — Issue card

Same as B2B Step 5 — pass the cardholderId in the card creation request.

Issuing Cards Without a Cardholder

If the BIN has a default holder configured (WasabiDefaultHolderID in BIN settings), cards can be issued without creating a cardholder first. The system resolves the holder using this priority:

1. Explicit cardholderId in the request (must be pass_audit).
2. User's approved cardholder for the card type.
3. Default holder from BIN settings.

This allows card issuance to work while a cardholder is still going through the approval process.

Required User Meta Fields

B2B (minimum)

B2C (additional)

Optional fields (B2B and B2C)

API Endpoints Reference

Error Handling