PayCA can provision cards into Apple Pay or Google Pay as long as the BIN backing the card has the tokenized capability enabled. This guide explains how to spot wallet-ready BINs, trigger tokenization, and handle the webhook that delivers the OTP you need to attach the card to a device wallet.

1. Identify tokenizable BINs

  • Every BIN object returned from GET /v2/accounts includes an isTokenizable boolean. Wallet-ready BINs come with the tokenized flag set to true.
  • Only cards issued against those BINs can enter the Apple/Google Pay flow.

Example snippet from a user payload:

{
  "id": "3c38ab75-5c7f-4e1f-ae5f-1d52d1407a23",
  "status": "active",
  "account": { "...": "..." },
  "bins": [
    {
      "bin": "535444",
      "currencyCode": "EUR",
      "provider": "mastercard",
      "isTokenizable": true,
      "settings": {
        "minCardBalance": "25.00"
      }
    }
  ]
}

2. Enable wallet provisioning

  1. At issuance — issue cards against a tokenizable BIN (bins[].isTokenizable = true). Tokenization is enabled by PayCA programme configuration; there is no tokenize flag on POST /v1/cards.

    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": "94d3f571-a726-4cb5-9691-f471ed49b5bd",
        "bin": "535444",
        "balance": "50.00"
      }'
  • Existing cards — reach out via your PayCA support channel (or internal tooling if available) to mark a specific card for tokenization. As soon as PayCA marks it for provisioning you will automatically get the webhook described below; there is no tenant-facing API call anymore.

3. What happens during tokenization

  1. PayCA verifies that the card product supports tokenization and that there is no in-flight session. This step now runs automatically whenever the platform marks a card as tokenizable.
  2. The issuer validates/sets the cardholder phone, then waits for a provider-generated OTP.
  3. As soon as the OTP arrives, PayCA pushes it through your card webhook subscription with type = tokenization_code.
  4. When the user redeems the OTP inside Apple Pay or Google Pay, PayCA automatically detaches the card from the tokenization queue and updates tokenizationStatus to tokenization_done.

If the OTP is never redeemed, the workflow detaches the card with tokenizationStatus = tokenization_expired. Ask PayCA to restart tokenization (or issue a fresh card) to generate a new OTP window and webhook.

4. Webhook payload to attach the card

Register a card webhook (type = card) and expose a handler that consumes the OTP payload below. The delivery contract follows the standard webhook headers (Content-Type, x-signature, x-request-id, optional x-idempotency-key) described in Webhook Handling Patterns.

Sample request:

POST https://your-webhook.example.com/payca/card
Content-Type: application/json
x-client-id: 7b1dde35-1ec4-4dbc-9a6d-cc533a132c15
x-signature: sha256=0e58f93f47fb9d9d3a6d9a6f0e7f9a8780a70fddff5b9c0e050a739db752be32
x-request-id: 03a3049b-a712-41b8-a180-7dd70dd82a6d

{
  "event": "card_tokenization",
  "data": {
    "type": "tokenization_code",
    "cardId": "35183072-f614-4c49-8381-fca9374ab456",
    "code": "483921"
  }
}

Recommended handling:

  1. Verify the HMAC signature and persist the payload idempotently (keyed by cardId + code).
  2. Notify the requesting client (mobile app, browser, or CSR tool) that the OTP arrived.
  3. Invoke the Apple Pay or Google Pay provisioning API with the OTP:
    • Apple Pay In-App Provisioning: pass the code in the activationData payload.
    • Google Pay TSP: include it in the otp field when calling cards:activate.
  4. Confirm completion by polling GET /v1/cards/{id}; once the tokenizationStatus flips to tokenization_done, the wallet can transact immediately.

If you miss the webhook, replay it via POST /v1/webhooks/resend?fromDate=<ISO8601>—the OTP can be resent as long as it has not expired.

5. Operational notes

  • Tokenization is available only while the card is active and unfrozen; if you freeze or close the card before redeeming the OTP, restart the flow after the state change.
  • Each OTP is valid for 15 minutes (timeout value). Build UI timers so the user can request a new code before it lapses.
  • Use strong logging and alerting: trigger an alert when repeated card_tokenization payloads remain unacknowledged or when cards end up in tokenization_expired.
  • The tokenization flow charges any applicable tokenized BIN fees (see your bins[].fees configuration) via the usual account_transaction webhooks.