Send the cardholder a one-time code by the method they chose in the wallet (token service connector only)
/cards/network-tokens/verification-codesOnly the network's own token service connector (svc_vts for visa, svc_mdes for mastercard, svc_ddx for discover) holding cards:tokens:network and no API key; cards:write and staff are refused. CARD_NETWORK_TOKEN_CONFIG must enable tokenization. Locally the connector is a VTS, MDES or DDX style simulator; nothing a simulator sends is evidence that a network acted. The request reference is the idempotency key: an identical retry replays the retained event with 200 and replayed true, a changed body under the same reference is idempotency_key_reused. The token must be pending_idv with the method offered. A six-digit code is sealed and sent to the cardholder through the notifications service (card_token_code_sms or card_token_code_email); it never appears in a response, event or history. At most three codes per token by default.
Headers
Idempotency-KeystringOptionalSend on every write that creates or changes money or state; a replay with the same key returns the original result with 200.
Body parameters
methodstringRequiredOtp_sms or otp_email
networkstringRequiredrequest_referencestringRequiredtoken_referencestringRequiredReturns
200 OK
eventobjectRequiredEvent is one immutable entry in a token's history with the token state after it.
20 child attributes
actorstringRequiredactor_kindstringRequiredToken_service, holder, staff or issuer
atstring · date-timeRequiredchallengeobject or nullOptionalChallenge is one one-time code the bank issued. The code itself is sealed at rest and never leaves the bank except in the notification to the cardholder.
8 child attributes
created_atstring · date-timeRequireddeliverystringOptionalSent, queued or undeliverable
expires_atstring · date-timeRequiredidstringRequiredmethodstringRequirednotification_idstringOptionalExample ntf_2tVh8nqLxq4GbDe0K1F6S9zRcWm
numberintegerRequiredtoken_idstringRequiredcode_attemptobject or nullOptionalThe attempt without its code
4 child attributes
codestringOptionalNever retained; the event keeps a domain-separated digest beside the record
networkstringRequiredrequest_referencestringRequiredtoken_referencestringRequiredcode_requestobject or nullOptionalCodeRequest is the token service relaying the cardholder's chosen verification method.
4 child attributes
methodstringRequiredOtp_sms or otp_email
networkstringRequiredrequest_referencestringRequiredtoken_referencestringRequiredcommand_idstringOptionalcontrols_requestobject or nullOptionalControlsRequest replaces a token's controls at an exact sequence.
3 child attributes
controlsobjectRequiredControls are per-token spending controls. They only ever restrict further than the card's own controls, which still apply to every token authorization.
5 child attributes
blocked_mccsarray of stringsOptionalchannelsarray of stringsOptionalEmpty means every channel of the token's domain
daily_limit_amountintegerOptionalper_transaction_limit_amountintegerOptionalvalid_untilstring · date-time or nullOptionalexpected_sequenceintegerRequiredreasonstringRequiredkindstringRequiredlifecycleobject or nullOptionalLifecycleRequest is an issuer-initiated suspension, resumption or deletion.
3 child attributes
actionstringRequiredSuspend, resume or delete
expected_sequenceintegerRequiredreasonstringRequirednotificationobject or nullOptionalNotification is a token lifecycle notification from the token service.
7 child attributes
eventstringRequiredActivated, suspended, resumed or deleted
initiated_bystringRequiredToken_requestor, cardholder, network or issuer
networkstringRequirednotification_referencestringRequiredoccurred_atstring · date-timeRequiredreasonstringOptionaltoken_referencestringRequiredoutcomestringRequiredpan_updateobject or nullOptionalPANUpdate carries a replacement card to the token service. The pan_token is the issuer processor's surrogate; the certified connector resolves it to the PAN inside its boundary.
5 child attributes
card_idstringRequiredExample card_2tVh8nqLxq4GbDe0K1F6S9zRcWm
expiry_monthintegerRequiredexpiry_yearintegerRequiredlast4stringRequiredpan_tokenstringRequiredproposal_idstringOptionalreasonstringOptionalrequestobject or nullOptionalAuthorizationRequest is the token service's token authorization request, bank-defined.
17 child attributes
card_verificationobjectRequiredCardVerification is what the issuer processor's security module found on the credentials the token service forwarded: the core never sees the CVV2 or the PAN.
3 child attributes
avsstringRequiredMatch, partial, no_match or not_checked
cvv2stringRequiredMatch, no_match or not_checked
expirystringRequiredMatch, no_match or not_checked
device_sha256stringOptionalWallet: opaque device binding digest
merchant_idstringOptionalMerchant: the exact processor merchant identity
networkstringRequiredpan_sourcestringRequiredIssuer_app, manual or on_file
pan_tokenstringRequiredThe issuer processor's surrogate of the funding PAN
request_referencestringRequiredriskobjectRequiredRisk is the token service's and wallet provider's risk data, normalized by the connector. Scores are on the bank-defined scale 1 (highest risk) to 5 (lowest risk); 0 is not provided.
6 child attributes
account_scoreintegerOptionaldevice_countrystringOptionaldevice_scoreintegerOptionalphone_number_scoreintegerOptionalreason_codesarray of stringsOptionalrecommended_decisionstringOptionalApprove, decline or require_idv
token_expiry_monthintegerRequiredtoken_expiry_yearintegerRequiredtoken_last4stringRequiredtoken_referencestringRequiredThe token service's unique token reference, never the token number
token_requestor_idstringRequired11 digits
token_requestor_namestringRequiredtoken_typestringRequiredSecure_element, cloud or card_on_file
use_casestringRequiredwallet_consent_idstringOptionalPush provisioning: the holder's recorded wallet consent
request_sha256stringRequiredresultobjectRequiredToken is a network token's current state as the bank holds it. It carries no token number.
28 child attributes
assurancestringRequiredcard_idstringRequiredExample card_2tVh8nqLxq4GbDe0K1F6S9zRcWm
controlsobjectRequiredControls are per-token spending controls. They only ever restrict further than the card's own controls, which still apply to every token authorization.
5 child attributes
blocked_mccsarray of stringsOptionalchannelsarray of stringsOptionalEmpty means every channel of the token's domain
daily_limit_amountintegerOptionalper_transaction_limit_amountintegerOptionalvalid_untilstring · date-time or nullOptionalcreated_atstring · date-timeRequireddecisionobjectRequiredDecision is the issuer's answer to a token authorization request.
4 child attributes
assurancestringRequireddecisionstringRequiredreasonsarray of stringsRequiredverification_methodsarray of objectsOptionaldevice_sha256stringOptionaldomain_controlsobjectRequiredDomainControls are the token domain restriction controls the issuer sets at provisioning.
4 child attributes
channelsarray of stringsRequiredcryptogram_requiredbooleanRequiredmerchant_idstringOptionaltoken_requestor_idstringRequiredeffective_statusstringRequiredholder_customer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
idstringRequiredissuer_statusstringRequiredissuer_suspended_bystringOptionalHolder or staff
last_network_event_atstring · date-time or nullOptionalmerchant_idstringOptionalnetworkstringRequirednetwork_statusstringRequiredoriginal_card_idstringRequiredExample card_2tVh8nqLxq4GbDe0K1F6S9zRcWm
sequenceintegerRequiredtoken_expiry_monthintegerRequiredtoken_expiry_yearintegerRequiredtoken_last4stringRequiredtoken_referencestringRequiredtoken_requestor_idstringRequiredtoken_requestor_namestringRequiredtoken_typestringRequiredupdated_atstring · date-timeRequireduse_casestringRequiredwallet_consent_idstringOptionalsequenceintegerRequiredtoken_idstringRequiredreplayedbooleanRequiredErrors
Every error is a problem document with a stable code. See Errors.
400401403404409412413422424429500503