Card Results
A tokenize session gives you the card token twice: in its own webhook the moment the holder's card is tokenized, and again in the session's result. The first is the one to act on. The gateway's token must be used within a short window after it is created, and a session can take much longer to reach its decision, for example while it waits for a review.
sequenceDiagram
autonumber
participant Y as Your System
participant I as Inyo360
participant G as Payments Gateway
I-->>Y: PaymentCardTokenized
Y->>G: POST /v2/payment<br/>capture: false
G-->>Y: AUTHORIZED
Note over I: Card checks,<br/>decision
I-->>Y: SessionResultUpdated
alt the outcome is one you accept
Y->>G: capture
else declined, expired, or a card row you reject
Y->>G: void
end
A verification-only session has no token: it sends the result alone, with the card rows in checks.
The PaymentCardTokenized Webhook
Sent to your webhookUrl as soon as the token is recorded, before the card checks run and before the session's decision. It is signed like every Inyo360 KYC webhook β see Receiving Results.
{
"event": "PaymentCardTokenized",
"sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
"paymentCard": {
"token": "3b9f6c1e-8d2a-4f7b-9e5c-1a2b3c4d5e6f",
"kind": "one_time",
"lastFour": "4242",
"holderName": "MARIA SANTOS",
"payerIpAddress": "203.0.113.42",
"expiresAt": "2026-07-31T14:34:39Z",
"recordedAt": "2026-07-31T14:04:41.112Z"
},
"notifiedAt": "2026-07-31T14:04:41.530Z"
}
| Field | Description |
|---|---|
event | PaymentCardTokenized |
sessionId | The session the card belongs to |
paymentCard.token | The gateway's card token. It goes in sender.paymentMethod.cardTokenId when you authorize a card payment |
paymentCard.kind | one_time or recurring, from storeLaterUse on the session. The gateway's one-time and recurring rules apply |
paymentCard.lastFour | The last four digits of the tokenized card, for display |
paymentCard.holderName | The cardholder name the holder confirmed in the widget, as one string. Split it into sender.firstName and sender.lastName for the authorization: the gateway's name check compares those with the name on the card |
paymentCard.payerIpAddress | The IP address the holder's browser sent the token from, for the authorization's ipAddress |
paymentCard.expiresAt | When the gateway said the token stops working. Authorize before it |
paymentCard.recordedAt | When Inyo360 recorded the token |
notifiedAt | When this delivery was sent |
The authorization also needs the holder's billing address. Inyo360 does not collect one: take it from your own records or ask the holder for it.
Pre-Authorize, Then Decide
Authorize with capture: false as soon as the webhook arrives. That holds the funds without moving them, for up to 7 days, while the session reaches its decision. Then, on the session's result:
| Outcome | What to do |
|---|---|
A decision you accept, with card rows you accept | Capture |
declined, failed, expired, or a card row you do not accept | Void. The hold is released, and nothing was charged |
in_review | Wait. The decision arrives in a later SessionResultUpdated |
The webhook is not a verdict. It is sent before Inyo360 has compared the tokenized card with the photographed one. That comparison is the payment_card_token_match row in the result. Capture only once you have read it.
A one-time token is spent by its authorization. If the hold lapses before the decision, a one-time token cannot authorize again; a recurring token can.
Delivery
| Property | Behavior |
|---|---|
| Retries | Non-2xx answers and timeouts are retried with backoff, from 1 second up to 2 minutes between attempts, until 2 minutes before expiresAt |
| Duplicates | A retry can repeat a delivery you already processed. A session has one token: treat a second PaymentCardTokenized for the same sessionId as a repeat |
| Ordering | PaymentCardTokenized is usually first, but not always: the result can overtake it while it is being retried. Handle whichever arrives first |
| Missed deliveries | Read GET /v1/sessions/{sessionId}: its paymentCard carries the same fields whenever the token is recorded |
Answer 2xx before you call the gateway. A handler that authorizes first and answers after the 15-second timeout receives the same webhook again.
The paymentCard Block in the Result
The SessionResultUpdated result of a tokenize session carries the token again, beside the checks and the decision:
{
"event": "SessionResultUpdated",
"sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
"userRef": "user-123",
"status": "completed",
"checks": [
{ "name": "payment_card_scene_clear", "status": "passed", "group": "payment_card", "severity": "medium", "reason": null, "detail": "no screen-recapture signals" },
{ "name": "payment_card_screen_grid_clear", "status": "passed", "group": "payment_card", "severity": "high", "reason": null, "detail": "no screen grid across the edge" },
{ "name": "payment_card_token_match", "status": "passed", "group": "payment_card", "severity": "high", "reason": null, "detail": "the tokenized card matches the photographed card and the holder" }
],
"paymentCard": {
"token": "3b9f6c1e-8d2a-4f7b-9e5c-1a2b3c4d5e6f",
"lastFour": "4242",
"kind": "one_time",
"recordedAt": "2026-07-31T14:04:41.112Z"
},
"provider": "inyo",
"trustIndex": 100,
"completedAt": "2026-07-31T14:04:57.874Z",
"notifiedAt": "2026-07-31T14:04:58.010Z"
}
The rest of the payload β document, person, the identity rows, decision β is described on Session Results. The block is the record of which card the session tokenized: token, lastFour, kind and recordedAt, as in the webhook.
When It Is Present
The block is present only on a session created with paymentCard.tokenize whose holder reached the token step and handed over a token. Otherwise the key is absent, not null.
| Session | paymentCard |
|---|---|
Verification only (capture without tokenize) | Absent |
| Tokenize, token recorded | Present |
| Tokenize, the holder never reached the token step β ran out of card attempts, or the session expired | Absent. No PaymentCardTokenized was sent either |
| Tokenize, and tokenizing was switched off for your tenant after the link was sent | Absent β the step ran as verification only |
A card check that does not pass does not remove the block. The session still completes, and the row's status says what failed β see Checks.
What Inyo360 Stores Beside the Token
Inyo360 keeps a token record per session: the token, its kind, the last four as the widget reported them, the card's expiry month, the cardholder name the holder confirmed, when the token expires, and the IP address the token was sent from. The card's expiry month is never delivered.
lastFour is the value the widget reported from the gateway's tokenizer. Inyo360 checks it against the digits left on the stored card photos, and the outcome is the payment_card_token_match row. Gate on that row, not on lastFour alone.
See Data Handling for everything Inyo360 stores.
Next Steps
- Checks β the card rows in
checks - Receiving Results β signatures, event types and delivery
- Authorizing a Card Payment β pre-authorization, capture and void
