Provider W Cardholder Integration

Overview

Provider W 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 Provider W 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 Provider W; 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 Provider W.

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. Documents are sent as base64-encoded JSON (not multipart). Max 10 MB decoded per file.

# Helper — base64-encode a file and POST it
upload_kyc() {
  local USER_ID="$1" DOC_TYPE="$2" FILE="$3"
  local CONTENT=$(base64 < "$FILE" | tr -d '\n')
  curl -s -X POST "$PAYCA_BASE_URL/v1/users/$USER_ID/kyc/documents" \
    -H 'Content-Type: application/json' \
    -H "x-client-id: $PAYCA_CLIENT_ID" \
    -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
    -d "{
      \"documentType\": \"$DOC_TYPE\",
      \"fileName\":     \"${FILE##*/}\",
      \"fileContent\":  \"$CONTENT\",
      \"mimeType\":     \"image/jpeg\"
    }"
}

upload_kyc "$USER_ID" passport             passport.jpg
upload_kyc "$USER_ID" selfie_with_document selfie.jpg

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

Valid documentType values: passport, driving_licence, id_card, residence_permit, proof_of_address, selfie_with_document.

Wait for status: "completed" on GET /v1/users/{userId}/kyc (or subscribe to the kyc webhook) 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 Provider W.

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 (providerDefaultHolderId 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