Send transactions

The Send Transactions operations includes APIs for sending payment transactions via credit card or payment token. Transaction types include sales, authorizations, captures, and refund/cancels.

Operations

Create a Transaction

Request

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.

Security

ApiKeyAuth

Client-Idstring, (ulid)required

X-Acting-As-Client-Idstring, (ulid)

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.

Bodyapplication/json

typestring(TransactionCreateType)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 Value	Description
SALE	Requests payment card or ACH authorization with an immediate, automatic capture of authorized funds. Includes payment cards and ACH debits. Funds transferred from customer to merchant.
AUTH	Requests payment card authorization that is not automatically captured. Completed by a manual capture of the authorized funds.
PAYOUT	An ACH credit. Funds transferred from merchant to customer.

amountinteger, (int32), [ 50 .. 99999999 ](Amount)required

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

tipinteger, (int32), [ 0 .. 99999999 ](Tip)

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

currencystring

Three-letter ISO 4217 currency code. Optional; defaults to USD, which is the only value the gateway accepts.

Default:"USD"

Value:"USD"

payment_methodany(PaymentMethodInput)required

initiatorstring(Initiator)

The initiator of the transaction.

Enum Value	Description
MERCHANT	Merchant-initiated transaction (MIT) — billed without the cardholder present.
CUSTOMER	Customer-initiated transaction (CIT) — the cardholder is actively present.
THIRD_PARTY	Initiated by a third party on the merchant's behalf.

recurringboolean

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.

Default:false

recurring_detailsobject(RecurringDetails)

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.

metadataobject or null, <= 50 properties(Metadata)

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.

A single-step sale that authorizes and captures $100.00 in one call, using full card details. This is the transaction the void, refund, and recurring examples all reference.

{
  "type": "SALE",
  "amount": 10000,
  "tip": 0,
  "payment_method": {
    "type": "Card",
    "entry_method": "ECOMMERCE",
    "pan": "4012000098765439",
    "expiry": { … },
    "cvv": "999",
    "first_name": "John",
    "last_name": "Doe",
    "contact": { … },
    "billing_address": { … }
  },
  "initiator": "CUSTOMER",
  "metadata": {
    "order_id": "ORD-10432",
    "sales_channel": "web",
    "customer_reference": "cust-8891"
  }
}

Responses

Transaction created successfully

Headers

x-request-idstring, (uuid)^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...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.

Bodyapplication/json

idstring

Unique identifier for the transaction assigned by the API server.

reference_transaction_idstring or 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.

typestring(TransactionResponseType)

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 Value	Description
SALE	Payment card or ACH authorization with an immediate, automatic capture of the authorized funds. Funds transferred from customer to merchant.
AUTH	Payment card authorization that was not automatically captured, and is completed by a manual capture.
INCREMENTAL_AUTH	An authorization that raised the amount held by an earlier `AUTH`.
PAYOUT	An ACH credit. Funds transferred from merchant to customer.
REFUND	A refund of a settled payment. Funds transferred from merchant to customer.
CANCEL	A payment cancelled before settlement. Covers a void, a reversal, and a reversed transaction, which the gateway reports under this single value.
CAPTURE	Manual capture of an authorized payment.

resultstring(Result)

Enum Value	Description
APPROVED	The transaction was approved by the issuer.
DECLINED	The transaction was declined by the issuer.
ERROR	The transaction experienced an error after it was successfully created by the API server.

client_idstring

The client_id of the client account that requested this transaction.

client_dbastring

Doing Business As (DBA) name of the client account.

integrationsArray of strings(Integrations)

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.

Items Enum Value	Description
TSYS	The TSYS card processor. Returned on card transactions.
VERICHECK	The Vericheck ACH processor. Returned on bank account (ACH) transactions.

response_codestring

Response code generated by the payment processor.

response_descriptionstring

Human-readable description of the transaction outcome.

batch_idstring or null

Unique identifier of the batch containing this transaction. Null when the transaction has not yet been assigned to a batch.

is_settledboolean

Whether the transaction is settled.

settlement_issuestring or null(SettlementIssue)

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.

Value	Description
REMOVED_FROM_BATCH	The transaction was removed from its batch before settlement.

is_returnedboolean

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_atstring or null, (date-time)

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_codestring or 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_reasonstring or 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_createdstring, (date-time)(TimeCreated)

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

amountinteger, (int32), [ 50 .. 99999999 ](Amount)

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

tipinteger, (int32), [ 0 .. 99999999 ](Tip)

Tip amount in cents (e.g. 1000 = $10.00). If no tip is included, use 0 or omit the field.

Minimum 0 cents ($0.00). Maximum 99,999,999 cents ($999,999.99). All transactions are in US dollars (USD).

currencystring

Three-letter ISO 4217 currency code for the transaction.

Value:"USD"

payment_methodany(PaymentMethodOutput)

recurringboolean

Whether the transaction is part of a recurring payment agreement.

initiatorInitiator (string) or null

One of:

Who initiated the transaction, per the card-network stored-credential framework. CUSTOMER = customer-initiated (CIT); MERCHANT = merchant-initiated (MIT).

string(Initiator)

Enum Value	Description
MERCHANT	Merchant-initiated transaction (MIT) — billed without the cardholder present.
CUSTOMER	Customer-initiated transaction (CIT) — the cardholder is actively present.
THIRD_PARTY	Initiated by a third party on the merchant's behalf.

recurring_detailsRecurringDetails (object) or null

One of:

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.

network_transaction_idstring or 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.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.

metadataobject or null, <= 50 properties(Metadata)

Key-value pairs for storing additional information on the transaction. Send null to clear all metadata.

Response

The approved sale. Because a SALE authorizes and captures in one step, batch_id is already assigned and the transaction settles at the next batch close. reference_transaction_id is null because this is an original transaction, not a capture, void, or refund of another one.

{
  "id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC",
  "reference_transaction_id": null,
  "type": "SALE",
  "result": "APPROVED",
  "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB",
  "client_dba": "Acme Jewelry",
  "integrations": [
    "TSYS"
  ],
  "response_code": "00",
  "response_description": "Approved",
  "batch_id": "BATCH-01KEW32V6YNV11T33XGDR7TGWC",
  "is_settled": false,
  "time_created": "2026-07-15T14:22:05Z",
  "amount": 10000,
  "tip": 0,
  "currency": "USD",
  "payment_method": {
    "type": "CARD",
    "truncated_pan": "****-****-****-5439",
    "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB",
    "expiry": { … },
    "first_name": "John",
    "last_name": "Doe",
    "entry_method": "keyed",
    "auth_code": "123456",
    "retrieval_reference_number": "000000603076",
    "card_type": "UNKNOWN",
    "card_brand": "Visa",
    "cvv_result_code": "M",
    "avs_result_code": "Y",
    "avs_response": "Exact Match - Street address and postal code match"
  },
  "initiator": "CUSTOMER",
  "network_transaction_id": "MCC1234567890",
  "metadata": {
    "order_id": "ORD-10432",
    "sales_channel": "web",
    "customer_reference": "cust-8891"
  }
}