Simulation
Simulate full financial transaction
Simulate a full financial transaction for a sandbox card. Full financial transactions capture funds immediately without
a prior authorization hold, as with transit taps, low-value purchases, and offline transactions. The cardholder is
always billed in USD; when merchant_currency is not USD, provide cardholder_fx_rate.
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 test PIN outcomes on a PIN debit purchase with 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.
On a virtual card, cardholder_input.cvv2 sets the CVV2 the cardholder enters, and a wrong CVV2 declines with
invalid_cvv2.
cardholder_input.expiration_date sets the expiration date the cardholder presents, and a date that doesn't match
the card's declines with invalid_expiration.
To test address verification (AVS), pass the billing address the cardholder enters in
cardholder_input.billing_address, as on an authorization. AVS doesn't decline the transaction by itself.
Path Parameters
card_id
stringRequiredUnique identifier for the card.
Body Parameters
cardholder_amount
numberRequiredTransaction 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
stringOptionalForeign 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
objectOptionalWhat 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
objectOptionalThe 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
stringOptionalThe 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
stringOptionalThe 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
stringOptionalThe 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_reasoninvalid_cvv2and
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
objectOptionalThe 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_reasoninvalid_expirationand
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
integerRequiredThe expiration month (1-12).
year
integerRequiredThe 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.
pin
stringOptionalThe 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_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.
Not supported for virtual cards, which have no terminal.
merchant_category_code
stringOptionalOptional 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
stringOptionalOptional 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
stringOptionalOptional 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
stringRequiredMerchant's currency code in ISO 4217 format.
merchant_name
stringOptionalOptional card acceptor name to put on the simulated message (Field 43, positions 1-25).
Defaults to ACQUIRER NAME. At most 25 characters.
realtime_decision
enumOptionalSpecifies the issuer's real-time authorization decision to inject if the transaction reaches the real-time decisioning step.
approve— the issuer approves the transaction.decline— the issuer declines the transaction (seerealtime_decision_reason).partially_approve— the issuer partially approves the transaction
(requires realtime_partially_approved_amount).
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 transaction 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
numberOptionalThe 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.