Sign in

v4

OpenAPI 3.1.02026-08-012402353.8 MB

Sandbox: Create a Card Authorization

Simulates a purchase authorization on a Card. Depending on the balance available to the card and the amount submitted, the authorization activity will result in a Pending Transaction of type card_authorization or a Declined Transaction of type card_decline. You can pass either a Card id or a Digital Wallet Token id to simulate the two different ways purchases can be made. The response will contain either a pending_transaction or a declined_transaction; the other attribute will be null. If the authorization is declined, the reason is available on the Declined Transaction at source.card_decline.reason.

post/simulations/card_authorizations

Request body

amountinteger required

The authorization amount in cents.

authenticated_card_payment_idstring

The identifier of a Card Payment with a card_authentication if you want to simulate an authenticated authorization.

card_idstring

The identifier of the Card to be authorized.

decline_reason'account_closed' | 'card_not_active' | 'card_canceled' | 'physical_card_not_active' | 'entity_not_active' | 'group_locked' | 'insufficient_funds' | 'cvv2_mismatch' | 'pin_mismatch' | 'card_expiration_mismatch' | 'transaction_not_allowed' | 'breaches_limit' | 'webhook_declined' | 'webhook_timed_out' | 'declined_by_stand_in_processing' | 'invalid_physical_card' | 'missing_original_authorization' | 'invalid_cryptogram' | 'failed_3ds_authentication' | 'suspected_card_testing' | 'suspected_fraud'

Forces a card decline with a specific reason. No real time decision will be sent.

digital_wallet_token_idstring

The identifier of the Digital Wallet Token to be authorized.

event_subscription_idstring

The identifier of the Event Subscription to use. If provided, will override the default real time event subscription. Because you can only create one real time decision event subscription, you can use this field to route events to any specified event subscription for testing purposes.

merchant_acceptor_idstring

The merchant identifier (commonly abbreviated as MID) of the merchant the card is transacting with.

merchant_category_codestring

The Merchant Category Code (commonly abbreviated as MCC) of the merchant the card is transacting with.

merchant_citystring

The city the merchant resides in.

merchant_countrystring

The country the merchant resides in.

merchant_descriptorstring

The merchant descriptor of the merchant the card is transacting with.

merchant_statestring

The state the merchant resides in.

network_risk_scoreinteger

The risk score generated by the card network. For Visa this is the Visa Advanced Authorization risk score, from 0 to 99, where 99 is the riskiest.

physical_card_idstring

The identifier of the Physical Card to be authorized.

terminal_idstring

The terminal identifier (commonly abbreviated as TID) of the terminal the card is transacting with.

Example request

{
  "amount": 1000,
  "card_id": "card_oubs0hwk5rn6knuecxg2",
  "event_subscription_id": "event_subscription_001dzz0r20rcdxgb013zqb8m04g",
  "merchant_acceptor_id": "5665270011000168",
  "merchant_category_code": "5734",
  "merchant_city": "New York",
  "merchant_country": "US",
  "merchant_descriptor": "AMAZON.COM",
  "merchant_state": "NY"
}

Response

Inbound Card Authorization Simulation Result

type'inbound_card_authorization_simulation_result' required

A constant representing the object's type. For this resource it will always be inbound_card_authorization_simulation_result.

Example response

{
  "declined_transaction": null,
  "pending_transaction": {
    "account_id": "account_in71c4amph0vgo2qllky",
    "amount": 100,
    "completed_at": null,
    "created_at": "2020-01-31T23:59:59Z",
    "currency": "USD",
    "description": "INVOICE 2468",
    "held_amount": 100,
    "id": "pending_transaction_k1sfetcau2qbvjbzgju4",
    "route_id": "card_oubs0hwk5rn6knuecxg2",
    "route_type": "card",
    "source": {
      "card_authorization": {
        "actioner": "increase",
        "additional_amounts": {
          "clinic": null,
          "dental": null,
          "original": null,
          "prescription": null,
          "surcharge": {
            "amount": 10,
            "currency": "USD"
          },
          "total_cumulative": null,
          "total_healthcare": null,
          "transit": null,
          "unknown": null,
          "vision": null
        },
        "amount": 100,
        "card_payment_id": "card_payment_nd3k2kacrqjli8482ave",
        "currency": "USD",
        "digital_wallet_token_id": null,
        "direction": "settlement",
        "expires_at": "2020-01-31T23:59:59Z",
        "healthcare": null,
        "id": "card_authorization_6iqxap6ivd0fo5eu3i8x",
        "merchant_acceptor_id": "5665270011000168",
        "merchant_category_code": "5734",
        "merchant_city": "New York",
        "merchant_country": "US",
        "merchant_descriptor": "AMAZON.COM",
        "merchant_postal_code": "10045",
        "merchant_state": "NY",
        "network_details": {
          "category": "visa",
          "pulse": null,
          "visa": {
            "electronic_commerce_indicator": "secure_electronic_commerce",
            "point_of_service_entry_mode": "manual",
            "stand_in_processing_reason": null,
            "terminal_entry_capability": "magnetic_stripe"
          }
        },
        "network_identifiers": {
          "authorization_identification_response": null,
          "retrieval_reference_number": "785867080153",
          "trace_number": "487941",
          "transaction_id": "627199945183184"
        },
        "network_risk_score": 10,
        "original_card_payment_id": null,
        "pending_transaction_id": null,
        "physical_card_id": null,
        "presentment_amount": 100,
        "presentment_currency": "USD",
        "processing_category": "purchase",
        "real_time_decision_id": null,
        "scheme_fees": [
          {
            "amount": "0.137465",
            "created_at": "2020-01-31T23:59:59Z",
            "currency": "USD",
            "fee_type": "visa_corporate_acceptance_fee",
            "fixed_component": null,
            "variable_rate": "0.0002"
          }
        ],
        "terminal_id": "RCN5VNXS",
        "type": "card_authorization",
        "verification": {
          "card_verification_code": {
            "result": "match"
          },
          "cardholder_address": {
            "actual_line1": "33 Liberty Street",
            "actual_postal_code": "94131",
            "provided_line1": "33 Liberty Street",
            "provided_postal_code": "94132",
            "result": "postal_code_no_match_address_match"
          },
          "cardholder_name": null
        }
      },
      "category": "card_authorization"
    },
    "status": "pending",
    "type": "pending_transaction"
  },
  "type": "inbound_card_authorization_simulation_result"
}