# 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` `string` _(required)_ — Unique identifier for the card.

### Body Parameters

- `cardholder_amount` `number` _(required)_ — 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` `string` — 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` `object` _(required)_ — 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` `string` _(required)_ — 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` `string` — 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` `string` — 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` `string` _(required)_ — Currency the ATM dispenses, in ISO 4217 format.
- `merchant_name` `string` — 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` `enum` — 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` `string` — 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` `string` — 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`.

**Request**

```shell
curl 'https://api.column.com/simulate/issuing/cards/<card_id>/card-transactions/atm-withdrawal' \
  -XPOST \
  -u :<YOUR API KEY> \
  -H 'Content-Type: application/json' \
  -d '{
  "cardholder_amount": 10000,
  "merchant_currency": "EUR",
  "cardholder_input": {
    "pin": "1234"
  },
  "realtime_funding_account_id": "bacc_2x8gszy5folpA9s0TOCseE9ABDM",
  "cardholder_fx_rate": "1.10",
  "merchant_city": "PARIS",
  "merchant_country_code": "FR",
  "merchant_name": "FIRST NATIONAL ATM",
  "realtime_decision": "approve",
  "realtime_decision_reason": "insufficient_funds"
}'
```

**Response 200**

```json
{
  "card_account_id": "cacc_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_id": "card_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_program_id": "cpgm_2x8gszy5folpA9s0TOCseE9ABDM",
  "created_at": "2024-01-15T09:30:00Z",
  "id": "ctxn_2x8gszy5folpA9s0TOCseE9ABDM",
  "type": "purchase"
}
```
