Sign in

v4

OpenAPI 3.1.02026-08-012402353.8 MB

Sandbox: Create a Card Balance Inquiry

Simulates a balance inquiry on a Card.

post/simulations/card_balance_inquiries

Request body

balanceinteger

The balance amount in cents. The account balance will be used if not provided.

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

{
  "balance": 1000000,
  "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": "CITIBANK",
  "merchant_state": "NY"
}

Response

Card Payment

account_idstring required

The identifier for the Account the Transaction belongs to.

card_idstring required

The Card identifier for this payment.

created_atstring date-time required

The ISO 8601 time at which the Card Payment was created.

digital_wallet_token_idstring nullable required

The Digital Wallet Token identifier for this payment.

idstring required

The Card Payment identifier.

physical_card_idstring nullable required

The Physical Card identifier for this payment.

type'card_payment' required

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

Example response

{
  "account_id": "account_in71c4amph0vgo2qllky",
  "card_id": "card_oubs0hwk5rn6knuecxg2",
  "created_at": "2020-01-31T23:59:59Z",
  "digital_wallet_token_id": null,
  "elements": [
    {
      "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",
      "created_at": "2020-01-31T23:59:59Z"
    },
    {
      "card_reversal": {
        "card_authorization_id": "card_authorization_6iqxap6ivd0fo5eu3i8x",
        "currency": "USD",
        "id": "card_reversal_8vr9qy60cgf5d0slpb68",
        "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": "visa",
        "network_identifiers": {
          "authorization_identification_response": null,
          "retrieval_reference_number": "785867080153",
          "trace_number": "487941",
          "transaction_id": "627199945183184"
        },
        "pending_transaction_id": "pending_transaction_k1sfetcau2qbvjbzgju4",
        "presentment_currency": "USD",
        "reversal_amount": 20,
        "reversal_presentment_amount": 20,
        "reversal_reason": "reversed_by_customer",
        "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_reversal",
        "updated_authorization_amount": 80,
        "updated_authorization_presentment_amount": 80
      },
      "category": "card_reversal",
      "created_at": "2020-01-31T23:59:59Z"
    },
    {
      "card_increment": {
        "actioner": "increase",
        "additional_amounts": {
          "clinic": null,
          "dental": null,
          "original": null,
          "prescription": null,
          "surcharge": null,
          "total_cumulative": null,
          "total_healthcare": null,
          "transit": null,
          "unknown": null,
          "vision": null
        },
        "amount": 20,
        "card_authorization_id": "card_authorization_6iqxap6ivd0fo5eu3i8x",
        "currency": "USD",
        "id": "card_increment_6ztayc58j1od0rpebp3e",
        "network": "visa",
        "network_identifiers": {
          "authorization_identification_response": null,
          "retrieval_reference_number": "785867080153",
          "trace_number": "487941",
          "transaction_id": "627199945183184"
        },
        "network_risk_score": 10,
        "pending_transaction_id": "pending_transaction_k1sfetcau2qbvjbzgju4",
        "presentment_amount": 20,
        "presentment_currency": "USD",
        "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"
          }
        ],
        "type": "card_increment",
        "updated_authorization_amount": 120
      },
      "category": "card_increment",
      "created_at": "2020-01-31T23:59:59Z"
    },
    {
      "card_settlement": {
        "amount": 100,
        "card_authorization": null,
        "card_payment_id": "card_payment_nd3k2kacrqjli8482ave",
        "cashback": null,
        "currency": "USD",
        "id": "card_settlement_khv5kfeu0vndj291omg6",
        "interchange": {
          "amount": "0.137465",
          "code": "271",
          "currency": "USD"
        },
        "merchant_acceptor_id": "5665270011000168",
        "merchant_category_code": "5734",
        "merchant_city": "New York",
        "merchant_country": "US",
        "merchant_name": "AMAZON.COM",
        "merchant_postal_code": "10045",
        "merchant_state": "NY",
        "network": "visa",
        "network_identifiers": {
          "acquirer_business_id": "69650702",
          "acquirer_reference_number": "83163715445437604865089",
          "authorization_identification_response": "ABC123",
          "transaction_id": "627199945183184"
        },
        "pending_transaction_id": null,
        "presentment_amount": 100,
        "presentment_currency": "USD",
        "purchase_details": {
          "car_rental": null,
          "customer_reference_identifier": "51201",
          "local_tax_amount": null,
          "local_tax_currency": "usd",
          "lodging": {
            "check_in_date": "2023-07-20",
            "daily_room_rate_amount": 1000,
            "daily_room_rate_currency": "usd",
            "extra_charges": "restaurant",
            "folio_cash_advances_amount": 0,
            "folio_cash_advances_currency": "usd",
            "food_beverage_charges_amount": 0,
            "food_beverage_charges_currency": "usd",
            "no_show_indicator": "no_show",
            "prepaid_expenses_amount": 0,
            "prepaid_expenses_currency": "usd",
            "room_nights": 1,
            "total_room_tax_amount": 100,
            "total_room_tax_currency": "usd",
            "total_tax_amount": 100,
            "total_tax_currency": "usd"
          },
          "national_tax_amount": null,
          "national_tax_currency": "usd",
          "purchase_identifier": "10203",
          "purchase_identifier_format": "order_number",
          "travel": 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"
          }
        ],
        "surcharge": null,
        "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
        "type": "card_settlement"
      },
      "category": "card_settlement",
      "created_at": "2020-01-31T23:59:59Z"
    }
  ],
  "id": "card_payment_nd3k2kacrqjli8482ave",
  "physical_card_id": null,
  "state": {
    "authorized_amount": 100,
    "fuel_confirmed_amount": 0,
    "incremented_amount": 20,
    "refund_authorized_amount": 0,
    "refunded_amount": 0,
    "reversed_amount": 20,
    "settled_amount": 100
  },
  "type": "card_payment"
}