Cards

Simulate card 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.

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

Request

  • Base URL: https://api.column.com
  • URL: https://api.column.com/simulate/issuing/cards/{card_id}/card-transactions/authorization
  • Auth: HTTP basic

Path parameters

card_idstring required

Request body

cardholder_amountinteger required

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_ratestring

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.

merchant_category_codestring

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_citystring

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_codestring

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_currencystring required

Merchant's currency code in ISO 4217 format.

merchant_namestring

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_reasonstring

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'approved' | 'declined'

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'approve' | 'decline' | 'partially_approve'

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_reasonstring

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_idstring

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_amountinteger

The amount to partially approve, expressed in the smallest currency unit. Required when realtime_decision is partially_approve, and must be less than the requested cardholder_amount.

three_ds_attempt_idstring

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.

Example request

{
  "cardholder_amount": 1000,
  "cardholder_fx_rate": "1.10",
  "merchant_category_code": "5812",
  "merchant_city": "OAKLAND",
  "merchant_country_code": "CA",
  "merchant_currency": "EUR",
  "merchant_name": "BLUE BOTTLE COFFEE",
  "network_decision_reason": "insufficient_funds",
  "realtime_decision_reason": "insufficient_funds",
  "realtime_funding_account_id": "bacc_2x8gszy5folpA9s0TOCseE9ABDM",
  "realtime_partially_approved_amount": 50,
  "three_ds_attempt_id": "tdsa_2x8gszy5folpA9s0TOCseE9ABDM"
}

Response

Successful response

authorization_expires_atstring date-time nullable

The authorization expiration date of the card transaction. Funds will be released from any authorization after this date

card_account_idstring required

The ID of the card account

card_idstring required

The ID of the card

card_program_idstring required

The ID of the card program

card_token_idstring nullable

The card token used for this transaction, if applicable.

created_atstring date-time required

The creation date of the card transaction

idstring required

The ID of the card transaction

network_transaction_idstring nullable

The transaction ID assigned by the card network

original_card_transaction_idstring nullable

The ID of the original card transaction referenced by the transaction

type'unknown' | 'purchase' | 'cash_withdrawal' | 'quasi_cash' | 'account_funding' | 'bill_payment' | 'adjustment' | 'refund' | 'original_credit' | 'balance_inquiry' | 'account_verification' required

The kind of card transaction, set from the card network processing code when the transaction is created. Unlike event_type, which describes each step of the transaction lifecycle, the type does not change. Combine it with point_of_sale_details.terminal_type to distinguish, for example, an ATM withdrawal (cash_withdrawal at an atm) from a cash advance at a bank teller. unknown is returned when the network did not identify the kind. Possible values: unknown, purchase, cash_withdrawal, quasi_cash, account_funding, bill_payment, adjustment, refund, original_credit, balance_inquiry, account_verification

Example response

{
  "authentication_details": {
    "three_ds_attempt_id": "tdsa_2x8gszy5folpA9s0TOCseE9ABDM"
  },
  "card_acceptor_details": {
    "acquiring_institution_country_code": "US",
    "country_code": "US",
    "name": "Yellen Cocktails, LLC"
  },
  "card_account_id": "cacc_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_id": "card_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_program_id": "cpgm_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_token_id": "ctkn_2x8gszy5folpA9s0TOCseE9ABDM",
  "events": [
    {
      "amounts": {
        "cardholder_authorized": {
          "amount": 12345,
          "currency_code": "USD",
          "fx_rate": "1.0842"
        },
        "cardholder_requested": {
          "amount": 12345,
          "currency_code": "USD",
          "fx_rate": "1.0842"
        },
        "cardholder_settled": {
          "amount": 12345,
          "currency_code": "USD",
          "fx_rate": "1.0842"
        },
        "merchant_authorized": {
          "amount": 12345,
          "currency_code": "USD",
          "fx_rate": "1.0842"
        },
        "merchant_requested": {
          "amount": 12345,
          "currency_code": "USD",
          "fx_rate": "1.0842"
        },
        "merchant_settled": {
          "amount": 12345,
          "currency_code": "USD",
          "fx_rate": "1.0842"
        }
      },
      "authentication_attempt_id": "caat_2x8gszy5folpA9s0TOCseE9ABDM",
      "card_account_id": "cacc_2x8gszy5folpA9s0TOCseE9ABDM",
      "card_id": "card_2x8gszy5folpA9s0TOCseE9ABDM",
      "card_program_id": "cpgm_2x8gszy5folpA9s0TOCseE9ABDM",
      "card_token_id": "ctkn_2x8gszy5folpA9s0TOCseE9ABDM",
      "decisioning_details": {
        "card_authorization_policy_evaluations": [
          {
            "card_authorization_policy_id": "caup_2x8gszy5folpA9s0TOCseE9ABDM",
            "card_authorization_policy_version_id": "cauv_2x8gszy5folpA9s0TOCseE9ABDM"
          }
        ],
        "funding_account_id": "bacc_2x8gszy5folpA9s0TOCseE9ABDM",
        "realtime_authorization_decision": "approve"
      },
      "id": "ctxe_2x8gszy5folpA9s0TOCseE9ABDM"
    }
  ],
  "fee_details": {
    "transaction_fee_currency": "USD"
  },
  "funding_details": {
    "currency_code": "USD",
    "funded_amount": 2500,
    "funding_account_id": "bacc_2x8gszy5folpA9s0TOCseE9ABDM"
  },
  "id": "ctxn_2x8gszy5folpA9s0TOCseE9ABDM",
  "network_details": {
    "network_fraud_score": 12,
    "network_identifier": "visa"
  },
  "network_transaction_id": "305123456789012",
  "original_card_transaction_id": "ctxn_2x8gszy5folpA9s0TOCseE9ABDM",
  "point_of_sale_details": {
    "card_presence": "present",
    "cardholder_presence": "present",
    "pan_entry_mode": "contactless_chip",
    "terminal_type": "atm",
    "transaction_initiator": "cardholder"
  },
  "recurring_transaction_details": {
    "recurring_original_transaction_id": "ctxn_2x8gszy5folpA9s0TOCseE9ABDM"
  },
  "total_amounts": {
    "cardholder_authorized": {
      "amount": 12345,
      "currency_code": "USD",
      "fx_rate": "1.0842"
    },
    "cardholder_settled": {
      "amount": 12345,
      "currency_code": "USD",
      "fx_rate": "1.0842"
    },
    "merchant_authorized": {
      "amount": 12345,
      "currency_code": "USD",
      "fx_rate": "1.0842"
    },
    "merchant_settled": {
      "amount": 12345,
      "currency_code": "USD",
      "fx_rate": "1.0842"
    }
  },
  "transaction_details": {
    "account_funding_data": {
      "payment_facilitator_name": "Acme Payments",
      "type": "account_to_account"
    },
    "fleet": {
      "fleet_fuel_information": {
        "quantity": "12.5",
        "unit_price": "3.65"
      },
      "item_sequence_number": 1,
      "motor_fuel_information": {
        "quantity": "12.5",
        "unit_price": "3.65"
      },
      "motor_fuel_service_type": "S",
      "odometer": "45210",
      "prompted_data": [
        {
          "prompt_code": "ODOM",
          "value": "45210"
        }
      ],
      "pump_number": "04"
    },
    "invoice_line_items": [
      {
        "debit_credit_indicator": "D",
        "extended_item_amount": "25.00",
        "fleet_extended_item_amount": "45.63",
        "fleet_item_description": "Unleaded fuel",
        "fleet_item_quantity": "12.5",
        "fleet_item_unit_of_measure": "GLL",
        "fleet_product_code": "001",
        "item_sequence_number": 1,
        "line_item_total": 2500,
        "quantity": "2",
        "unit_cost": "12.50",
        "vat_tax_rate": "8.25"
      }
    ],
    "invoice_summary": {
      "acceptor_tax_id": "12-3456789",
      "acceptor_type": "01",
      "item_sequence_number": 1
    },
    "lodging_data": {
      "daily_room_rate": 18900,
      "food_beverage_charges": 3000,
      "room_nights": 2,
      "total_charged": 44202,
      "total_charges": 44202,
      "total_non_room_charges": 3000,
      "total_room_tax": 3402,
      "total_tax": 3402
    },
    "original_credit_data": {
      "type": "person_to_person"
    },
    "travel_itinerary": {
      "item_sequencing_field": "1",
      "passenger_name": "Oliver Hockey"
    },
    "travel_legs": [
      {
        "control_id": "CTL0001",
        "item_sequencing_field": "1"
      }
    ]
  },
  "type": "purchase"
}

Changes

No recorded changes to this operation across all 1 revision of this API.