Skip to content
OrderCard

Transactions

Charge, authorize and verify vaulted cards, then capture, void and refund.

Updated View as Markdown

Every gateway operation is a transaction with a type: purchase, authorize, capture, void, refund or verify. Captures, voids and refunds are new transactions whose parent is the authorization or purchase they act on, so a payment’s whole history is a small tree you can list with ?parent=.

A transaction’s status is succeeded, declined (the issuer or gateway said no) or failed (the gateway could not process it). The response object carries the gateway’s answer, normalized across gateways: decline codes, AVS and CVV results, the authorization code and the network transaction id. See Declines.

amount is always the total that moved, surcharge included. subtotal_amount, tax_amount and surcharge_amount break it down. Purchases, authorizations and captures also carry a summary of what has been captured, refunded or voided since, and what is left.

The Payments guide walks through the flows.

Charge a card

POST/v1/gateways/{id}/purchase
Authorizes and captures in one step through the gateway you choose.
Required ability
transactions:write
Rate limit
300 requests/minute per API key

Path parameters

idstringrequired
The gateway to charge through.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Body parameters

payment_method_tokenstringrequired
The vaulted card to charge.
Example: tok_01jaxqk0pz7r8w5m3n2b4c6d8e
amountintegerrequired
What to charge before any surcharge, tax included, in minor units (cents).
Example: 10000
tax_amountintegeroptional
The tax inside amount, for Level 2 data and Fortis.
surcharge.modestringoptional
auto (default): the gateway's surcharge set-up decides. none: no surcharge. amount: send surcharge.amount yourself (not on Fortis or Converge).
surcharge.amountintegeroptional
With mode amount: the surcharge you showed, at most 3% of amount.
max_totalintegeroptional
Never charge more than this. If the surcharge would push the total above it, nothing is charged and you get 409 surcharge_changed with the new total.
currencystringoptional
Three-letter currency code. Default USD.
referencestringoptional
Your order or invoice number. Sent to the gateway where it has a field for it.
descriptionstringoptional
Max 255 characters.
customerstringoptional
The customer this charge is for, by OrderCard id. Defaults to the card's customer. A card that belongs to another customer is refused with customer_mismatch; a card with no customer is linked to this one when the charge succeeds and the card is kept.
customer_referencestringoptional
The same, by your own id for the customer (created the first time). Send this or customer, not both.
metadataobjectoptional
Up to 50 keys of your own, each with a text value of up to 500 characters. See Conventions for the rules.
billingobjectoptional
Billing details for this charge only (same fields as on the payment method). A field sent as null is left out for this charge.
initiatorstringoptional
customer (default) when the cardholder is at checkout; merchant for an unscheduled charge on a stored card; recurring for a subscription. Merchant-initiated charges never send a CVV and reference the card's first customer-initiated transaction.
retain_on_successbooleanoptional
Retain a pending token when the charge succeeds. Default true.
ip_addressstringoptional
The cardholder's IP address, for the gateway's fraud checks.
three_d_secure.versionstringoptional
Required with three_d_secure. The protocol version, such as 2.2.0.
three_d_secure.statusstringoptional
Required with three_d_secure. Y (authenticated) or A (attempted); any other outcome is refused.
three_d_secure.ecistringoptional
Required with three_d_secure. The electronic commerce indicator, such as 05 (Visa) or 02 (Mastercard).
three_d_secure.cavvstringoptional
Required with three_d_secure. The authentication value (CAVV, or AAV for Mastercard), base64. Sent to the gateway, never stored.
three_d_secure.ds_transaction_idstringoptional
The directory server transaction ID. Required for 3-D Secure 2.
three_d_secure.xidstringoptional
The transaction ID of a 3-D Secure 1 result.
Caveats
  • 201 means money moved (or, for verify, the card checked out). Anything else that reached the gateway answers 402 with the recorded transaction inside the error, so a decline is never mistaken for success.
  • Send an Idempotency-Key header. A retry with the same key and body returns the first answer instead of charging again.
  • Other refusals before the gateway is called: 409 gateway_inactive, payment_method_redacted, payment_method_expired, customer_mismatch; 422 surcharge_too_high, surcharge_not_allowed.
  • three_d_secure is only accepted with initiator customer. On a gateway that cannot receive it (Deluxe), the charge goes through without it and three_d_secure.forwarded is false.
Requestbash
curl -X POST https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/purchase \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e", "amount": 10000, "reference": "order-1001" }'
201The charge succeeded.
{
  "object": "transaction",
  "id": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b",
  "type": "purchase",
  "status": "succeeded",
  "succeeded": true,
  "environment": "live",
  "gateway": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "payment_method": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e",
  "parent": null,
  "amount": 10300,
  "currency": "USD",
  "subtotal_amount": 10000,
  "tax_amount": null,
  "surcharge_amount": 300,
  "surcharge": { "rate": 3, "source": "platform", "waived_reason": null },
  "initiator": "customer",
  "reference": "order-1001",
  "description": null,
  "customer": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "customer_reference": "user_1001",
  "response": {
    "message": "Approved",
    "gateway_message": "SUCCESS",
    "error_code": null,
    "decline_code": null,
    "auth_code": "123456",
    "avs_code": "Y",
    "avs_result": "match",
    "avs_message": "Street and postal code match",
    "cvv_code": "M",
    "cvv_result": "match",
    "cvv_message": "CVV matches",
    "gateway_transaction_id": "9001234567",
    "network_transaction_id": "012345678901234"
  },
  "summary": {
    "captured_amount": 0,
    "refunded_amount": 0,
    "voided": false,
    "remaining_capturable": 0,
    "remaining_refundable": 10300
  },
  "three_d_secure": null,
  "billing_address": { "first_name": "Jane", "last_name": "Doe", "postal_code": "30301", "country": "US", "...": "..." },
  "ip_address": "203.0.113.7",
  "metadata": { "cart": "77" },
  "processed_at": "2026-10-17T15:20:01+00:00",
  "created_at": "2026-10-17T15:20:00+00:00"
}
402The card was declined, or the gateway failed. The transaction is recorded.
{
  "error": {
    "code": "card_declined",
    "message": "The card has insufficient funds.",
    "decline_code": "insufficient_funds",
    "transaction": {
      "object": "transaction",
      "id": "txn_01jaxs6q9s2u5w8y1a4c7e0g3j",
      "type": "purchase",
      "status": "declined",
      "succeeded": false,
      "amount": 10000,
      "response": { "error_code": "card_declined", "decline_code": "insufficient_funds", "gateway_message": "Insufficient funds", "...": "..." },
      "...": "..."
    }
  }
}
409The surcharge would make the total more than max_total. Nothing was charged.
{
  "error": {
    "code": "surcharge_changed",
    "message": "A surcharge of 300 applies, making the total 10300, which is more than max_total. Show the customer the new total and retry.",
    "transaction": "txn_01jaxs8t1v4x7z0b3d6f9h2k5m",
    "surcharge_amount": 300,
    "surcharge_rate": 3,
    "total_amount": 10300
  }
}
422The token is not one of this key's cards.
{ "error": { "code": "resource_missing", "message": "No such payment method: tok_01jaxqk0pz7r8w5m3n2b4c6d8e.", "param": "payment_method_token" } }

Authorize a card

POST/v1/gateways/{id}/authorize
Holds the amount on the card without taking it. Capture it later, or void it to release the hold.
Required ability
transactions:write
Rate limit
300 requests/minute per API key

Path parameters

idstringrequired
The gateway to charge through.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Body parameters

payment_method_tokenstringrequired
The vaulted card to charge.
Example: tok_01jaxqk0pz7r8w5m3n2b4c6d8e
amountintegerrequired
What to charge before any surcharge, tax included, in minor units (cents).
Example: 10000
tax_amountintegeroptional
The tax inside amount, for Level 2 data and Fortis.
surcharge.modestringoptional
auto (default): the gateway's surcharge set-up decides. none: no surcharge. amount: send surcharge.amount yourself (not on Fortis or Converge).
surcharge.amountintegeroptional
With mode amount: the surcharge you showed, at most 3% of amount.
max_totalintegeroptional
Never charge more than this. If the surcharge would push the total above it, nothing is charged and you get 409 surcharge_changed with the new total.
currencystringoptional
Three-letter currency code. Default USD.
referencestringoptional
Your order or invoice number. Sent to the gateway where it has a field for it.
descriptionstringoptional
Max 255 characters.
customerstringoptional
The customer this charge is for, by OrderCard id. Defaults to the card's customer. A card that belongs to another customer is refused with customer_mismatch; a card with no customer is linked to this one when the charge succeeds and the card is kept.
customer_referencestringoptional
The same, by your own id for the customer (created the first time). Send this or customer, not both.
metadataobjectoptional
Up to 50 keys of your own, each with a text value of up to 500 characters. See Conventions for the rules.
billingobjectoptional
Billing details for this charge only (same fields as on the payment method). A field sent as null is left out for this charge.
initiatorstringoptional
customer (default) when the cardholder is at checkout; merchant for an unscheduled charge on a stored card; recurring for a subscription. Merchant-initiated charges never send a CVV and reference the card's first customer-initiated transaction.
retain_on_successbooleanoptional
Retain a pending token when the charge succeeds. Default true.
ip_addressstringoptional
The cardholder's IP address, for the gateway's fraud checks.
three_d_secure.versionstringoptional
Required with three_d_secure. The protocol version, such as 2.2.0.
three_d_secure.statusstringoptional
Required with three_d_secure. Y (authenticated) or A (attempted); any other outcome is refused.
three_d_secure.ecistringoptional
Required with three_d_secure. The electronic commerce indicator, such as 05 (Visa) or 02 (Mastercard).
three_d_secure.cavvstringoptional
Required with three_d_secure. The authentication value (CAVV, or AAV for Mastercard), base64. Sent to the gateway, never stored.
three_d_secure.ds_transaction_idstringoptional
The directory server transaction ID. Required for 3-D Secure 2.
three_d_secure.xidstringoptional
The transaction ID of a 3-D Secure 1 result.
Caveats
  • 201 means money moved (or, for verify, the card checked out). Anything else that reached the gateway answers 402 with the recorded transaction inside the error, so a decline is never mistaken for success.
  • Send an Idempotency-Key header. A retry with the same key and body returns the first answer instead of charging again.
Requestbash
curl -X POST https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/authorize \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1002-auth" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e", "amount": 8900 }'
201The authorization. summary.remaining_capturable is what you can capture.
{
  "object": "transaction",
  "id": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b",
  "type": "authorize",
  "status": "succeeded",
  "succeeded": true,
  "environment": "live",
  "gateway": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "payment_method": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e",
  "parent": null,
  "amount": 10300,
  "currency": "USD",
  "subtotal_amount": 10000,
  "tax_amount": null,
  "surcharge_amount": 300,
  "surcharge": { "rate": 3, "source": "platform", "waived_reason": null },
  "initiator": "customer",
  "reference": "order-1001",
  "description": null,
  "customer": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "customer_reference": "user_1001",
  "response": {
    "message": "Approved",
    "gateway_message": "SUCCESS",
    "error_code": null,
    "decline_code": null,
    "auth_code": "123456",
    "avs_code": "Y",
    "avs_result": "match",
    "avs_message": "Street and postal code match",
    "cvv_code": "M",
    "cvv_result": "match",
    "cvv_message": "CVV matches",
    "gateway_transaction_id": "9001234567",
    "network_transaction_id": "012345678901234"
  },
  "summary": {
    "captured_amount": 0,
    "refunded_amount": 0,
    "voided": false,
    "remaining_capturable": 0,
    "remaining_refundable": 10300
  },
  "three_d_secure": null,
  "billing_address": { "first_name": "Jane", "last_name": "Doe", "postal_code": "30301", "country": "US", "...": "..." },
  "ip_address": "203.0.113.7",
  "metadata": { "cart": "77" },
  "processed_at": "2026-10-17T15:20:01+00:00",
  "created_at": "2026-10-17T15:20:00+00:00"
}
402Declined or failed.
{
  "error": {
    "code": "card_declined",
    "message": "The card has insufficient funds.",
    "decline_code": "insufficient_funds",
    "transaction": {
      "object": "transaction",
      "id": "txn_01jaxs6q9s2u5w8y1a4c7e0g3j",
      "type": "purchase",
      "status": "declined",
      "succeeded": false,
      "amount": 10000,
      "response": { "error_code": "card_declined", "decline_code": "insufficient_funds", "gateway_message": "Insufficient funds", "...": "..." },
      "...": "..."
    }
  }
}

Verify a card

POST/v1/gateways/{id}/verify
Checks the card with the issuer (a zero-amount authorization or AVS-only check, depending on the gateway) and records the AVS and CVV results on the card. Never moves money; takes no amount.
Required ability
transactions:write
Rate limit
300 requests/minute per API key

Path parameters

idstringrequired
The gateway to charge through.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Body parameters

payment_method_tokenstringrequired
The vaulted card to charge.
Example: tok_01jaxqk0pz7r8w5m3n2b4c6d8e
currencystringoptional
Three-letter currency code. Default USD.
referencestringoptional
Your order or invoice number. Sent to the gateway where it has a field for it.
descriptionstringoptional
Max 255 characters.
customerstringoptional
The customer this charge is for, by OrderCard id. Defaults to the card's customer. A card that belongs to another customer is refused with customer_mismatch; a card with no customer is linked to this one when the charge succeeds and the card is kept.
customer_referencestringoptional
The same, by your own id for the customer (created the first time). Send this or customer, not both.
metadataobjectoptional
Up to 50 keys of your own, each with a text value of up to 500 characters. See Conventions for the rules.
billingobjectoptional
Billing details for this charge only (same fields as on the payment method). A field sent as null is left out for this charge.
initiatorstringoptional
customer (default) when the cardholder is at checkout; merchant for an unscheduled charge on a stored card; recurring for a subscription. Merchant-initiated charges never send a CVV and reference the card's first customer-initiated transaction.
retain_on_successbooleanoptional
Retain a pending token when the charge succeeds. Default true.
ip_addressstringoptional
The cardholder's IP address, for the gateway's fraud checks.
Caveats
  • three_d_secure is refused with 422: a verification never carries a 3-D Secure result.
Requestbash
curl -X POST https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/verify \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e" }'
201The verification, with amount 0.
{ "object": "transaction", "type": "verify", "status": "succeeded", "amount": 0, "response": { "avs_result": "postal_only", "cvv_result": "match", "...": "..." }, "...": "..." }
402The issuer refused the card.
{
  "error": {
    "code": "card_declined",
    "message": "The card has insufficient funds.",
    "decline_code": "insufficient_funds",
    "transaction": {
      "object": "transaction",
      "id": "txn_01jaxs6q9s2u5w8y1a4c7e0g3j",
      "type": "purchase",
      "status": "declined",
      "succeeded": false,
      "amount": 10000,
      "response": { "error_code": "card_declined", "decline_code": "insufficient_funds", "gateway_message": "Insufficient funds", "...": "..." },
      "...": "..."
    }
  }
}

Capture an authorization

POST/v1/transactions/{id}/capture
Takes the money an authorization held, in full or for less. An authorization can be captured once.
Required ability
transactions:write
Rate limit
300 requests/minute per API key

Path parameters

idstringrequired
The transaction to act on.
Example: txn_01jaxs4h7k0m3p6r9t2v5x8z1b

Body parameters

amountintegeroptional
Defaults to the full authorized amount. Never more than it.
Caveats
  • Other 409 codes: transaction_not_successful, transaction_voided, transaction_not_capturable (not an authorization), transaction_in_progress.
Requestbash
curl -X POST https://api.ordercard.io/v1/transactions/txn_01jaxs4h7k0m3p6r9t2v5x8z1b/capture \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1002-capture"
201The capture, a new transaction whose parent is the authorization.
{ "object": "transaction", "id": "txn_01jaxsb0c3e6g9j2l5n8q1s4u7", "type": "capture", "status": "succeeded", "parent": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b", "amount": 8900, "...": "..." }
402The gateway refused the capture.
{
  "error": {
    "code": "card_declined",
    "message": "The card has insufficient funds.",
    "decline_code": "insufficient_funds",
    "transaction": {
      "object": "transaction",
      "id": "txn_01jaxs6q9s2u5w8y1a4c7e0g3j",
      "type": "purchase",
      "status": "declined",
      "succeeded": false,
      "amount": 10000,
      "response": { "error_code": "card_declined", "decline_code": "insufficient_funds", "gateway_message": "Insufficient funds", "...": "..." },
      "...": "..."
    }
  }
}
409Not capturable.
{ "error": { "code": "transaction_already_captured", "message": "This authorization was already captured." } }
422More than was authorized.
{ "error": { "code": "amount_too_large", "message": "The capture amount is more than the authorized amount (8900).", "maximum_amount": 8900 } }

Void a transaction

POST/v1/transactions/{id}/void
Cancels an authorization, or a purchase or capture that has not settled yet. After settlement the gateway refuses the void; refund instead.
Required ability
transactions:write
Rate limit
300 requests/minute per API key

Path parameters

idstringrequired
The transaction to act on.
Example: txn_01jaxs4h7k0m3p6r9t2v5x8z1b
Requestbash
curl -X POST https://api.ordercard.io/v1/transactions/txn_01jaxs4h7k0m3p6r9t2v5x8z1b/void \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
201The void.
{ "object": "transaction", "type": "void", "status": "succeeded", "parent": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b", "...": "..." }
409Not voidable.
{ "error": { "code": "transaction_not_voidable", "message": "This authorization was captured. Void or refund the capture instead." } }

Refund a transaction

POST/v1/transactions/{id}/refund
Returns money from a purchase or capture, in full or in parts, up to what is left. A surcharged payment refunds its surcharge in proportion.
Required ability
transactions:write
Rate limit
300 requests/minute per API key

Path parameters

idstringrequired
The transaction to act on.
Example: txn_01jaxs4h7k0m3p6r9t2v5x8z1b

Body parameters

amountintegeroptional
Defaults to everything left to refund.
Requestbash
curl -X POST https://api.ordercard.io/v1/transactions/txn_01jaxs4h7k0m3p6r9t2v5x8z1b/refund \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1001-refund-1" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5150 }'
201The refund.
{ "object": "transaction", "type": "refund", "status": "succeeded", "parent": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b", "amount": 5150, "surcharge_amount": 150, "...": "..." }
409Nothing left to refund.
{ "error": { "code": "transaction_fully_refunded", "message": "This transaction was already refunded in full." } }

List transactions

GET/v1/transactions
Lists the transactions of the key's team and environment, newest first. Purchases, authorizations and captures include a summary.
Required ability
transactions:read
Rate limit
300 requests/minute per API key

Query parameters

typestringoptional
purchase, authorize, capture, void, refund or verify.
statusstringoptional
pending, succeeded, declined or failed.
gatewaystringoptional
A gateway id.
payment_methodstringoptional
A card token.
parentstringoptional
The captures, voids and refunds of this transaction.
customerstringoptional
A customer's transactions, by OrderCard id.
customer_referencestringoptional
Transactions made for this reference of yours.
referencestringoptional
Your order reference.
created[gte]stringoptional
Created at or after this date or time.
created[lte]stringoptional
Created at or before this date or time.
limitintegeroptional
1 to 100, default 25.
cursorstringoptional
The meta.next_cursor of the previous page.
Requestbash
curl "https://api.ordercard.io/v1/transactions?parent=txn_01jaxs4h7k0m3p6r9t2v5x8z1b" \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
200A page of transactions.
{ "data": [ { "object": "transaction", "id": "txn_01jaxsb0c3e6g9j2l5n8q1s4u7", "type": "refund", "...": "..." } ], "links": { "...": "..." }, "meta": { "...": "..." } }

Retrieve a transaction

GET/v1/transactions/{id}
Returns one transaction.
Required ability
transactions:read
Rate limit
300 requests/minute per API key

Path parameters

idstringrequired
The transaction to act on.
Example: txn_01jaxs4h7k0m3p6r9t2v5x8z1b
Requestbash
curl https://api.ordercard.io/v1/transactions/txn_01jaxs4h7k0m3p6r9t2v5x8z1b \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
200The transaction.
{
  "object": "transaction",
  "id": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b",
  "type": "purchase",
  "status": "succeeded",
  "succeeded": true,
  "environment": "live",
  "gateway": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "payment_method": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e",
  "parent": null,
  "amount": 10300,
  "currency": "USD",
  "subtotal_amount": 10000,
  "tax_amount": null,
  "surcharge_amount": 300,
  "surcharge": { "rate": 3, "source": "platform", "waived_reason": null },
  "initiator": "customer",
  "reference": "order-1001",
  "description": null,
  "customer": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "customer_reference": "user_1001",
  "response": {
    "message": "Approved",
    "gateway_message": "SUCCESS",
    "error_code": null,
    "decline_code": null,
    "auth_code": "123456",
    "avs_code": "Y",
    "avs_result": "match",
    "avs_message": "Street and postal code match",
    "cvv_code": "M",
    "cvv_result": "match",
    "cvv_message": "CVV matches",
    "gateway_transaction_id": "9001234567",
    "network_transaction_id": "012345678901234"
  },
  "summary": {
    "captured_amount": 0,
    "refunded_amount": 0,
    "voided": false,
    "remaining_capturable": 0,
    "remaining_refundable": 10300
  },
  "three_d_secure": null,
  "billing_address": { "first_name": "Jane", "last_name": "Doe", "postal_code": "30301", "country": "US", "...": "..." },
  "ip_address": "203.0.113.7",
  "metadata": { "cart": "77" },
  "processed_at": "2026-10-17T15:20:01+00:00",
  "created_at": "2026-10-17T15:20:00+00:00"
}
Navigation

Type to search…

↑↓ navigate↵ selectEsc close