Wallet Provisioning OTP

When a cardholder adds a SetldPay card to Apple Pay or Google Pay, the card scheme may require a one-time step-up to confirm the real cardholder is behind the request — the identity & verification (ID&VID&VIdentity & verification — the scheme's "yellow path" step-up that confirms the real cardholder is behind the request.) "yellow path". For these programs TribeTribeSetldPay's card issuer-processor. Here it generates the OTP and validates it when entered. hands that step to us: it sends a holderAuthenticationholderAuthenticationThe Tribe TAI notification carrying the OTP, the channel, and the wallet — the trigger for this flow. message carrying a one-time code (OTPOTPOne-time passcode — the short code the cardholder types into the wallet to pass ID&V.), and SetldPay delivers that code to the cardholder by SMS or email. This page traces the whole path; the build lives on the Wallet Provisioning OTP Delivery design page.

It is a side-branch off normal push provisioningPush provisioningAdding a card to a device wallet (Apple / Google Pay), which creates a device-bound token. — the happy path needs no cardholder prompt. The step-up OTP only fires when the scheme demands ID&V during tokenizationTokenizationThe scheme replacing the card number with a device token (DPAN) — the step that can require ID&V.:

The code originates at Tribe and travels outward to the cardholder, who enters it to finish verification. Read the lanes left to right and time top to bottom — SetldPay's lane only ever receives the request and sends the OTP; it is never on the validation path.

Step by step

1. 1
   Cardholderadd card to wallet

   Taps Add in Apple or Google Pay.

2. 2
   Wallettokenize

   Asks the scheme to create a device token for the card.

3. 3
   Scheme TSPstep-up ID&V requiredyellow path

   Needs holder verification and asks Tribe.

4. 4
   TribeholderAuthentication

   Generates the OTP and sends it to SetldPay in the notification.

5. 5
   SetldPaygetHolder · render copy

   Looks up the cardholder contact (getHolder) and renders the message.

6. 6
   SetldPaydeliver OTP

   Sends the code by SMS or email.

7. 7
   Cardholderenter code

   Types the code into the wallet.

8. 8
   Walletrelay via scheme

   Relays the code back through the scheme to Tribe.

9. 9
   Tribevalidate · activate token

   Validates the code and activates the device token.

10. 10
    TribeholderAuthenticationNotification

    Reports the outcome (Y/N/E/L/C) to SetldPay for logging.

Tribe delivers the trigger as a holderAuthentication TAI notification on the encrypted notify endpoint. The code is already in the payload — validationValue — and a single field, authenticationMethod, says which channel to use.

Message essentials

What we act on

Example payload

{
  "requestType": ["holderAuthentication"],
  "holderAuthentication": {
    "authRequestId": 16147738970184,
    "holderId": 3731163,
    "authenticationMethod": 4,
    "requestor": 2,
    "validationValue": "718294",
    "requestExpiresAt": 1612789119,
    "cardId": 1354301,
    "cardProgramId": 44,
    "walletProviderId": 3,
    "additionalData": {
      "maskedPan": "XXXXXXXXXXXX0013",
      "maskedPhone": "XXXXXXX22"
    }
  }
}

Method 4 (email) for an Apple Pay tokenization (requestor 2, walletProviderId 3). maskedPan / maskedPhone are display-only — the real contact comes from Tribe's getHolder.

Inside SetldPay the work splits in two: ingest acknowledges Tribe in milliseconds, then a background worker does the slower delivery — so a slow SMS or email provider can never threaten the webhook response.

Delivery is the end of SetldPay's request leg. As the lower half of the sequence above shows, the cardholder enters the code in the wallet; it relays back through the schemeScheme TSPThe scheme's Token Service Provider — Mastercard MDES or Visa VTS — which issues and manages tokens. to Tribe, which validates it — that is why we never need to. The token then activates and the card goes live in the wallet.

Tribe reports the outcome to us with a separate holderAuthenticationNotification. We log it for observability (correlating a delivery to its result) but take no action on it.

The OTP lifecycle is split deliberately. Reading the boundary as "SetldPay delivers, Tribe owns the code" keeps the design honest — it is why there is no OTP store, validation endpoint, or callback on our side.