Decide a token service's token authorization request: approve, decline or require identification and verification (token service connector only)
/cards/network-tokens/authorization-requestsOnly 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 bank decides from the funding card (active, unexpired, not replaced, holder authority current), the token count, the requestor deny list, card verification results and the token service risk data: approved, declined with every reason, or require_idv with the verification methods offered. Push provisioning names the holder's wallet consent, which must be for this card, requestor and device, enabled, unused and fresh. An unknown pan_token is not_found; a token reference already held is conflict.
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
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
Returns
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