Simulation
Simulate ATM withdrawal
Simulate a cardholder withdrawing cash from an ATM with a sandbox physical card. Column receives it as an ATM
cash withdrawal authorization: the card's magnetic stripe is read, the cardholder enters cardholder_input.pin,
and the ATM has merchant category code 6011. The resulting card transaction has type cash_withdrawal and
point_of_sale_details.terminal_type atm, and holds the cash until it is captured. Virtual cards can't be used
at an ATM. The cardholder is always billed in USD; when merchant_currency is not USD, provide
cardholder_fx_rate, and set merchant_country_code to simulate an international ATM.
Column checks the PIN with its real PIN verification and lockout, so a wrong PIN declines with pin_invalid, a
card with no PIN with pin_not_set, and a card whose PIN is blocked after 3 wrong PINs with pin_blocked.
When realtime_decision is not set, Column sends a real-time authorization decision request to your endpoint
subscribed to decision.issuing.card_transaction, and declines if none is configured. Set realtime_decision
to supply the decision without calling your endpoint.
To settle the withdrawal, simulate a capture of the full amount. To simulate an ATM that dispenses less cash than
was authorized, simulate a reversal with the cardholder_amount that wasn't dispensed before capturing the
rest; reverse in full when the ATM dispenses nothing.
Path Parameters
card_id
stringRequiredUnique identifier for the card.
Body Parameters
cardholder_amount
numberRequiredCash the cardholder withdraws, in the ATM's currency, expressed in the smallest currency unit.
For example, 10000 represents 100.00 EUR. When merchant_currency is not USD, this amount is
multiplied by cardholder_fx_rate to derive the USD billing amount. Must not exceed 999999999999.
cardholder_fx_rate
stringOptionalForeign exchange rate to convert from the ATM's currency to USD (cardholder billing currency),
as a decimal string. Required when merchant_currency is not USD.
For example, if merchant_currency is EUR and cardholder_fx_rate is "1.10",
a 100.00 EUR withdrawal will result in a 110.00 USD cardholder charge.
cardholder_input
objectRequiredWhat the cardholder enters at the ATM. Column's real PIN verification checks it against the card, so the outcome is the one a real withdrawal would get.
pin
stringRequiredThe PIN the cardholder types on the ATM's PIN pad, as 4 to 12 digits in plaintext. Sandbox only: the simulator encrypts it the way an ATM would, and Column verifies it against the card's PIN.
- The PIN matches: PIN verification passes and the withdrawal continues to decisioning.
- The PIN doesn't match: the withdrawal is declined with
decision_reasonpin_invalidand
decision_source column. 3 wrong PINs in a row block the card's PIN.
- The card has no PIN set: declined with
pin_not_set. - The card's PIN is blocked: declined with
pin_blocked, whatever the PIN, until you unblock it with
POST /issuing/cards/\{card_id\}/pin/unblock.
merchant_city
stringOptionalOptional ATM city to put on the simulated message (Field 43, positions 26-38).
Defaults to CITY NAME. At most 13 characters.
merchant_country_code
stringOptionalOptional ATM country, ISO 3166-1 alpha-2, to put on the simulated message (Field 43,
positions 39-40). Defaults to US. Use it to test domestic and international ATM withdrawals.
merchant_currency
stringRequiredCurrency the ATM dispenses, in ISO 4217 format.
merchant_name
stringOptionalOptional ATM owner name to put on the simulated message (Field 43, positions 1-25).
Defaults to SANDBOX ATM. At most 25 characters.
realtime_decision
enumOptionalSpecifies the issuer's real-time authorization decision to inject if the withdrawal reaches the real-time decisioning step.
approve— the issuer approves the withdrawal.decline— the issuer declines the withdrawal (seerealtime_decision_reason).
ATMs dispense the requested amount or nothing, so partial approval is not supported.
When realtime_decision is not provided, the simulator attempts a real real-time authorization
decision webhook to the platform's configured decision.issuing.card_transaction destination
(declining if no destination is configured).
realtime_decision_reason
stringOptionalThe reason for the issuer's real-time decline decision. Only applicable when
realtime_decision is decline. Defaults to generic_decline if not specified.
realtime_funding_account_id
stringOptionalThe bank account to just-in-time fund the withdrawal from, as a platform's real-time authorization
decision would name in funding_account_id. Only applicable when realtime_decision is approve,
and only on debit card programs with jit_funding_enabled.