Simulation

Simulate ATM withdrawal

POST/simulate/issuing/cards/{card_id}/card-transactions/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

stringRequired

Unique identifier for the card.

Body Parameters

cardholder_amount

numberRequired

Cash 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

stringOptional

Foreign 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

objectRequired

What 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

stringRequired

The 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_reason pin_invalid and

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

stringOptional

Optional ATM city to put on the simulated message (Field 43, positions 26-38). Defaults to CITY NAME. At most 13 characters.

merchant_country_code

stringOptional

Optional 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

stringRequired

Currency the ATM dispenses, in ISO 4217 format.

merchant_name

stringOptional

Optional ATM owner name to put on the simulated message (Field 43, positions 1-25). Defaults to SANDBOX ATM. At most 25 characters.

realtime_decision

enumOptional

Specifies 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 (see realtime_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

stringOptional

The 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

stringOptional

The 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.