increase-test
POST/simulations/card_balance_inquiries

Simulate a card balance inquiry

Simulates a balance inquiry on a Card in the sandbox. Supply a card identifier or a physical card or digital wallet token identifier to specify the card being used, and use balance to override the account balance for the simulation. You can also provide merchant details, network information, or a decline_reason to exercise specific scenarios.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

15 body fields

Optional card balance inquiry simulation inputs, including card identifiers, balance, merchant details, and network-specific data.

balanceintegeroptional
The balance amount in cents. The account balance will be used if not provided.
card_idstringoptional
The identifier of the Card to be authorized.
decline_reasonstringoptional
Forces a card decline with a specific reason. No real time decision will be sent.
Allowed:account_closedcard_not_activecard_canceledphysical_card_not_activeentity_not_activegroup_lockedinsufficient_fundscvv2_mismatchpin_mismatchcard_expiration_mismatchtransaction_not_allowedbreaches_limit
digital_wallet_token_idstringoptional
The identifier of the Digital Wallet Token to be authorized.
event_subscription_idstringoptional
The identifier of the Event Subscription to use. If provided, will override the default real time event subscription. Because you can only create one real time decision event subscription, you can use this field to route events to any specified event subscription for testing purposes.
merchant_acceptor_idstringoptional
The merchant identifier (commonly abbreviated as MID) of the merchant the card is transacting with.
merchant_category_codestringoptional
The Merchant Category Code (commonly abbreviated as MCC) of the merchant the card is transacting with.
merchant_citystringoptional
The city the merchant resides in.
merchant_countrystringoptional
The country the merchant resides in.
merchant_descriptorstringoptional
The merchant descriptor of the merchant the card is transacting with.
merchant_statestringoptional
The state the merchant resides in.
network_detailsobjectoptional
Fields specific to a given card network.
network_risk_scoreintegeroptional
The risk score generated by the card network. For Visa this is the Visa Advanced Authorization risk score, from 0 to 99, where 99 is the riskiest.
physical_card_idstringoptional
The identifier of the Physical Card to be authorized.
terminal_idstringoptional
The terminal identifier (commonly abbreviated as TID) of the terminal the card is transacting with.

3 status codes
200Returns the Card Payment object created for the simulated balance inquiry, including its interactions and summarized state.
account_idstringrequired
The identifier for the Account the Transaction belongs to.
card_idstringrequired
The Card identifier for this payment.
created_atstringrequired
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) time at which the Card Payment was created.
digital_wallet_token_idstringrequired
The Digital Wallet Token identifier for this payment.
elementsarray<CardPaymentCardPaymentElement>required
The interactions related to this card payment.
idstringrequired
The Card Payment identifier.
physical_card_idstringrequired
The Physical Card identifier for this payment.
stateobjectrequired
The summarized state of this card payment.
typestringrequired
A constant representing the object's type. For this resource it will always be `card_payment`.
Allowed:card_payment
4XXReturned when the request cannot be processed because of a client-side error.
5XXReturned when the service encounters a server-side error.

Error handling

If provided, balance must be an integer from 1 to 1000000000, and network_risk_score must be an integer from 0 to 99. Merchant detail fields and terminal_id must contain 1 to 200 characters; decline_reason must be an accepted value, and network_details must include visa.