---
title: "Transactions"
description: "Charge, authorize and verify vaulted cards, then capture, void and refund."
image: "https://docs.ordercard.io/og.png"
---

> API Reference Index
> Fetch the complete API index at: https://docs.ordercard.io/api/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

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](/payments/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](/payments) walks through the flows.

## Charge a card

`POST /v1/gateways/{id}/purchase`

Authorizes and captures in one step through the gateway you choose.

- **Operation id:** `transactions.purchase`
- **Required ability:** `transactions:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway to charge through. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `payment_method_token` | string | yes | The vaulted card to charge. Example: `tok_01jaxqk0pz7r8w5m3n2b4c6d8e` |
| `amount` | integer | yes | What to charge before any surcharge, tax included, in minor units (cents). Example: `10000` |
| `tax_amount` | integer | no | The tax inside amount, for Level 2 data and Fortis. |
| `surcharge.mode` | string | no | auto (default): the gateway's surcharge set-up decides. none: no surcharge. amount: send surcharge.amount yourself (not on Fortis or Converge). |
| `surcharge.amount` | integer | no | With mode amount: the surcharge you showed, at most 3% of amount. |
| `max_total` | integer | no | 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. |
| `currency` | string | no | Three-letter currency code. Default USD. |
| `reference` | string | no | Your order or invoice number. Sent to the gateway where it has a field for it. |
| `description` | string | no | Max 255 characters. |
| `customer` | string | no | 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_reference` | string | no | The same, by your own id for the customer (created the first time). Send this or customer, not both. |
| `metadata` | object | no | Up to 50 keys of your own, each with a text value of up to 500 characters. See Conventions for the rules. |
| `billing` | object | no | Billing details for this charge only (same fields as on the payment method). A field sent as null is left out for this charge. |
| `initiator` | string | no | 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_success` | boolean | no | Retain a pending token when the charge succeeds. Default true. |
| `ip_address` | string | no | The cardholder's IP address, for the gateway's fraud checks. |
| `three_d_secure.version` | string | no | Required with three_d_secure. The protocol version, such as 2.2.0. |
| `three_d_secure.status` | string | no | Required with three_d_secure. Y (authenticated) or A (attempted); any other outcome is refused. |
| `three_d_secure.eci` | string | no | Required with three_d_secure. The electronic commerce indicator, such as 05 (Visa) or 02 (Mastercard). |
| `three_d_secure.cavv` | string | no | 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_id` | string | no | The directory server transaction ID. Required for 3-D Secure 2. |
| `three_d_secure.xid` | string | no | The transaction ID of a 3-D Secure 1 result. |

#### Request

```bash
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" }'
```

#### Responses

##### 201 — The charge succeeded.

```json
{
  "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"
}
```

##### 402 — The card was declined, or the gateway failed. The transaction is recorded.

```json
{
  "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", "...": "..." },
      "...": "..."
    }
  }
}
```

##### 409 — The surcharge would make the total more than max_total. Nothing was charged.

```json
{
  "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
  }
}
```

##### 422 — The token is not one of this key's cards.

```json
{ "error": { "code": "resource_missing", "message": "No such payment method: tok_01jaxqk0pz7r8w5m3n2b4c6d8e.", "param": "payment_method_token" } }
```

#### 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.

## 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.

- **Operation id:** `transactions.authorize`
- **Required ability:** `transactions:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway to charge through. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `payment_method_token` | string | yes | The vaulted card to charge. Example: `tok_01jaxqk0pz7r8w5m3n2b4c6d8e` |
| `amount` | integer | yes | What to charge before any surcharge, tax included, in minor units (cents). Example: `10000` |
| `tax_amount` | integer | no | The tax inside amount, for Level 2 data and Fortis. |
| `surcharge.mode` | string | no | auto (default): the gateway's surcharge set-up decides. none: no surcharge. amount: send surcharge.amount yourself (not on Fortis or Converge). |
| `surcharge.amount` | integer | no | With mode amount: the surcharge you showed, at most 3% of amount. |
| `max_total` | integer | no | 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. |
| `currency` | string | no | Three-letter currency code. Default USD. |
| `reference` | string | no | Your order or invoice number. Sent to the gateway where it has a field for it. |
| `description` | string | no | Max 255 characters. |
| `customer` | string | no | 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_reference` | string | no | The same, by your own id for the customer (created the first time). Send this or customer, not both. |
| `metadata` | object | no | Up to 50 keys of your own, each with a text value of up to 500 characters. See Conventions for the rules. |
| `billing` | object | no | Billing details for this charge only (same fields as on the payment method). A field sent as null is left out for this charge. |
| `initiator` | string | no | 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_success` | boolean | no | Retain a pending token when the charge succeeds. Default true. |
| `ip_address` | string | no | The cardholder's IP address, for the gateway's fraud checks. |
| `three_d_secure.version` | string | no | Required with three_d_secure. The protocol version, such as 2.2.0. |
| `three_d_secure.status` | string | no | Required with three_d_secure. Y (authenticated) or A (attempted); any other outcome is refused. |
| `three_d_secure.eci` | string | no | Required with three_d_secure. The electronic commerce indicator, such as 05 (Visa) or 02 (Mastercard). |
| `three_d_secure.cavv` | string | no | 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_id` | string | no | The directory server transaction ID. Required for 3-D Secure 2. |
| `three_d_secure.xid` | string | no | The transaction ID of a 3-D Secure 1 result. |

#### Request

```bash
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 }'
```

#### Responses

##### 201 — The authorization. summary.remaining_capturable is what you can capture.

```json
{
  "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"
}
```

##### 402 — Declined or failed.

```json
{
  "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", "...": "..." },
      "...": "..."
    }
  }
}
```

#### 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.

## 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.

- **Operation id:** `transactions.verify`
- **Required ability:** `transactions:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway to charge through. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `payment_method_token` | string | yes | The vaulted card to charge. Example: `tok_01jaxqk0pz7r8w5m3n2b4c6d8e` |
| `currency` | string | no | Three-letter currency code. Default USD. |
| `reference` | string | no | Your order or invoice number. Sent to the gateway where it has a field for it. |
| `description` | string | no | Max 255 characters. |
| `customer` | string | no | 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_reference` | string | no | The same, by your own id for the customer (created the first time). Send this or customer, not both. |
| `metadata` | object | no | Up to 50 keys of your own, each with a text value of up to 500 characters. See Conventions for the rules. |
| `billing` | object | no | Billing details for this charge only (same fields as on the payment method). A field sent as null is left out for this charge. |
| `initiator` | string | no | 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_success` | boolean | no | Retain a pending token when the charge succeeds. Default true. |
| `ip_address` | string | no | The cardholder's IP address, for the gateway's fraud checks. |

#### Request

```bash
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" }'
```

#### Responses

##### 201 — The verification, with amount 0.

```json
{ "object": "transaction", "type": "verify", "status": "succeeded", "amount": 0, "response": { "avs_result": "postal_only", "cvv_result": "match", "...": "..." }, "...": "..." }
```

##### 402 — The issuer refused the card.

```json
{
  "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", "...": "..." },
      "...": "..."
    }
  }
}
```

#### Caveats

- three_d_secure is refused with 422: a verification never carries a 3-D Secure result.

## 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.

- **Operation id:** `transactions.capture`
- **Required ability:** `transactions:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The transaction to act on. Example: `txn_01jaxs4h7k0m3p6r9t2v5x8z1b` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | integer | no | Defaults to the full authorized amount. Never more than it. |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/transactions/txn_01jaxs4h7k0m3p6r9t2v5x8z1b/capture \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1002-capture"
```

#### Responses

##### 201 — The capture, a new transaction whose parent is the authorization.

```json
{ "object": "transaction", "id": "txn_01jaxsb0c3e6g9j2l5n8q1s4u7", "type": "capture", "status": "succeeded", "parent": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b", "amount": 8900, "...": "..." }
```

##### 402 — The gateway refused the capture.

```json
{
  "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", "...": "..." },
      "...": "..."
    }
  }
}
```

##### 409 — Not capturable.

```json
{ "error": { "code": "transaction_already_captured", "message": "This authorization was already captured." } }
```

##### 422 — More than was authorized.

```json
{ "error": { "code": "amount_too_large", "message": "The capture amount is more than the authorized amount (8900).", "maximum_amount": 8900 } }
```

#### Caveats

- Other 409 codes: transaction_not_successful, transaction_voided, transaction_not_capturable (not an authorization), transaction_in_progress.

## 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.

- **Operation id:** `transactions.void`
- **Required ability:** `transactions:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The transaction to act on. Example: `txn_01jaxs4h7k0m3p6r9t2v5x8z1b` |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/transactions/txn_01jaxs4h7k0m3p6r9t2v5x8z1b/void \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 201 — The void.

```json
{ "object": "transaction", "type": "void", "status": "succeeded", "parent": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b", "...": "..." }
```

##### 409 — Not voidable.

```json
{ "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.

- **Operation id:** `transactions.refund`
- **Required ability:** `transactions:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The transaction to act on. Example: `txn_01jaxs4h7k0m3p6r9t2v5x8z1b` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | integer | no | Defaults to everything left to refund. |

#### Request

```bash
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 }'
```

#### Responses

##### 201 — The refund.

```json
{ "object": "transaction", "type": "refund", "status": "succeeded", "parent": "txn_01jaxs4h7k0m3p6r9t2v5x8z1b", "amount": 5150, "surcharge_amount": 150, "...": "..." }
```

##### 409 — Nothing left to refund.

```json
{ "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.

- **Operation id:** `transactions.list`
- **Required ability:** `transactions:read`
- **Rate limit:** 300 requests/minute per API key

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | no | purchase, authorize, capture, void, refund or verify. |
| `status` | string | no | pending, succeeded, declined or failed. |
| `gateway` | string | no | A gateway id. |
| `payment_method` | string | no | A card token. |
| `parent` | string | no | The captures, voids and refunds of this transaction. |
| `customer` | string | no | A customer's transactions, by OrderCard id. |
| `customer_reference` | string | no | Transactions made for this reference of yours. |
| `reference` | string | no | Your order reference. |
| `created[gte]` | string | no | Created at or after this date or time. |
| `created[lte]` | string | no | Created at or before this date or time. |
| `limit` | integer | no | 1 to 100, default 25. |
| `cursor` | string | no | The meta.next_cursor of the previous page. |

#### Request

```bash
curl "https://api.ordercard.io/v1/transactions?parent=txn_01jaxs4h7k0m3p6r9t2v5x8z1b" \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — A page of transactions.

```json
{ "data": [ { "object": "transaction", "id": "txn_01jaxsb0c3e6g9j2l5n8q1s4u7", "type": "refund", "...": "..." } ], "links": { "...": "..." }, "meta": { "...": "..." } }
```

## Retrieve a transaction

`GET /v1/transactions/{id}`

Returns one transaction.

- **Operation id:** `transactions.get`
- **Required ability:** `transactions:read`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The transaction to act on. Example: `txn_01jaxs4h7k0m3p6r9t2v5x8z1b` |

#### Request

```bash
curl https://api.ordercard.io/v1/transactions/txn_01jaxs4h7k0m3p6r9t2v5x8z1b \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The transaction.

```json
{
  "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"
}
```

Source: https://docs.ordercard.io/api/transactions/index.mdx