# Create a Transaction

Create a payment transaction via a payment card (credit or debit).
- A
`SALE`
 transaction authorizes and captures the payment simultaneously.
- An
`AUTH`
 transaction authorizes the payment and requires a subsequent  capture.

Endpoint: POST /v1/transactions
Version: 1.0.0-beta.54
Security: ApiKeyAuth

## Security:

  - `ApiKeyAuth` (unknown)
    apiKey in header Api-Key

## Header parameters:

  - `Client-Id` (string, required)

  - `X-Acting-As-Client-Id` (string)
    The child client this request acts on behalf of. A reseller still authenticates as itself — `Api-Key` and `Client-Id` stay the reseller's — and names the child here.
This works only from a parent to its own children. Merchants have no children, so a merchant calling as itself omits the header. Sending your own client ULID here is not the same as omitting it, and is rejected on some operations.

## Request fields (application/json):

  - `type` (string, required)
    The type of transaction to create. `POST /v1/transactions` accepts these three. `REFUND` and `VOID` are served by `POST /v1/transactions/{id}/cancel`, and `CAPTURE` by `POST /v1/transactions/{id}/capture`.
Which of the three applies depends on the payment method: a card takes `SALE` or `AUTH`, a bank account takes `SALE` or `PAYOUT`. A payment token resolves to whichever instrument it was issued for, so the applicable pair is not known until the gateway detokenizes it.
    Enum: "SALE", "AUTH", "PAYOUT"

  - `amount` (integer, required)
    Amount in cents (e.g. `10000` = $100.00). All transactions are in US  dollars (USD).

  - `tip` (integer)
    Tip amount in cents (e.g. `1000` = $10.00). If no tip is included, use `0` or omit the field.
`amount` is the whole charge and `tip` declares how much of it is gratuity. The two are not added together: a $100.00 bill with a $20.00 tip is `amount: 12000` with `tip: 2000`, and the cardholder is charged $120.00. The tip is reported to the processor separately at settlement and never increases the settled amount.
Minimum 0 cents ($0.00). Maximum 99,999,999 cents ($999,999.99). All transactions are in US dollars (USD).

  - `tax_amount` (integer)
    Tax amount in cents (e.g. `500` = $5.00). Used for reporting only.
`amount` is the whole charge and `tax_amount` declares how much of it is tax. The two are not added together: a $100.00 sale with $5.00 tax is `amount: 10500` with `tax_amount: 500`, and the cardholder is charged $105.00. The gateway does not check `tax_amount` against `amount`.
Minimum 0 cents ($0.00). Maximum 99,999,999 cents ($999,999.99). All transactions are in US dollars (USD).

  - `currency` (string)
    Three-letter ISO 4217 currency code. Optional; defaults to `USD`, which is the only value the gateway accepts.
    Enum: "USD"

  - `payment_method` (any, required)
    Schema for payment methods supplied on a transaction create request. Concrete subtypes are discriminated by the `type` property.

  - `payment_method.type` (string, required)
    The type of payment method supplied on a request. A request can also send `TOKEN`, which a response never returns: the gateway resolves the token to the card or bank account behind it and reports that instead — see `PaymentMethodTypeOutput`.
    Enum: "ACH", "CARD", "TOKEN"

  - `payment_method.standard_entry_class` (string, required)
    ACH Standard Entry Class (SEC) code that defines the transaction type and authorization method.
    Enum: "PPD", "CCD", "WEB", "TEL", "POP", "BOC"

  - `payment_method.account_type` (string, required)
    The type of bank account.
    Enum: "CHECKING", "SAVINGS"

  - `payment_method.routing_number` (string, required)
    Nine-digit ABA routing number.

  - `payment_method.account_number` (string, required)
    Bank account number.

  - `payment_method.first_name` (string, required)
    Account holder's first name.

  - `payment_method.last_name` (string, required)
    Account holder's last name.

  - `payment_method.description` (string)
    Optional information to include on customer's bank statement. This is a short description that, e.g., identifies the goods or services purchased or the merchant's name. When omitted or blank, the gateway uses the merchant's DBA, cut to 30 characters. Only the first 10 characters will appear on the bank statement.

  - `payment_method.pan` (string, required)
    Primary account number (PAN) — the full card number.

  - `payment_method.expiry` (object, required)
    Card expiration date supplied on a request. Both fields are numbers, not strings, and the year is the full four-digit year. A response returns a different shape — see `Expiry`.

  - `payment_method.expiry.month` (integer, required)
    Month of the card expiration date, as a number from 1 to 12.

  - `payment_method.expiry.year` (integer, required)
    Four-digit year of the card expiration date.

  - `payment_method.cvv` (string)
    Card verification value (CVV/CVC) — three digits for Visa, Mastercard,  Discover. Four digits for American Express.

  - `payment_method.first_name` (string)
    First name of the cardholder.

  - `payment_method.last_name` (string)
    Last name of the cardholder.

  - `payment_method.contact` (object)

  - `payment_method.contact.phone` (any)
    Phone number. The phone number must contain between 10 and 12 digits and can contain spaces, a leading `+` symbol (when used with a country  code), and the special characters `(`, `)`, `-`, and `.`. Alphabetical  characters are not allowed.

  - `payment_method.contact.email` (string)
    Email address.

  - `payment_method.billing_address` (object)
    Address object.

  - `payment_method.billing_address.line1` (string)
    Primary street address line.

  - `payment_method.billing_address.line2` (string)
    Secondary address line (suite, apt, floor, etc.).

  - `payment_method.billing_address.city` (string)
    City name.

  - `payment_method.billing_address.state` (string)
    Two-letter US state code (e.g. `VA`).

  - `payment_method.billing_address.postal_code` (string)
    ZIP or postal code.

  - `payment_method.billing_address.country` (string)
    Two-letter ISO 3166-1 alpha-2 country code (e.g. `US`).

  - `payment_method.entry_method` (string | null)
    How the payment method information was captured. Both supported values are Card Not Present: `ECOMMERCE` for information taken over the internet through a web browser, and `MOTO` for information taken over the phone or by postal mail.
Optional. Defaults to `ECOMMERCE` when omitted or sent as `null`.
    Enum: "MOTO", "ECOMMERCE", "null"

  - `payment_method.payment_token` (string | null, required)
    Reference to a previously stored (tokenized) payment method. A read of a transaction returns null when no token was issued for it.
The response to the request that ran the transaction does not return null today. A declined transaction returns an empty string. An approved one whose payment method could not be tokenized returns the sentence `Payment method could not be tokenized.` Treat a value that starts with none of the prefixes below as no token, and do not store it.
The prefix says what the token stands for: `CARD_TOKEN-` for a card, and `BANK_TOKEN-` for a bank account. Tokens issued before 2026-10-16 start with `PAYMENT_TOKEN-` and keep working, so an older token's prefix does not say what it stands for. Send the value back exactly as it was returned.

  - `initiator` (string)
    Who initiated the transaction, per the card-network stored-credential framework. `CUSTOMER` = customer-initiated (CIT); `MERCHANT` = merchant-initiated (MIT).
    Enum: "MERCHANT", "CUSTOMER", "THIRD_PARTY"

  - `recurring` (boolean)
    Marks the transaction as part of a recurring payment agreement. Supplying `recurring_details` has the same effect on most paths, but set this flag explicitly on a recurring charge.

  - `recurring_details` (object)
    Stored-credential details. Present only when the transaction is part of a recurring payment agreement; omit for one-off transactions. Identifies the transaction's position within the agreement.

  - `recurring_details.sequence` (string, required)
    The position of this transaction within a recurring payment agreement.
    Enum: "INITIAL", "SUBSEQUENT"

  - `recurring_details.initial_transaction_id` (string | null)
    The transaction ID of the initial customer-initiated (CIT) transaction that established the recurring payment agreement. Required when `sequence` is `SUBSEQUENT`; omit (or send `null`) on the `INITIAL` transaction.

  - `recurring_details.initial_network_transaction_id` (string | null)
    The network-assigned transaction identifier (Visa Transaction ID / Mastercard Trace ID) returned on the initial authorization that established the agreement. Supply this only when the initial transaction was processed outside this gateway (e.g. migration from another provider). When `initial_transaction_id` references a transaction processed by this gateway, the network ID is resolved automatically and this field may be omitted.

  - `metadata` (object | null)
    Key-value pairs for storing additional information on the transaction. Send `null` to clear all metadata.
At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected.

## Request examples:

  - `Sale with a card` (unknown)
    A single-step sale that authorizes and captures $100.00 in one call, using full card details. This is the transaction the void and refund examples reference.
Of the $100.00, $5.00 is tax, declared in `tax_amount`. Tax is part of `amount`, not added to it, and is for reporting only.

  - `Sale with a stored payment token` (unknown)
    The same $100.00 sale, charged against a previously stored payment token instead of raw card details. No PAN, expiry, or CVV is sent.
Of the $100.00, $5.00 is tax, declared in `tax_amount`. Tax is part of `amount`, not added to it, and is for reporting only.

  - `Authorization with a card` (unknown)
    A two-step authorization that reserves $100.00 without capturing it. Capture the resulting transaction with the Capture operation; the `captureCard` example there captures exactly this transaction.
Of the $100.00, $5.00 is tax. Send `tax_amount` on the authorization, because a capture has none of its own and reports the value from the authorization.

  - `Authorization with a stored payment token` (unknown)
    A two-step authorization charged against a stored payment token. The `captureToken` example on the Capture operation captures this one.
Of the $100.00, $5.00 is tax. Send `tax_amount` on the authorization, because a capture has none of its own and reports the value from the authorization.

  - `Sale taken by phone or mail (MOTO)` (unknown)
    A $100.00 sale keyed by an operator from card details the cardholder gave over the phone or by mail. `entry_method` is `MOTO`, the other Card Not Present value besides the default `ECOMMERCE`.
The CVV is optional. It is left out here, as it is on a mail order, where the cardholder should not write it down. The billing address is still sent, so the address check runs.
Of the $100.00, $5.00 is tax, declared in `tax_amount`. Tax is part of `amount`, not added to it, and is for reporting only.

  - `Sale that includes a tip` (unknown)
    A $120.00 sale of which $20.00 is a tip. `amount` is the whole charge and `tip` says how much of it is gratuity. The two are not added together, so the cardholder is charged $120.00, not $140.00. The tip is reported to the processor separately at settlement.
$5.00 of the $120.00 is tax, declared in `tax_amount`. The tip and the tax are both parts of `amount`, and each is reported on its own.

  - `Sale that includes tax` (unknown)
    A $105.00 sale of which $5.00 is tax. `amount` is the whole charge and `tax_amount` says how much of it is tax. The two are not added together, so the cardholder is charged $105.00, not $110.00. The tax amount is used for reporting only.

  - `Sale charged to a bank account (ACH)` (unknown)
    A $100.00 ACH debit. `type` is `ACH` — the gateway matches this value case-insensitively against `card`, `ach`, and `token`, and rejects anything else before reading the rest of the payment method.
`routing_number` is exactly nine digits and `account_number` is four to twenty. `standard_entry_class` is required and has no default; `WEB` here says the customer authorized the debit online. `description` is optional and defaults to the merchant's DBA. `first_name` and `last_name` are supplied because the ACH processor requires them.
A bank account accepts `SALE` and `PAYOUT`. It does not accept `AUTH`.
Of the $100.00, $5.00 is tax, declared in `tax_amount`. Tax is part of `amount`, not added to it, and is for reporting only.

  - `Sale charged to a stored bank account token` (unknown)
    A $100.00 ACH debit charged against a payment token that stands for a bank account, so no routing or account number is sent. The gateway resolves the token to the account behind it.
A token never stores a Standard Entry Class (SEC) code, so the code travels with each request. `standard_entry_class` is `PPD` here because the customer signed a written authorization. Leaving it out returns 400 `REQUIRED_DATA_MISSING`. On a token that stands for a card, the code is ignored.
Of the $100.00, $5.00 is tax, declared in `tax_amount`. Tax is part of `amount`, not added to it, and is for reporting only.

  - `Payout to a bank account (ACH credit)` (unknown)
    A $250.00 ACH credit. `type` is `PAYOUT`, which reverses the direction: funds move from the merchant to the bank account rather than into it.
The payment method is the same `BankAccountInput` an ACH debit uses, with the same required fields. `standard_entry_class` is `CCD` here because the recipient is a business; use `PPD` when paying an individual.
A bank account accepts `SALE` and `PAYOUT`. A card accepts neither `PAYOUT` nor anything but `SALE` and `AUTH`, so a payout with a card payment method is rejected with 400 `INVALID_ACTION`.
Of the $250.00, $12.50 is recorded as tax in `tax_amount`, for reporting only. It is part of `amount`, not added to it.

  - `Sale that returns a decline` (unknown)
    An ordinary card sale, identical in shape to `saleWithCard`. Nothing in this request causes a decline: the card number and amount are the same ordinary values the approved example uses. Do not treat either as a decline trigger — against the live gateway they behave like any other sale. The declined body shown alongside is a fixed sample of what an issuer decline looks like.
Selecting this example and sending it returns the *approved* sample, because the mock server always answers with the first response example for the operation unless a specific one is named. To see the decline, add the header `x-redocly-response-body-example: saleDeclined`.

  - `Initial recurring payment that stores the credential` (unknown)
    The customer-initiated (CIT) sale that starts a recurring payment agreement. `recurring` is `true`, `initiator` is `CUSTOMER`, and `recurring_details.sequence` is `INITIAL`. The cardholder is present, so the CVV is sent.
Store the `id` and the `network_transaction_id` from the response. Each later charge in the agreement quotes the `id` back as `initial_transaction_id`, and the `saleRecurringSubsequent` example bills against this one.
Of the $100.00, $5.00 is tax, declared in `tax_amount`. Tax is part of `amount`, not added to it, and is for reporting only.

  - `Subsequent recurring payment on a stored credential` (unknown)
    A merchant-initiated (MIT) payment billed against the stored-credential agreement that `saleRecurringInitial` established.
Three rules apply together here. The gateway enforces all three and returns 400 `INVALID_ACTION` when one is broken; this schema does not describe them, so a generated client will not catch them first. `recurring_details` requires `initiator`. `sequence: SUBSEQUENT` requires either `initial_transaction_id` or `initial_network_transaction_id`. Only `sequence: INITIAL` may use `initiator: CUSTOMER`.
`initial_transaction_id` points at the transaction returned by `saleRecurringInitial`. Use `initial_network_transaction_id` instead when the agreement began outside this gateway. `recurring` is `true`, as on every charge in the agreement. No CVV is sent — the cardholder is not present.
Of the $100.00, $5.00 is tax, declared in `tax_amount`. Tax is part of `amount`, not added to it, and is for reporting only.

## Response 200:

  - `200` (unknown)
    Transaction created successfully

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier for the transaction assigned by the API server.

  - `reference_transaction_id` (string | null)
    The `transaction_id` of the transaction that this request  references, that is, the transaction that this request updated,  captured, canceled, or refunded. Null for original transactions.

  - `type` (string)
    The type of transaction, as reported on a response. This is not the same set a request may ask for — see `TransactionCreateType`. A cancelled payment is reported as `CANCEL`, never as `VOID`.
    Enum: "SALE", "AUTH", "INCREMENTAL_AUTH", "PAYOUT", "REFUND", "CANCEL", "CAPTURE"

  - `result` (string)
    Enum: "APPROVED", "DECLINED", "ERROR"

  - `client_id` (string)
    The `client_id` of the client account that requested this  transaction.

  - `client_dba` (string)
    Doing Business As (DBA) name of the client account.

  - `integrations` (array)
    Third-party integrations tied to the merchant account for this transaction. Includes the payment processor that processed the payment and may include additional services (e.g. network token providers) as offerings expand.

  - `response_code` (string)
    Response code generated by the payment processor.

  - `response_description` (string)
    Human-readable description of the transaction outcome.

  - `batch_id` (string | null)
    Unique identifier of the batch containing this transaction. Null when the transaction has not yet been assigned to a batch.

  - `is_settled` (boolean)
    Whether the transaction is settled.

  - `settlement_issue` (string | null)
    An issue preventing the transaction from settling. Null when there is no issue — because the transaction was canceled, has already settled, or is still in an open batch. Read `is_settled` to see whether it settled.
    Enum: "REMOVED_FROM_BATCH", "null"

  - `is_returned` (boolean)
    Whether the transaction has been returned by the processor. A return is a transaction outcome rather than an API error, it arrives days after the transaction was approved, and it can follow a transaction that has already settled - so read this alongside `is_settled` rather than instead of it. Always false on a card transaction.

  - `returned_at` (string | null)
    The time the processor sent the return. In ISO-8601 format (YYYY-MM-DDTHH:MM:SS.SSSZ), UTC, matching `time_created`. Null when the transaction has not been returned.

  - `return_code` (string | null)
    The NACHA return code, three characters. Omitted entirely when the transaction has not been returned, and omitted on a returned transaction the processor sent no code for - not sent as null.

  - `return_reason` (string | null)
    Human-readable description of the reason the processor returned the transaction. Omitted entirely when the transaction has not been returned, the way `return_code` is - not sent as null.

  - `time_created` (string)
    the API server generated time indicating when the object was created.  In ISO-8601 format (YYYY-MM-DDTHH:MM:SS.SSSZ).

  - `amount` (integer)
    Amount in cents (e.g. `10000` = $100.00). All transactions are in US  dollars (USD).

  - `tip` (integer)
    Tip amount in cents (e.g. `1000` = $10.00). If no tip is included, use `0` or omit the field.
`amount` is the whole charge and `tip` declares how much of it is gratuity. The two are not added together: a $100.00 bill with a $20.00 tip is `amount: 12000` with `tip: 2000`, and the cardholder is charged $120.00. The tip is reported to the processor separately at settlement and never increases the settled amount.
Minimum 0 cents ($0.00). Maximum 99,999,999 cents ($999,999.99). All transactions are in US dollars (USD).

  - `tax_amount` (any)
    The tax amount in cents sent when the transaction was created. A capture reports the tax amount of the auth it captures. Null when the transaction was created without a `tax_amount`, including every transaction created before the field existed.

  - `currency` (string)
    Three-letter ISO 4217 currency code for the transaction.
    Enum: "USD"

  - `payment_method` (any)
    Base schema for payment methods returned on a transaction response. Concrete subtypes are discriminated by the `type` property.
A response reports the underlying instrument, so `type` is `CARD` or `ACH`. Paying with a token is not a third kind of response: send `payment_method.type` of `TOKEN` and the gateway resolves the token to the card or bank account behind it, then reports that. The token itself comes back in `payment_token` on either subtype.

  - `payment_method.type` (string, required)
    The type of payment method returned on a response. These are the request values without `TOKEN` — see `PaymentMethodTypeInput`.
A token-funded transaction reports the instrument the token resolves to, so there is no separate token value here. `PaymentMethodTypeInput` still accepts `TOKEN` on the way in.
    Enum: "ACH", "CARD"

  - `payment_method.standard_entry_class` (any)
    ACH Standard Entry Class (SEC) code of the transaction. Null when none was recorded.

  - `payment_method.account_type` (any)
    The type of bank account. Null when none was recorded.

  - `payment_method.route_number_truncated` (string | null)
    Nine-digit ABA routing number truncated to the last 4 digits.

  - `payment_method.account_number_truncated` (string | null)
    Bank account number truncated to the last 4 digits.

  - `payment_method.payment_token` (string | null)
    Reference to a previously stored (tokenized) payment method. A read of a transaction returns null when no token was issued for it.
The response to the request that ran the transaction does not return null today. A declined transaction returns an empty string. An approved one whose payment method could not be tokenized returns the sentence `Payment method could not be tokenized.` Treat a value that starts with none of the prefixes below as no token, and do not store it.
The prefix says what the token stands for: `CARD_TOKEN-` for a card, and `BANK_TOKEN-` for a bank account. Tokens issued before 2026-10-16 start with `PAYMENT_TOKEN-` and keep working, so an older token's prefix does not say what it stands for. Send the value back exactly as it was returned.

  - `payment_method.first_name` (string | null)
    Account holder's first name. On a transaction response this is the name submitted with the request. On a reporting response it is derived by splitting the stored account holder name at the last space, so a single-word stored name returns an empty string here and puts the whole name in `last_name`.

  - `payment_method.last_name` (string | null)
    Account holder's last name.

  - `payment_method.description` (string | null)
    Optional information to include on customer's bank statement. This is a short description that, e.g., identifies the goods or services purchased or the merchant's name. If left blank, the merchant's name will be used as a default description.

  - `payment_method.truncated_pan` (string | null)
    Masked card number with only the last 4 digits visible  (e.g. `****1111`).

  - `payment_method.expiry` (any)
    Card expiration date. Null on capture/void/refund responses where expiry is not echoed back.

  - `payment_method.expiry.month` (string, required)
    Month of the card expiration date as a two-digit number

  - `payment_method.expiry.year` (string, required)
    Year of the card expiration date as a four-digit number. The response to a transaction charged to a card token returns two digits instead, such as `"30"` for 2030, so read a two-digit year as 20YY. A later read of the same transaction returns four.

  - `payment_method.first_name` (string | null)
    First name of the cardholder. Null if not provided, and on cancel and refund responses, which do not repeat it.

  - `payment_method.last_name` (string | null)
    Last name of the cardholder. Null if not provided, and on cancel and refund responses, which do not repeat it.

  - `payment_method.entry_method` (string | null)
    How the card payment method was entered (e.g. `keyed`, `swiped`,  `chip`, `contactless`, `magstripe`, `barcode`, `qr`, `other`).

  - `payment_method.auth_code` (string | null)
    Authorization code generated by the card provider when the card is successfully authorized.

  - `payment_method.retrieval_reference_number` (string | null)
    The retrieval reference number (RRN) is a 12-character alphanumeric  identifier assigned to a card transaction to allow the tracking  of a specific transaction record.

  - `payment_method.card_type` (string)
    The type of card. `UNKNOWN` is returned when the processor cannot determine the card type.
    Enum: "DEBIT", "CREDIT", "UNKNOWN"

  - `payment_method.card_brand` (string | null)
    Card network brand (e.g. `Visa`, `Mastercard`, `Amex`, `Discover`). Null when the processor did not report one.

  - `payment_method.cvv_result_code` (string | null)
    The result returned from a card verification value check. Null on void/refund responses where CVV is not re-checked.

  - `payment_method.avs_result_code` (any)
    The result of the Address Verification Service (AVS) check. May be a single-letter string code or integer `0` when AVS was not performed.

  - `payment_method.avs_response` (string | null)
    Human-readable AVS response message. Null when the processor returned no AVS response.

  - `recurring` (boolean)
    Whether the transaction is part of a recurring payment agreement.

  - `initiator` (any)
    Who initiated the transaction. Null on a transaction read back through `GET /v1/transactions/{id}`, which does not currently return the value supplied on create. Tracked as a gateway defect — treat the value from the create response as authoritative.

  - `recurring_details` (any)
    Stored-credential details for the recurring agreement this transaction belongs to. Null on a one-off transaction.

  - `recurring_details.sequence` (string, required)
    The position of this transaction within a recurring payment agreement.
    Enum: "INITIAL", "SUBSEQUENT"

  - `recurring_details.initial_transaction_id` (string | null)
    The transaction ID of the initial customer-initiated (CIT) transaction that established the recurring payment agreement. Required when `sequence` is `SUBSEQUENT`; omit (or send `null`) on the `INITIAL` transaction.

  - `recurring_details.initial_network_transaction_id` (string | null)
    The network-assigned transaction identifier (Visa Transaction ID / Mastercard Trace ID) returned on the initial authorization that established the agreement. Supply this only when the initial transaction was processed outside this gateway (e.g. migration from another provider). When `initial_transaction_id` references a transaction processed by this gateway, the network ID is resolved automatically and this field may be omitted.

  - `network_transaction_id` (string | null)
    The network-assigned transaction identifier (Visa Transaction ID / Mastercard Trace ID) assigned by the card network. On the initial transaction of a recurring agreement, store this value and supply it as `recurring_details.initial_network_transaction_id` on subsequent transactions billed against the agreement (required when those transactions are processed by a different gateway). Null when the network did not return an identifier.

  - `metadata` (object | null)
    Key-value pairs for storing additional information on the transaction. Send `null` to clear all metadata.
At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected.

## Response 200 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 400 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 401:

  - `401` (unknown)
    Not authenticated

## Response 401 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 401 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 403 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 409:

  - `409` (unknown)
    Conflict

## Response 409 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 409 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 429:

  - `429` (unknown)
    The processor's request limit for this merchant was exceeded, and the transaction was not attempted. TOO_MANY_REQUESTS. Retry after a backoff. No Retry-After header is sent, because no processor documents how long its limits last.

## Response 429 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 429 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 500:

  - `500` (unknown)
    Internal server error

## Response 500 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 500 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 502:

  - `502` (unknown)
    The gateway reached the downstream processor and could not use its response. Distinct from a 500, which is a fault inside the gateway.

## Response 502 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 502 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 503:

  - `503` (unknown)
    The processor is down or unreachable, and did not process the request. PROCESSOR_UNAVAILABLE. Retry after a backoff. Distinct from a 502, which says the processor may have seen the transaction.

## Response 503 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 503 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 200 examples:

  - `Sale with a card — approved` (unknown)
    The approved sale. A `SALE` authorizes and captures in one step, so the transaction joins the open batch and settles at the next batch close. `batch_id` is null until then, because the gateway assigns it at settlement. `reference_transaction_id` is null because this is an original transaction, not a capture, void, or refund of another one. `entry_method` echoes the request value.

  - `Sale with a stored payment token — approved` (unknown)
    The approved token sale. The response reports the card the token resolves to, so `payment_method.type` is `CARD` and the card attributes are present. `payment_token` carries the token that funded it.

  - `Authorization with a card — approved` (unknown)
    The approved authorization. An `AUTH` does not capture, so `batch_id` is null and `is_settled` is false until the transaction is captured. Use this `id` as the path parameter on the Capture operation.

  - `Authorization with a stored payment token — approved` (unknown)
    The approved token authorization. `batch_id` is null until the transaction is captured.

  - `Sale taken by phone or mail — approved` (unknown)
    The approved MOTO sale. `entry_method` echoes `MOTO`, and `cvv_result_code` is null because no CVV was sent.

  - `Sale that includes a tip — approved` (unknown)
    The approved sale. `amount` is the $120.00 charged, and `tip` is the $20.00 of it that is gratuity.

  - `Sale that includes tax — approved` (unknown)
    The approved sale. `amount` is the $105.00 charged, and `tax_amount` is the $5.00 of it that is tax. A transaction created without a `tax_amount` reports `null` here, not `0`.

  - `Sale charged to a stored bank account token — approved` (unknown)
    The approved ACH debit. The response reports the bank account the token resolves to, so `payment_method.type` is `ACH`, and `standard_entry_class` is the code sent with the request. The routing and account numbers are cut to their last four digits.

  - `Payout to a bank account — approved` (unknown)
    The approved payout. `payment_method.type` is `ACH`, and the routing and account numbers are cut to their last four digits, the way they are on any ACH response.
`is_returned` is `false` and `returned_at` is null because nothing has been returned yet. `return_code` and `return_reason` are absent rather than null — they appear only once a return arrives, which can be days after this response. The payout joins the open batch and leaves at the next batch close, so `batch_id` is null until then.

  - `Sale — declined for insufficient funds` (unknown)
    A declined sale. Note this is an HTTP 200 with `result: DECLINED`, not an error response: the request was processed correctly and the issuer declined it. `response_code` `51` is the insufficient-funds code. `batch_id` is null and `is_settled` is false because a declined transaction is never captured or settled. `auth_code` is absent rather than null — the issuer never issued one.

  - `Initial recurring payment — approved` (unknown)
    The approved initial payment. `recurring`, `initiator` and `recurring_details` echo the request, with both initial identifiers null because this transaction is the start of the agreement. `network_transaction_id` is the identifier later charges rely on. A subsequent charge that quotes this `id` does not need to send it, because the gateway looks it up.

  - `Subsequent recurring payment — approved` (unknown)
    The approved recurring payment. `initiator`, `recurring` and `recurring_details` echo the request. The gateway fills in `recurring_details.initial_network_transaction_id` from the initial sale, so the caller does not have to send it. `network_transaction_id` is the new identifier the network assigned to this payment. `batch_id` is null until the batch settles.

## Response 400 examples:

  - `Invalid field value in the request body` (unknown)

  - `A required field is absent` (unknown)

  - `The transaction's state does not allow this operation` (unknown)

  - `A single amount is outside the allowed range` (unknown)

  - `A count or dollar cap over a period is spent` (unknown)
    details names the limit: limit_type is COUNT or AMOUNT, window is DAILY or MONTHLY, and scope is ACCOUNT, one payer's bank account, or MERCHANT, everything the merchant submits. A key whose value is not known is left out. No limit figure or reset time is sent.

## Response 401 examples:

  - `Missing or invalid API key` (unknown)

## Response 403 examples:

  - `Authenticated but not authorized for this action` (unknown)

  - `The merchant is not boarded to the processor this transaction routes to` (unknown)
    A card transaction routes to TSYS and an ACH transaction to VeriCheck. Both details keys are always present. The condition lasts until the merchant is boarded, so retrying does not help.

## Response 409 examples:

  - `The operation has already been done` (unknown)
    A 409 means the same operation was already done, or is already underway: a transaction canceled again, captured again, or refunded again in full. An operation the transaction's state blocks for any other reason is a 400 INVALID_ACTION instead.

## Response 429 examples:

  - `The processor's request limit for this merchant was exceeded` (unknown)

## Response 500 examples:

  - `Unhandled server fault or downstream processor error` (unknown)

  - `The merchant's stored integration record is wrong` (unknown)
    The processor rejected an identifier that came from boarding, not from the request. Retrying does not help until the integration is corrected.

## Response 502 examples:

  - `The processor returned an invalid or unexpected response` (unknown)
    Distinct from a 500. A 500 is a fault inside the gateway; a 502 means the gateway reached the processor and could not use what came back. Both are safe to retry, but only a 502 says the transaction may have been seen by the processor — reconcile before retrying a payment.

## Response 503 examples:

  - `The processor is down or unreachable` (unknown)

