Inyo

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"
}
FieldDescription
eventPaymentCardTokenized
sessionIdThe session the card belongs to
paymentCard.tokenThe gateway's card token. It goes in sender.paymentMethod.cardTokenId when you authorize a card payment
paymentCard.kindone_time or recurring, from storeLaterUse on the session. The gateway's one-time and recurring rules apply
paymentCard.lastFourThe last four digits of the tokenized card, for display
paymentCard.holderNameThe 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.payerIpAddressThe IP address the holder's browser sent the token from, for the authorization's ipAddress
paymentCard.expiresAtWhen the gateway said the token stops working. Authorize before it
paymentCard.recordedAtWhen Inyo360 recorded the token
notifiedAtWhen 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:

OutcomeWhat to do
A decision you accept, with card rows you acceptCapture
declined, failed, expired, or a card row you do not acceptVoid. The hold is released, and nothing was charged
in_reviewWait. 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

PropertyBehavior
RetriesNon-2xx answers and timeouts are retried with backoff, from 1 second up to 2 minutes between attempts, until 2 minutes before expiresAt
DuplicatesA retry can repeat a delivery you already processed. A session has one token: treat a second PaymentCardTokenized for the same sessionId as a repeat
OrderingPaymentCardTokenized is usually first, but not always: the result can overtake it while it is being retried. Handle whichever arrives first
Missed deliveriesRead 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.

SessionpaymentCard
Verification only (capture without tokenize)Absent
Tokenize, token recordedPresent
Tokenize, the holder never reached the token step β€” ran out of card attempts, or the session expiredAbsent. No PaymentCardTokenized was sent either
Tokenize, and tokenizing was switched off for your tenant after the link was sentAbsent β€” 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