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.

Cardholder Is Always Required for Provider W

Every Provider W card issue requires the requesting client to already have a pass_audit cardholder for the BIN's card type. The check runs as a preflight on POST /v1/cards; failures return HTTP 412 (Failed Precondition) with a kyc required: ... message before any funds are held or any workflow is started.

Once the client-level KYC is in place, the provider-side holderId for the actual card issuance is resolved in this priority:

1. Explicit cardholderId in the request — must belong to your client, match the BIN's card type, and be pass_audit.
2. User's approved cardholder for the card type (/v1/users/{id}/cardholder).
3. BIN-internal fallbacks (b2b holder pool, BIN default holder) — used when no per-user cardholder is set; never bypasses the client-level KYC preflight.

In practice: create the cardholder, wait for pass_audit, then issue. There is no longer a path that lets a client issue a Provider W card before completing its own KYC.

Required User Meta Fields

B2B (minimum)

B2C (additional)

Optional fields (B2B and B2C)

API Endpoints Reference

Error Handling