PayCA supports Apple Pay and Google Pay provisioning when the selected BIN is tokenization-enabled.

1. Identify tokenizable BINs

  • GET /v2/accounts returns BIN objects with isTokenizable.
  • Only cards issued against tokenizable BINs can enter wallet provisioning.

Example snippet from an account response:

{
  "id": "3c38ab75-5c7f-4e1f-ae5f-1d52d1407a23",
  "currency": "EUR",
  "balance": { "available": "12000.00", "pending": "0.00" },
  "bins": [
    {
      "bin": "535444",
      "currencyCode": "EUR",
      "provider": "mastercard",
      "isTokenizable": true,
      "settings": {
        "minCardBalance": "25.00"
      }
    }
  ]
}

2. Enable wallet provisioning

  1. Issue cards using a tokenizable BIN.
  2. For existing cards, request tokenization enablement via PayCA support or internal tools.
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"
      }'

3. Tokenization lifecycle

  1. PayCA validates tokenization prerequisites.
  2. Issuer validates or sets cardholder phone and requests provider OTP.
  3. OTP arrives on card webhook with type = tokenization_code.
  4. After OTP redemption in Apple Pay/Google Pay, status moves to tokenization_done.

If OTP expires before redemption, status becomes tokenization_expired; restart tokenization for a new OTP window.

4. Webhook payload for wallet attach

Register a card webhook (type = card) and ingest OTP payloads.

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 HMAC signature and persist idempotently.
  2. Notify the requesting channel that OTP is available.
  3. Pass OTP to Apple Pay (activationData) or Google Pay (otp) provisioning API.
  4. Confirm completion through GET /v1/cards/{id} (tokenizationStatus = tokenization_done).

If webhook is missed, replay with POST /v1/webhooks/resend?fromDate=<ISO8601> while OTP is still valid.

5. Operational notes

  • Tokenization requires card status active and not frozen.
  • OTP validity is 15 minutes; expose countdown in client UX.
  • Alert on repeated unacknowledged card_tokenization events.
  • Tokenized BIN fees are reflected via account_transaction webhooks.