Docs
Guides
Explanatory and how-to content
API Reference
Technical documentation
Changelog
Release notes
Dashboard
Manage your account
Status
Service status
API Reference
Card Payments

Card Payments group together interactions related to a single card payment, such as an authorization and its corresponding settlement.

The Card Payment object
{
  "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",
        "amount": 100,
        "card_payment_id": "card_payment_nd3k2kacrqjli8482ave",
        "currency": "USD",
        "digital_wallet_token_id": null,
        "direction": "settlement",
        "expires_at": "2020-01-31T23:59:59Z",
        "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",
          "visa": {
            "electronic_commerce_indicator": "secure_electronic_commerce",
            "point_of_service_entry_mode": "manual",
            "stand_in_processing_reason": null
          }
        },
        "network_identifiers": {
          "retrieval_reference_number": "785867080153",
          "trace_number": "487941",
          "transaction_id": "627199945183184"
        },
        "network_risk_score": 10,
        "pending_transaction_id": null,
        "physical_card_id": null,
        "presentment_amount": 100,
        "presentment_currency": "USD",
        "processing_category": "purchase",
        "real_time_decision_id": null,
        "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"
          }
        }
      },
      "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": {
          "retrieval_reference_number": "785867080153",
          "trace_number": "487941",
          "transaction_id": "627199945183184"
        },
        "pending_transaction_id": "pending_transaction_k1sfetcau2qbvjbzgju4",
        "reversal_amount": 20,
        "reversal_reason": "reversed_by_customer",
        "terminal_id": "RCN5VNXS",
        "type": "card_reversal",
        "updated_authorization_amount": 80
      },
      "category": "card_reversal",
      "created_at": "2020-01-31T23:59:59Z"
    },
    {
      "card_increment": {
        "actioner": "increase",
        "amount": 20,
        "card_authorization_id": "card_authorization_6iqxap6ivd0fo5eu3i8x",
        "currency": "USD",
        "id": "card_increment_6ztayc58j1od0rpebp3e",
        "network": "visa",
        "network_identifiers": {
          "retrieval_reference_number": "785867080153",
          "trace_number": "487941",
          "transaction_id": "627199945183184"
        },
        "network_risk_score": 10,
        "pending_transaction_id": "pending_transaction_k1sfetcau2qbvjbzgju4",
        "real_time_decision_id": null,
        "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_identifiers": {
          "acquirer_business_id": "69650702",
          "acquirer_reference_number": "83163715445437604865089",
          "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
        },
        "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,
    "reversed_amount": 20,
    "settled_amount": 100
  },
  "type": "card_payment"
}
Attributes
account_id
string

The identifier for the Account the Transaction belongs to.

card_id
string

The Card identifier for this payment.

created_at
string

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

digital_wallet_token_id
string
Nullable

The Digital Wallet Token identifier for this payment.

elements
array

The interactions related to this card payment.

id
string

The Card Payment identifier.

physical_card_id
string
Nullable

The Physical Card identifier for this payment.

state
dictionary

The summarized state of this card payment.

type
string

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

List Card Payments
curl \
  --url "${INCREASE_URL}/card_payments?account_id=account_in71c4amph0vgo2qllky" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
cursor
string

Return the page of entries after this one.

limit
integer

Limit the size of the list that is returned. The default (and maximum) is 100 objects.

account_id
string

Filter Card Payments to ones belonging to the specified Account.

card_id
string

Filter Card Payments to ones belonging to the specified Card.

created_at.after
string

Return results after this ISO 8601 timestamp.

created_at.before
string

Return results before this ISO 8601 timestamp.

created_at.on_or_after
string

Return results on or after this ISO 8601 timestamp.

created_at.on_or_before
string

Return results on or before this ISO 8601 timestamp.

Retrieve a Card Payment
curl \
  --url "${INCREASE_URL}/card_payments/card_payment_nd3k2kacrqjli8482ave" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
card_payment_id
string
Required

The identifier of the Card Payment.

Sandbox: Expire a Card Authorization

Simulates expiring a Card Authorization immediately.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_authorization_expirations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "card_payment_id": "card_payment_nd3k2kacrqjli8482ave"
  }'
Parameters
card_payment_id
string
Required

The identifier of the Card Payment to expire.

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.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_authorizations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "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"
  }'
Returns a Inbound Card Authorization Simulation Result object:
{
  "declined_transaction": null,
  "pending_transaction": {
    "account_id": "account_in71c4amph0vgo2qllky",
    "amount": 100,
    "balance_impact": "affects_available_balance",
    "completed_at": null,
    "created_at": "2020-01-31T23:59:59Z",
    "currency": "USD",
    "description": "INVOICE 2468",
    "id": "pending_transaction_k1sfetcau2qbvjbzgju4",
    "route_id": "card_oubs0hwk5rn6knuecxg2",
    "route_type": "card",
    "source": {
      "card_authorization": {
        "actioner": "increase",
        "amount": 100,
        "card_payment_id": "card_payment_nd3k2kacrqjli8482ave",
        "currency": "USD",
        "digital_wallet_token_id": null,
        "direction": "settlement",
        "expires_at": "2020-01-31T23:59:59Z",
        "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",
          "visa": {
            "electronic_commerce_indicator": "secure_electronic_commerce",
            "point_of_service_entry_mode": "manual",
            "stand_in_processing_reason": null
          }
        },
        "network_identifiers": {
          "retrieval_reference_number": "785867080153",
          "trace_number": "487941",
          "transaction_id": "627199945183184"
        },
        "network_risk_score": 10,
        "pending_transaction_id": null,
        "physical_card_id": null,
        "presentment_amount": 100,
        "presentment_currency": "USD",
        "processing_category": "purchase",
        "real_time_decision_id": null,
        "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"
          }
        }
      },
      "category": "card_authorization"
    },
    "status": "pending",
    "type": "pending_transaction"
  },
  "type": "inbound_card_authorization_simulation_result"
}
Parameters
amount
integer
Required

The authorization amount in cents.

authenticated_card_payment_id
string

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

card_id
string

The identifier of the Card to be authorized.

decline_reason
enum

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

digital_wallet_token_id
string

The identifier of the Digital Wallet Token to be authorized.

event_subscription_id
string

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_id
string

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

200 character maximum
merchant_category_code
string

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

200 character maximum
merchant_city
string

The city the merchant resides in.

200 character maximum
merchant_country
string

The country the merchant resides in.

200 character maximum
merchant_descriptor
string

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

200 character maximum
merchant_state
string

The state the merchant resides in.

200 character maximum
network_details
dictionary

Fields specific to a given card network.

network_risk_score
integer

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_id
string

The identifier of the Physical Card to be authorized.

processing_category
dictionary

Fields specific to a specific type of authorization, such as Automatic Fuel Dispensers, Refund Authorizations, or Cash Disbursements.

terminal_id
string

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

200 character maximum
Sandbox: Confirm the fuel pump amount for a Card Authorization

Simulates the fuel confirmation of an authorization by a card acquirer. This happens asynchronously right after a fuel pump transaction is completed. A fuel confirmation can only happen once per authorization.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_fuel_confirmations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "amount": 5000,
    "card_payment_id": "card_payment_nd3k2kacrqjli8482ave"
  }'
Parameters
amount
integer
Required

The amount of the fuel_confirmation in minor units in the card authorization's currency.

card_payment_id
string
Required

The identifier of the Card Payment to create a fuel_confirmation on.

Sandbox: Increment a Card Authorization

Simulates the increment of an authorization by a card acquirer. An authorization can be incremented multiple times.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_increments" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "amount": 500,
    "card_payment_id": "card_payment_nd3k2kacrqjli8482ave"
  }'
Parameters
amount
integer
Required

The amount of the increment in minor units in the card authorization's currency.

card_payment_id
string
Required

The identifier of the Card Payment to create a increment on.

event_subscription_id
string

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.

Sandbox: Refund a card transaction

Simulates refunding a card transaction. The full value of the original sandbox transaction is refunded.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_refunds" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "transaction_id": "transaction_uyrp7fld2ium70oa7oi"
  }'
Returns a Transaction object:
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "amount": 100,
  "created_at": "2020-01-31T23:59:59Z",
  "currency": "USD",
  "description": "INVOICE 2468",
  "id": "transaction_uyrp7fld2ium70oa7oi",
  "route_id": "account_number_v18nkfqm6afpsrvy82b2",
  "route_type": "account_number",
  "source": {
    "category": "inbound_ach_transfer",
    "inbound_ach_transfer": {
      "addenda": null,
      "amount": 100,
      "originator_company_descriptive_date": null,
      "originator_company_discretionary_data": null,
      "originator_company_entry_description": "RESERVE",
      "originator_company_id": "0987654321",
      "originator_company_name": "BIG BANK",
      "receiver_id_number": "12345678900",
      "receiver_name": "IAN CREASE",
      "trace_number": "021000038461022",
      "transfer_id": "inbound_ach_transfer_tdrwqr3fq9gnnq49odev"
    }
  },
  "type": "transaction"
}
Parameters
transaction_id
string
Required

The identifier for the Transaction to refund. The Transaction's source must have a category of card_settlement.

Sandbox: Reverse a Card Authorization

Simulates the reversal of an authorization by a card acquirer. An authorization can be partially reversed multiple times, up until the total authorized amount. Marks the pending transaction as complete if the authorization is fully reversed.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_reversals" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "card_payment_id": "card_payment_nd3k2kacrqjli8482ave"
  }'
Parameters
amount
integer

The amount of the reversal in minor units in the card authorization's currency. This defaults to the authorization amount.

card_payment_id
string
Required

The identifier of the Card Payment to create a reversal on.

Sandbox: Settle a Card Authorization

Simulates the settlement of an authorization by a card acquirer. After a card authorization is created, the merchant will eventually send a settlement. This simulates that event, which may occur many days after the purchase in production. The amount settled can be different from the amount originally authorized, for example, when adding a tip to a restaurant bill.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_settlements" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "card_id": "card_oubs0hwk5rn6knuecxg2",
    "pending_transaction_id": "pending_transaction_k1sfetcau2qbvjbzgju4"
  }'
Returns a Transaction object:
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "amount": 100,
  "created_at": "2020-01-31T23:59:59Z",
  "currency": "USD",
  "description": "INVOICE 2468",
  "id": "transaction_uyrp7fld2ium70oa7oi",
  "route_id": "account_number_v18nkfqm6afpsrvy82b2",
  "route_type": "account_number",
  "source": {
    "category": "inbound_ach_transfer",
    "inbound_ach_transfer": {
      "addenda": null,
      "amount": 100,
      "originator_company_descriptive_date": null,
      "originator_company_discretionary_data": null,
      "originator_company_entry_description": "RESERVE",
      "originator_company_id": "0987654321",
      "originator_company_name": "BIG BANK",
      "receiver_id_number": "12345678900",
      "receiver_name": "IAN CREASE",
      "trace_number": "021000038461022",
      "transfer_id": "inbound_ach_transfer_tdrwqr3fq9gnnq49odev"
    }
  },
  "type": "transaction"
}
Parameters
amount
integer

The amount to be settled. This defaults to the amount of the Pending Transaction being settled.

card_id
string
Required

The identifier of the Card to create a settlement on.

pending_transaction_id
string
Required

The identifier of the Pending Transaction for the Card Authorization you wish to settle.