Simulate card authorization

POST/simulate/issuing/cards/{card_id}/card-transactions/authorization

Simulate a card authorization for a sandbox card. The cardholder is always billed in USD; when merchant_currency is not USD, provide cardholder_fx_rate.

When neither realtime_decision nor network_standin is 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, or network_standin to simulate the card network deciding on your behalf. To attach 3DS authentication details, pass an authenticated three_ds_attempt_id for the same card.

To test PIN outcomes on a physical card, pass the PIN the cardholder enters in cardholder_input.pin. Column checks it 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.

To test card-present and card-not-present decisioning, set entry_mode to swipe, keyed or ecommerce. By default a physical card is swiped and a virtual card is used at an online checkout. Virtual cards only support ecommerce, and a PIN can't be entered with ecommerce.

To test CVV2 outcomes, pass the CVV2 the cardholder enters in cardholder_input.cvv2 with entry_mode keyed or ecommerce (a virtual card's default). Column checks it with its real CVV2 verification, so a wrong CVV2 declines with invalid_cvv2. When omitted, the card's real CVV2 is sent. A swiped card carries no CVV2.

To test expiration date outcomes, pass the date the cardholder presents in cardholder_input.expiration_date. Column compares it with the card's expiration, so a date that doesn't match declines with invalid_expiration. Without it, the simulated transaction carries no expiration date and Column skips the check.

To test address verification (AVS), pass the billing address the cardholder enters in cardholder_input.billing_address. Column compares it with the cardholder entity's address and reports each field as verified or invalid in the transaction's cardholder_verification_details. AVS doesn't decline the authorization by itself.

Path Parameters

card_id

stringRequired

Unique identifier for the card.

Body Parameters

cardholder_amount

numberRequired

Transaction amount in the merchant's currency, expressed in the smallest currency unit. For example, 1000 represents 10.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 merchant 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 10.00 EUR transaction will result in an 11.00 USD cardholder charge.

cardholder_input

objectOptional

What the cardholder enters at the terminal or online checkout. Column's real verification checks each input against the card, so the outcome is the one a real transaction would get.

billing_address

objectOptional

The billing address the cardholder enters, for example at checkout or at a fuel pump. The simulator sends it in the Visa address verification (AVS) fields, and Column's real AVS check compares each field with the cardholder entity's address. The results appear in the card transaction's cardholder_verification_details as street_address_verification_status and postal_code_verification_status: verified when the field matches, invalid when it doesn't, and not_provided when it is omitted. AVS is informational: a mismatch does not decline the authorization, and the merchant decides what to do with the result.

postal_code

stringOptional

The postal code, as 1 to 9 letters, digits, spaces or hyphens. Send a US ZIP+4 as 9 digits without the hyphen, for example 941051234. A 5-digit ZIP matches a ZIP+4 on file with the same first 5 digits.

street

stringOptional

The street address line, as 1 to 40 printable ASCII characters. AVS compares the digits in the address (the house number, plus any unit number), so 123 Main St matches an address on file of 123 Main Street.

cvv2

stringOptional

The CVV2 the cardholder types at an online checkout or a keyed terminal, as 3 or 4 digits. Column verifies it against the card's CVV2.

The CVV2 matches: CVV2 verification passes and the transaction continues to decisioning.
The CVV2 doesn't match: the transaction is declined with decision_reason invalid_cvv2 and

decision_source column.

Only supported when the card is keyed or used online: entry_mode keyed or ecommerce, which is a virtual card's default. A swiped card, a physical card's default, carries no CVV2, so cvv2 is rejected. When omitted, a keyed or online transaction carries the card's real CVV2.

expiration_date

objectOptional

The expiration date the cardholder presents, which the simulator sends in the message (Field 14). Column compares it with the card's expiration_month and expiration_year.

The date matches the card's: expiration verification passes and the transaction continues to decisioning.
The date doesn't match: the transaction is declined with decision_reason invalid_expiration and

decision_source column.

Omit it to send no expiration date, in which case Column skips the check. A card past its own expiration declines with card_expired whatever date is presented.

month

integerRequired

The expiration month (1-12).

year

integerRequired

The expiration year, as a 4-digit year from 2000 to 2068. Field 14 carries only the last two digits, which decode to 2000-2068 (00-68) or 1969-1999 (69-99), so later years can't be presented.

stringOptional

The PIN the cardholder types on the terminal's PIN pad, as 4 to 12 digits in plaintext. Sandbox only: the simulator encrypts it the way a terminal would, and Column verifies it against the card's PIN.

The PIN matches: PIN verification passes and the transaction continues to decisioning.
The PIN doesn't match: the transaction 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.

Not supported for virtual cards, which have no terminal.

entry_mode

enumOptional

How the card is presented to the merchant, which sets the simulated message's PAN entry mode (Field 22) and POS condition code (Field 25). Use it to test card-present and card-not-present decisioning. Defaults to swipe for physical cards and ecommerce for virtual cards.

swipe: the physical card's magnetic stripe is read at an attended terminal. The message carries the

card's track data, which Column verifies.

keyed: the physical card's number is typed into the terminal by hand. The message carries no track

data, and carries the card's CVV2.

ecommerce: the card is used at an online checkout. The message carries no track data, and carries the

card's CVV2.

Virtual cards only support ecommerce, and cardholder_input.pin is not supported with ecommerce. Chip and contactless entry are not supported, because they need an EMV cryptogram the simulator cannot generate under sandbox card keys.

merchant_category_code

stringOptional

Optional merchant category code (ISO 18245 MCC) to put on the simulated message (Field 18), for example 5812 (restaurants) or 6011 (ATM). Defaults to 5999. Use it to exercise real-time decisioning rules that depend on the merchant category.

merchant_city

stringOptional

Optional card acceptor 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 card acceptor country, ISO 3166-1 alpha-2, to put on the simulated message (Field 43, positions 39-40). Defaults to US. Use it to exercise country-based decisioning rules.

merchant_currency

stringRequired

Merchant's currency code in ISO 4217 format.

merchant_name

stringOptional

Optional card acceptor name to put on the simulated message (Field 43, positions 1-25). Defaults to ACQUIRER NAME. At most 25 characters.

network_decision_reason

stringOptional

The reason for the network's decline decision. Only applicable when network_standin is declined. Determines the network response code on the transaction. Defaults to generic_decline if not specified.

network_standin

enumOptional

Simulates a scenario where the card network makes the authorization decision on behalf of the issuer (e.g., due to issuer timeout). When set, the resulting transaction will have decision_source set to card_network.

approved — the network approves the transaction.
declined — the network declines the transaction.

realtime_decision

enumOptional

Specifies the issuer's real-time authorization decision to inject if the transaction reaches the real-time decisioning step. Mutually exclusive with network_standin.

approve — the issuer approves the transaction.
decline — the issuer declines the transaction (see realtime_decision_reason).
partially_approve — the issuer partially approves the transaction

(requires realtime_partially_approved_amount).

When neither realtime_decision nor network_standin is 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 authorization from, as a platform's real-time authorization decision would name in funding_account_id. Only applicable when realtime_decision is approve or partially_approve, and only on debit card programs with jit_funding_enabled.

realtime_partially_approved_amount

numberOptional

The amount to partially approve, in the smallest unit of the cardholder billing currency (USD). Required when realtime_decision is partially_approve, and must be less than the amount billed to the cardholder: cardholder_amount when merchant_currency is USD, or cardholder_amount converted at cardholder_fx_rate otherwise.

three_ds_attempt_id

stringOptional

Optional 3DS attempt ID to link to this authorization. The 3DS attempt must be in authenticated status and belong to the same card. When provided, the authorization will include authentication details with liability shift.