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 #

PII handling #

Cardholder personal data is encrypted at rest in PayCA's database using
field-level envelope encryption (AES-256-GCM with an RSA-OAEP-wrapped
per-record content key). The following fields, when supplied in user meta,
are stored encrypted: phone, phoneCode, birthday, country, town,
address, postCode, gender, idType, idNo, idIssueDate,
idExpiryDate, nationality, occupation, annualSalary, accountPurpose,
expectedMonthlyVolume, ipAddress.

firstName, lastName, and email are stored in plaintext at rest to
support admin-side lookup and audit views.

In transit, all client traffic to PayCA uses TLS. PayCA forwards plaintext
cardholder data to Provider W over TLS — Provider W does not currently
support encrypted intake, so end-to-end encryption to the issuer is out of
scope. No request/response format changes — clients continue to submit
meta exactly as documented above.

Error Handling #