{ "openapi": "3.1.1", "info": { "x-audience": "internal", "version": "1.0.0-beta.27", "title": "Gateway API", "contact": { "email": "info@gateway.net" }, "license": { "name": "Gateway API", "identifier": "Gateway API" }, "description": "Our public APIs enable clients to integrate with the Gateway API server. Our APIs use RESTful architecture, conform with OpenAPI specifications, and are PCI-DSS compliant.\n\n### Request IDs\n\nEvery response — successful or not — includes an `x-request-id` header containing a GUID that uniquely identifies the request.\n\n```http\nx-request-id: 73039bd9-c380-4186-bffe-259125144a56\n```\n\nLog this value with your request and supply it when contacting support so that a specific request can be traced.\n\n### Mock responses in this reference\n\nRequests sent from this reference go to a mock server, not the live gateway. Responses are generated from the examples in this description, so the values in them are illustrative and must not be used in a real integration. See the production server in the Servers list for live testing." }, "servers": [ { "url": "https://api.dev.paradisegateway.net", "description": "development server" }, { "url": "https://api.sandbox.paradisegateway.net", "description": "sandbox server" }, { "url": "https://api.paradisegateway.net", "description": "production server" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Batches", "description": "The Batches operations includes APIs for managing batches of transactions." }, { "name": "Close batches", "description": "The Close batches operations includes APIs for closing batches of transactions." }, { "name": "Batch reports", "description": "The Batch reports operations includes APIs for generating reports on batches." }, { "name": "Client accounts", "description": "The Clients service includes APIs for managing client accounts. associated with a client account within the transaction processing system." }, { "name": "Client management", "description": "The Client Management operations includes APIs for managing client accounts. Client types include `RESELLER` and `MERCHANT`." }, { "name": "Client reports", "description": "The Client Reports operations includes APIs for managing client accounts." }, { "name": "Send transactions", "description": "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." }, { "name": "Transactions", "description": "The Transactions service includes APIs for sending payment transaction via credit card. Transaction types include sales, authorizations, completions, and refund/cancels." }, { "name": "Transaction reports", "description": "The Transaction reports operations includes APIs for generating transaction reports." }, { "name": "Integrations", "description": "The Integrations service includes APIs for managing integrations with third-party service providers." }, { "name": "Integration management", "description": "The Integration management operations includes APIs for managing integrations with third-party service providers." }, { "name": "Integration reports", "description": "The Integration reports operations includes APIs for generating reports on integrations." } ], "x-tagGroups": [ { "name": "Transactions", "tags": [ "Send transactions", "Transaction reports" ] }, { "name": "Batches", "tags": [ "Close batches", "Batch reports" ] }, { "name": "Client Accounts", "tags": [ "Client management", "Client reports" ] }, { "name": "Integrations", "tags": [ "Integration management", "Integration reports" ] } ], "paths": { "/v1/batches/close": { "post": { "tags": [ "Close batches" ], "summary": "Close a Batch", "operationId": "closeBatch", "description": "Manually close a batch of transactions. Closing a batch initiates the settlement process for all captured transactions in the batch.", "parameters": [ { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchClose" } } } }, "responses": { "200": { "description": "Batch closed successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCloseResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/v1/clients": { "get": { "tags": [ "Client reports" ], "summary": "List all Clients", "operationId": "listClients", "description": "Return a list of all client accounts.", "parameters": [ { "name": "Take", "in": "query", "schema": { "type": "string" } }, { "name": "Skip", "in": "query", "schema": { "type": "string" } }, { "name": "SortColumn", "in": "query", "schema": { "type": "string" } }, { "name": "SortOrder", "in": "query", "schema": { "$ref": "#/components/schemas/SortOrder" } }, { "name": "SearchText", "in": "query", "schema": { "type": "string" } }, { "name": "Term", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "responses": { "200": { "description": "Client list returned successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllClientsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Client management" ], "summary": "Create a Client", "operationId": "createClient", "description": "Create a new client account. Client types include `reseller` and `merchant`.", "parameters": [ { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientRequest" } } } }, "responses": { "200": { "description": "Client account created successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}": { "get": { "tags": [ "Client reports" ], "summary": "Retrieve a Client", "operationId": "getClient", "description": "Retrieve details of a specific client account.", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "responses": { "200": { "description": "Client details retrieved successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetClientResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Client management" ], "summary": "Update a Client", "operationId": "updateClient", "description": "Update an existing client account.", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientsRequest" } } } }, "responses": { "200": { "description": "Client updated successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/integrations": { "get": { "tags": [ "Integration reports" ], "summary": "List Integrations", "operationId": "listIntegrations", "description": "Return a list of all integrations that the client account has onboarded with.", "parameters": [ { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "responses": { "200": { "description": "Integration list returned successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSummaryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Integration management" ], "summary": "Create an Integration", "operationId": "createIntegration", "description": "Create an integration with a third-party service provider, including payment processors, tokenization services, and other payment services.", "parameters": [ { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCreateRequest" }, "examples": { "tsysIntegration": { "summary": "Onboard a TSYS merchant integration", "description": "A complete TSYS host configuration for the merchant. Twenty-nine of these fields are required — the gateway enforces them in `TsysHostDetailsValidator` — so this payload is close to the minimum a real onboarding needs rather than a generous illustration. The processor-specific identifiers here are illustrative placeholders.", "value": { "client": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "is_active": true, "processor": "Tsys", "integration_details": { "name": "Acme Jewelry LLC", "amex_number": "1234567890", "association": "123456", "bin": "888888", "discover_number": "123456789012345", "dba": "Acme Jewelry", "url": "https://example.apiserver.com", "phone_number": 17035550123, "fax_number": "+17035550199", "mid": "888000001234", "mcc": "5944", "bank_number": "1234", "industry": "R", "amex_opt_blue": true, "agent_chain": "012345", "store_number": "0001", "mvv": "123456", "terminal_number": "0001", "agent_bank_number": "123456", "agent_chain_number": "654321", "descriptor_postal": "22150", "descriptor_city": "Springfield", "descriptor_state": "VA", "descriptor_country": "US", "descriptor_phone": 17035550123, "descriptor_store_number": "0001", "address1": "123 Main St", "address2": "Suite 100", "descriptor_line3": "ACME JEWELRY 703-555-0123", "terminal_id": "00000001", "v_number": "V1234567", "settlement_time": "23:00", "merchant_area_code": 703, "descriptor_area_code": 703, "sharing_group": "AEFGKMQ", "merchant_aba_number": "123456789", "merchant_settlement_agent_number": "1234", "reimbursement_attribute": "0", "fcsid": "12345" } } } } } } }, "responses": { "200": { "description": "Integration created successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationGetResponse" }, "examples": { "tsysIntegration": { "summary": "TSYS merchant integration created", "description": "The stored configuration, echoing back what was submitted and adding the `id` to reference it, the network identifiers TSYS assigns during onboarding (`amex_number`, `discover_number`, `association`, `bin`), and the audit fields.", "value": { "id": "INTEGRATION-01KFDKXMQ637EKEAY410MSQSXB", "is_active": true, "client": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "processor": "Tsys", "integration_details": { "name": "Acme Jewelry LLC", "dba": "Acme Jewelry", "url": "https://example.apiserver.com", "phone_number": 17035550123, "fax_number": "+17035550199", "mid": "888000001234", "amex_number": "1234567890", "association": "VISA", "bin": "431940", "discover_number": "601100999999", "mcc": "5944", "bank_number": "1234", "industry": "R", "amex_opt_blue": true, "agent_chain": "012345", "store_number": "0001", "mvv": "123456", "terminal_number": "0001", "agent_bank_number": "123456", "agent_chain_number": "654321", "descriptor_postal": "22150", "descriptor_city": "Springfield", "descriptor_state": "VA", "descriptor_country": "US", "descriptor_phone": 17035550123, "descriptor_store_number": "0001", "address1": "123 Main St", "address2": "Suite 100", "descriptor_line3": "ACME JEWELRY 703-555-0123", "terminal_id": "00000001", "v_number": "V1234567", "settlement_time": "23:00", "merchant_area_code": 703, "descriptor_area_code": 703, "sharing_group": "AEFGKMQ", "merchant_aba_number": "123456789", "merchant_settlement_agent_number": "1234", "reimbursement_attribute": "0", "fcsid": "12345", "created_by": 1042, "created_at": "2026-02-11T09:24:17Z", "modified_by": 1042, "modified_at": "2026-06-30T14:02:51Z" }, "correlation_id": "01KFDKXMQ637EKEAY410MSQSXB" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/integrations/{id}": { "get": { "tags": [ "Integration reports" ], "summary": "Retrieve an Integration", "operationId": "getIntegration", "description": "Retrieve details of a specific integration.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "responses": { "200": { "description": "Integration retrieved successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationGetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Integration management" ], "summary": "Update an Integration", "operationId": "updateIntegration", "description": "Update an existing integration with a third-party service provider.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationUpdateRequest" } } } }, "responses": { "200": { "description": "Integration updated successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationGetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/integrations/summary/{id}": { "get": { "tags": [ "Integration reports" ], "summary": "List Integration Summary", "operationId": "listIntegrationSummary", "description": "Return a summary list of integrations for a specific client.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "responses": { "200": { "description": "Integration summary returned successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSummaryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/transactions": { "post": { "tags": [ "Send transactions" ], "summary": "Create a Transaction", "operationId": "createTransaction", "description": "Create a payment transaction via a payment card (credit or debit).\n\n- A `SALE` transaction authorizes and captures the payment simultaneously.\n- An `AUTH` transaction authorizes the payment and requires a subsequent capture.", "parameters": [ { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCreateRequest" }, "examples": { "saleWithCard": { "summary": "Sale with a card", "description": "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.", "x-discriminator-value": "Card", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "Card", "entry_method": "ECOMMERCE", "pan": "4012000098765439", "expiry": { "month": 1, "year": 2028 }, "cvv": "999", "first_name": "John", "last_name": "Doe", "contact": { "phone": "+17035550123", "email": "john.doe@example.com" }, "billing_address": { "line1": "123 Main St", "line2": "Suite 100", "city": "Springfield", "state": "VA", "postal_code": "22150", "country": "US" } }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10432", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "saleWithToken": { "summary": "Sale with a stored payment token", "description": "The same $100.00 sale, charged against a previously stored payment token instead of raw card details. No PAN, expiry, or CVV is sent.", "x-discriminator-value": "Token", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "Token", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB" }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10433", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "authWithCard": { "summary": "Authorization with a card", "description": "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.", "x-discriminator-value": "Card", "value": { "type": "AUTH", "amount": 10000, "tip": 0, "payment_method": { "type": "Card", "entry_method": "ECOMMERCE", "pan": "4012000098765439", "expiry": { "month": 1, "year": 2028 }, "cvv": "999", "first_name": "John", "last_name": "Doe", "contact": { "phone": "+17035550123", "email": "john.doe@example.com" }, "billing_address": { "line1": "123 Main St", "line2": "Suite 100", "city": "Springfield", "state": "VA", "postal_code": "22150", "country": "US" } }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10434", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "authWithToken": { "summary": "Authorization with a stored payment token", "description": "A two-step authorization charged against a stored payment token. The `captureToken` example on the Capture operation captures this one.", "x-discriminator-value": "Token", "value": { "type": "AUTH", "amount": 10000, "tip": 0, "payment_method": { "type": "Token", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB" }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10435", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "saleWithBankAccount": { "summary": "Sale charged to a bank account (ACH)", "description": "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.\n\n`routing_number` is exactly nine digits and `account_number` is four to twenty. `standard_entry_class` and `description` are both optional; they default to `WEB` and `ACH Transaction`. `first_name` and `last_name` are supplied because the ACH processor requires them.\n\nA bank account accepts `SALE` and `PAYOUT`. It does not accept `AUTH`.", "x-discriminator-value": "ACH", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "ACH", "account_type": "CHECKING", "routing_number": "021000021", "account_number": "123456789012", "standard_entry_class": "WEB", "first_name": "John", "last_name": "Doe", "description": "Blue jeans" }, "metadata": { "order_id": "ORD-10438", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "payout": { "summary": "Payout to a bank account (ACH credit)", "description": "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.\n\nThe 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.\n\nA 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`.", "x-discriminator-value": "ACH", "value": { "type": "PAYOUT", "amount": 25000, "tip": 0, "payment_method": { "type": "ACH", "account_type": "CHECKING", "routing_number": "021000021", "account_number": "123456789012", "standard_entry_class": "CCD", "first_name": "Dana", "last_name": "Reyes", "description": "Vendor payment" }, "metadata": { "invoice_id": "INV-2291", "sales_channel": "api" } } }, "saleDeclined": { "summary": "Sale that returns a decline", "description": "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.\n\nSelecting 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`.", "x-discriminator-value": "Card", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "Card", "entry_method": "ECOMMERCE", "pan": "4012000098765439", "expiry": { "month": 1, "year": 2028 }, "cvv": "999", "first_name": "John", "last_name": "Doe", "contact": { "phone": "+17035550123", "email": "john.doe@example.com" }, "billing_address": { "line1": "123 Main St", "line2": "Suite 100", "city": "Springfield", "state": "VA", "postal_code": "22150", "country": "US" } }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10436", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "saleRecurringSubsequent": { "summary": "Subsequent recurring payment on a stored credential", "description": "A merchant-initiated (MIT) payment billed against the stored-credential agreement that `saleWithCard` established.\n\nThree 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`.\n\n`initial_transaction_id` points at the transaction returned by `saleWithCard`. Use `initial_network_transaction_id` instead when the agreement began outside this gateway. No CVV is sent — the cardholder is not present.", "x-discriminator-value": "Card", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "Card", "entry_method": "ECOMMERCE", "pan": "4012000098765439", "expiry": { "month": 1, "year": 2028 }, "first_name": "John", "last_name": "Doe", "billing_address": { "line1": "123 Main St", "line2": "Suite 100", "city": "Springfield", "state": "VA", "postal_code": "22150", "country": "US" } }, "initiator": "MERCHANT", "recurring_details": { "sequence": "SUBSEQUENT", "initial_transaction_id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC" }, "metadata": { "order_id": "ORD-10437", "sales_channel": "recurring", "customer_reference": "cust-8891" } } } } } } }, "responses": { "200": { "description": "Transaction created successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "examples": { "saleWithCard": { "summary": "Sale with a card — approved", "description": "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.", "value": { "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": { "month": "01", "year": "2028" }, "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" } } }, "saleWithToken": { "summary": "Sale with a stored payment token — approved", "description": "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.", "value": { "id": "TRANSACTION-01KEW33H5PQ2K8M4VNCDW7YRT9", "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:31:47Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": { "month": "01", "year": "2028" }, "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-10433", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "authWithCard": { "summary": "Authorization with a card — approved", "description": "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.", "value": { "id": "TRANSACTION-01KEW32V6YNV11T336VEDKL123", "reference_transaction_id": null, "type": "AUTH", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "00", "response_description": "Approved", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:02:11Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": { "month": "01", "year": "2028" }, "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-10434", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "authWithToken": { "summary": "Authorization with a stored payment token — approved", "description": "The approved token authorization. `batch_id` is null until the transaction is captured.", "value": { "id": "TRANSACTION-01KEW34J7RS3N9P5WQDEX8ZTB2", "reference_transaction_id": null, "type": "AUTH", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "00", "response_description": "Approved", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:14:39Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": { "month": "01", "year": "2028" }, "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-10435", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "payout": { "summary": "Payout to a bank account — approved", "description": "The approved payout. `payment_method.type` is `ACH` and the account identifiers are truncated, the way they are on any ACH response.\n\n`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. `batch_id` is assigned, so the payout leaves at the next batch close.", "value": { "id": "TRANSACTION-01KEW3J7NRW9T4M2QVBXK8HZD3", "reference_transaction_id": null, "type": "PAYOUT", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "VERICHECK" ], "response_code": "00", "response_description": "Approved", "batch_id": "BATCH-01KEW32V6YNV11T33XGDR7TGWC", "is_settled": false, "is_returned": false, "returned_at": null, "time_created": "2026-07-15T17:31:44Z", "amount": 25000, "tip": 0, "currency": "USD", "payment_method": { "type": "ACH", "standard_entry_class": "CCD", "account_type": "CHECKING", "route_number_truncated": "****21", "account_number_truncated": "****9012", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637ETEAY410MSQTUH", "first_name": "Dana", "last_name": "Reyes", "description": "Vendor payment" }, "metadata": { "invoice_id": "INV-2291", "sales_channel": "api" } } }, "saleDeclined": { "summary": "Sale — declined for insufficient funds", "description": "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.", "value": { "id": "TRANSACTION-01KEW36C9TQ5N1P7YRFGZ0BVW4", "reference_transaction_id": null, "type": "SALE", "result": "DECLINED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "51", "response_description": "Insufficient funds", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:47:52Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "retrieval_reference_number": "000000603077", "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": null, "metadata": { "order_id": "ORD-10436", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "saleRecurringSubsequent": { "summary": "Subsequent recurring payment — approved", "description": "The approved recurring payment. `initiator` and `recurring_details` echo the request, and `network_transaction_id` carries the network-assigned identifier that links this payment to the agreement. The payment falls in a later batch than the initial sale.", "value": { "id": "TRANSACTION-01KEW3D4YMV8Q7T3FNJZ2XPB56", "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-01KEXA7M2QP5N8T3VDFGH1JKR9", "is_settled": false, "time_created": "2026-08-15T09:00:00Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "auth_code": "123456", "retrieval_reference_number": "000000603078", "card_type": "UNKNOWN", "card_brand": "Visa", "cvv_result_code": null, "avs_result_code": "Y", "avs_response": "Exact Match - Street address and postal code match" }, "initiator": "MERCHANT", "recurring_details": { "sequence": "SUBSEQUENT", "initial_transaction_id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC" }, "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10437", "sales_channel": "recurring", "customer_reference": "cust-8891" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } }, "get": { "tags": [ "Transaction reports" ], "summary": "List Transactions", "operationId": "listTransactions", "description": "Return a list of payment transactions for a merchant account. Use the query parameters to filter and sort the results.\n\n### Examples\n\n**50 approved Sale transactions:**\n```http\nGET /v1/transactions?type=sale&result=approved&limit=50\n```\n\n**Declined transactions in January 2026:**\n```http\nGET /v1/transactions?result=declined&created.gte=2026-01-01T00:00:00Z&created.lte=2026-01-31T23:59:59Z\n```\n\n**A child merchant's transactions (reseller viewing merchant):**\n```http\nGET /v1/transactions?client_id=CLIENT-01KFDKXMQ637EKEAY410MSQSXB\n```\n\n**Page through results — skip first 100, return next 25, sorted by amount descending:**\n```http\nGET /v1/transactions?offset=100&limit=25&sort_by=amount&sort_order=desc\n```\n\n**All Sales and Authorizations for a merchant in a date range:**\n```http\nGET /v1/transactions?type=sale,auth&client_id=CLIENT-01KFDKXMQ637EKEAY410MSQSXB&created.gte=2026-03-01T00:00:00Z&created.lte=2026-03-31T23:59:59Z\n```", "parameters": [ { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/BatchId" }, { "$ref": "#/components/parameters/IsSettled" }, { "$ref": "#/components/parameters/CardType" }, { "$ref": "#/components/parameters/Integration" }, { "$ref": "#/components/parameters/ClientId" }, { "$ref": "#/components/parameters/Type" }, { "$ref": "#/components/parameters/Result" }, { "$ref": "#/components/parameters/CreatedGte" }, { "$ref": "#/components/parameters/CreatedLte" }, { "$ref": "#/components/parameters/SortBy" }, { "$ref": "#/components/parameters/SortOrder" } ], "responses": { "200": { "description": "Payment transaction list returned successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsListResponse" }, "examples": { "transactionList": { "summary": "First page of a transaction list", "description": "Three transactions from the same merchant and batch — the approved sale, the approved authorization, and the declined sale. `total_count` is 3 and `limit` is 10, so `has_more` is false and there is no next page to fetch.", "value": { "total_count": 3, "limit": 10, "offset": 0, "has_more": false, "transactions": [ { "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", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "auth_code": "123456", "retrieval_reference_number": "000000603076", "card_type": "CREDIT", "card_brand": "Visa", "cvv_result_code": "M", "avs_result_code": "Y" }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10432" } }, { "id": "TRANSACTION-01KEW32V6YNV11T336VEDKL123", "reference_transaction_id": null, "type": "AUTH", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "00", "response_description": "Approved", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:02:11Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "auth_code": "123456", "retrieval_reference_number": "000000603076", "card_type": "CREDIT", "card_brand": "Visa", "cvv_result_code": "M", "avs_result_code": "Y" }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10434" } }, { "id": "TRANSACTION-01KEW36C9TQ5N1P7YRFGZ0BVW4", "reference_transaction_id": null, "type": "SALE", "result": "DECLINED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "51", "response_description": "Insufficient funds", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:47:52Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "retrieval_reference_number": "000000603077", "card_type": "CREDIT", "card_brand": "Visa", "cvv_result_code": "M", "avs_result_code": "Y" }, "initiator": "CUSTOMER", "network_transaction_id": null, "metadata": { "order_id": "ORD-10436" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/transactions/{id}": { "get": { "tags": [ "Transaction reports" ], "summary": "Retrieve a Transaction", "operationId": "retrieveTransaction", "description": "Retrieve the details of a specific transaction.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "responses": { "200": { "description": "Transaction details retrieved successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "examples": { "saleWithCard": { "summary": "The same sale, read back from reporting", "description": "The sale from `SaleWithCardResponseExample`, read back after the processor reported the card type. Everything else is unchanged; the one difference is `payment_method.card_type`, which was `UNKNOWN` on the transaction response and is `CREDIT` here. See `TransactionResponse` for why the two differ.", "value": { "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": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "auth_code": "123456", "retrieval_reference_number": "000000603076", "card_type": "CREDIT", "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" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/transactions/{id}/capture": { "post": { "tags": [ "Send transactions" ], "summary": "Capture a Transaction", "operationId": "captureTransaction", "description": "Capture an authorized transaction. A captured transaction will be settled during the next scheduled batch closure and funds will be transferred from the cardholder's account to the merchant's account. This operation is only available for approved authorization requests.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the transaction to capture. You can find the transaction ID in the response of the original authorization transaction.", "required": true, "schema": { "type": "string" }, "examples": { "captureCard": { "summary": "The card authorization returned by authWithCard", "value": "TRANSACTION-01KEW32V6YNV11T336VEDKL123" }, "captureToken": { "summary": "The token authorization returned by authWithToken", "value": "TRANSACTION-01KEW34J7RS3N9P5WQDEX8ZTB2" } } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCaptureRequest" }, "examples": { "captureCard": { "summary": "Capture a card authorization", "description": "Captures the full $100.00 authorized by `authWithCard`. Send this to the transaction ID returned by that authorization.", "value": { "amount": 10000, "tip": 0 } }, "captureToken": { "summary": "Capture a stored-token authorization", "description": "Captures the full $100.00 authorized by `authWithToken`. The capture request body is identical whichever payment method the authorization used — only the response differs.", "value": { "amount": 10000, "tip": 0 } } } } } }, "responses": { "200": { "description": "Transaction captured successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "examples": { "captureCard": { "summary": "Capture a card authorization — approved", "description": "The capture record. It is a new transaction whose `reference_transaction_id` points at the authorization it captured. `expiry` is null because expiry is not echoed back on capture responses. `batch_id` is now assigned, so the funds settle at the next batch close.", "value": { "id": "TRANSACTION-01KEW35B8QP4M2X9YHFT0KDN47", "reference_transaction_id": "TRANSACTION-01KEW32V6YNV11T336VEDKL123", "type": "CAPTURE", "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-15T16:08:23Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": null, "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" }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10434", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "captureToken": { "summary": "Capture a stored-token authorization — approved", "description": "The capture record for a token authorization. `payment_method` reports the card the token resolves to, with `expiry` null because a capture does not echo it, and `reference_transaction_id` points at the authorization it captured.", "value": { "id": "TRANSACTION-01KEW37D0SR6P2Q8ZTGHA1CWX5", "reference_transaction_id": "TRANSACTION-01KEW34J7RS3N9P5WQDEX8ZTB2", "type": "CAPTURE", "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-15T16:19:05Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": null, "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" }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10435", "sales_channel": "web", "customer_reference": "cust-8891" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/v1/transactions/{id}/cancel": { "post": { "tags": [ "Send transactions" ], "summary": "Cancel (void) or refund a transaction", "operationId": "cancelTransaction", "description": "Cancel (void) a transaction or refund a transaction.\n\n- Select type `VOID` to void a transaction before settlement.\n- Select type `REFUND` to refund a transaction after settlement.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the transaction to cancel or refund.", "required": true, "schema": { "type": "string" }, "examples": { "voidTransaction": { "summary": "The sale returned by saleWithCard, voided before settlement", "value": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC" }, "refundTransaction": { "summary": "The same sale, partially refunded after settlement", "value": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC" } } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TransactionCancelRequest" }, { "$ref": "#/components/schemas/TransactionRefundRequest" } ] }, "examples": { "voidTransaction": { "summary": "Void an unsettled transaction", "description": "Voids the sale created by `saleWithCard` before it settles. A void needs only the transaction `type`; the amount is always the full original amount. Send it to the transaction ID being voided.", "value": { "type": "VOID" } }, "refundTransaction": { "summary": "Partially refund a settled transaction", "description": "Refunds $25.00 of the $100.00 sale created by `saleWithCard`. The amount must be less than or equal to the original transaction amount; this partial refund shows that rule in use. Send it to the transaction ID being refunded.", "value": { "type": "REFUND", "amount": 2500 } } } } } }, "responses": { "200": { "description": "Transaction canceled or refunded successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "examples": { "voidTransaction": { "summary": "Void — approved", "description": "The void record. `type` comes back as `CANCEL`, which is the type returned on void and refund response records, and `reference_transaction_id` points at the sale that was voided. `expiry` and `cvv_result_code` are null because neither is re-checked on a void.", "value": { "id": "TRANSACTION-01KEW38F2RT6N4Z1AJGV5MPQ82", "reference_transaction_id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC", "type": "CANCEL", "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-15T17:30:44Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": null, "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": null }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10432", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "refundTransaction": { "summary": "Partial refund — approved", "description": "The refund record. `amount` is the refunded amount, not the original sale amount. `type` comes back as `CANCEL`, and `reference_transaction_id` points at the sale that was refunded. The refund lands in the next open batch, so its own `batch_id` is not yet assigned.", "value": { "id": "TRANSACTION-01KEW3B7XKC9P5W2DMHY6NRS13", "reference_transaction_id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC", "type": "REFUND", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "00", "response_description": "Approved", "batch_id": null, "is_settled": false, "time_created": "2026-07-16T10:12:58Z", "amount": 2500, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": null, "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": null }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10432", "sales_channel": "web", "customer_reference": "cust-8891" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/v1/batches": { "get": { "tags": [ "Batch reports" ], "summary": "List Batches", "operationId": "listBatches", "description": "Return a list of batches. Use the query parameters to filter and sort the results.", "parameters": [ { "name": "skip", "in": "query", "schema": { "type": "string" } }, { "name": "take", "in": "query", "schema": { "type": "string" } }, { "name": "sort_column", "in": "query", "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "schema": { "$ref": "#/components/schemas/SortOrder" } }, { "name": "search_text", "in": "query", "schema": { "type": "string" } }, { "name": "term", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "responses": { "200": { "description": "Batch list returned successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchElasticModelTransResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/batches/status": { "get": { "tags": [ "Batch reports" ], "summary": "List Batch Status", "operationId": "listBatchStatus", "description": "Return the status of batches for a client.", "parameters": [ { "name": "client_id", "in": "query", "schema": { "type": "string" } }, { "name": "last_checked_at", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" } ], "responses": { "200": { "description": "Batch status returned successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/batches/transactions": { "get": { "tags": [ "Batch reports" ], "summary": "List Transactions in a Batch without Batch ID", "operationId": "listBatchTransactionsUnknownBatchId", "description": "Return a list of transactions in a batch without a batch ID. Use this endpoint to return a list of transactions in an open batch. Open batches do not have a batch ID. (Batch ID assigned when settlement request sent to host processor.)", "parameters": [ { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/ClientId" }, { "$ref": "#/components/parameters/Integration" }, { "$ref": "#/components/parameters/OpenBatchCardType" }, { "$ref": "#/components/parameters/CreatedAt" }, { "$ref": "#/components/parameters/TimeZone" } ], "responses": { "200": { "description": "Transaction list returned successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/batches/{id}/transactions": { "get": { "tags": [ "Batch reports" ], "summary": "List Transactions in a Batch with Batch ID", "operationId": "listBatchTransactions", "description": "Return a list of transactions in a batch.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Client-Id" }, { "$ref": "#/components/parameters/X-Acting-As-Client-Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/IncludeBadTransactions" } ], "responses": { "200": { "description": "Transaction list returned successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "schemas": { "Address": { "title": "Address", "description": "Address object.", "properties": { "line1": { "maxLength": 50, "type": "string", "description": "Primary street address line.", "examples": [ "123 Main St" ] }, "line2": { "maxLength": 50, "type": "string", "description": "Secondary address line (suite, apt, floor, etc.).", "examples": [ "Suite 100" ] }, "city": { "maxLength": 50, "type": "string", "description": "City name.", "examples": [ "Springfield" ] }, "state": { "maxLength": 2, "type": "string", "description": "Two-letter US state code (e.g. `VA`).", "examples": [ "VA" ] }, "postal_code": { "maxLength": 10, "pattern": "^[a-zA-Z0-9]+(-|\\s?)[a-zA-Z0-9]+$", "type": "string", "description": "ZIP or postal code.", "examples": [ "22150" ] }, "country": { "maxLength": 2, "type": "string", "description": "Two-letter ISO 3166-1 alpha-2 country code (e.g. `US`).", "examples": [ "US" ] } }, "additionalProperties": false }, "BankAccountType": { "type": "string", "description": "The type of bank account.", "enum": [ "CHECKING", "SAVINGS" ], "x-enumDescriptions": { "CHECKING": "Checking account.", "SAVINGS": "Savings account." }, "examples": [ "CHECKING", "SAVINGS" ] }, "BankAccountInput": { "description": "Request object for Bank Account (ACH) payment method.", "type": "object", "required": [ "type", "account_number", "account_type", "first_name", "last_name", "routing_number" ], "properties": { "type": { "$ref": "#/components/schemas/PaymentMethodTypeInput", "const": "ACH", "description": "The type of payment method." }, "standard_entry_class": { "$ref": "#/components/schemas/StandardEntryClass", "default": "WEB" }, "account_type": { "$ref": "#/components/schemas/BankAccountType" }, "routing_number": { "minLength": 9, "maxLength": 9, "pattern": "^\\d{9}$", "type": "string", "description": "Nine-digit ABA routing number.", "examples": [ "021000021" ] }, "account_number": { "minLength": 4, "maxLength": 20, "pattern": "^\\d{4,20}$", "type": "string", "description": "Bank account number.", "examples": [ "123456789012" ] }, "first_name": { "type": "string", "description": "Account holder's first name.", "examples": [ "John" ] }, "last_name": { "type": "string", "description": "Account holder's last name.", "examples": [ "Doe" ] }, "description": { "type": "string", "description": "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. Only the first 10 characters will appear on the bank statement. Defaults to `ACH Transaction` when omitted.", "default": "ACH Transaction", "maxLength": 30, "examples": [ "Frank's Garage", "Acme LLC", "Blue jeans", "Bob's Burgers" ] } }, "additionalProperties": false }, "BankAccountOutput": { "type": "object", "description": "New bank account (ACH) payment method details for tokenization or direct use.", "readOnly": true, "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/PaymentMethodTypeOutput", "const": "ACH" }, "standard_entry_class": { "$ref": "#/components/schemas/StandardEntryClass" }, "account_type": { "$ref": "#/components/schemas/BankAccountType" }, "route_number_truncated": { "type": "string", "description": "Nine-digit ABA routing number truncated to the last 4 digits.", "examples": [ "0210" ] }, "account_number_truncated": { "type": "string", "description": "Bank account number truncated to the last 4 digits.", "examples": [ "1234" ], "readOnly": true }, "payment_token": { "$ref": "#/components/schemas/PaymentToken" }, "first_name": { "type": "string", "description": "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`.", "examples": [ "John" ] }, "last_name": { "type": "string", "description": "Account holder's last name.", "examples": [ "Doe" ] }, "description": { "type": "string", "description": "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.", "maxLength": 30, "examples": [ "Frank's Pool Hall", "Acme Jewelry", "Blue jeans", "Bob's Burgers" ] } }, "additionalProperties": false }, "ClientAddress": { "title": "ClientAddress", "description": "A client address, including a `type` that identifies its purpose (`LEGAL`, `BILLING`, or `PHYSICAL`).", "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ClientAddressType" }, "line1": { "maxLength": 50, "type": "string", "description": "Primary street address line.", "examples": [ "123 Main St" ] }, "line2": { "maxLength": 50, "type": "string", "description": "Secondary address line (suite, apt, floor, etc.).", "examples": [ "Suite 100" ] }, "city": { "maxLength": 50, "type": "string", "description": "City name.", "examples": [ "Springfield" ] }, "state": { "maxLength": 2, "type": "string", "description": "Two-letter US state code (e.g. `VA`).", "examples": [ "VA" ] }, "postal_code": { "maxLength": 10, "pattern": "^[a-zA-Z0-9]+(-|\\s?)[a-zA-Z0-9]+$", "type": "string", "description": "ZIP or postal code.", "examples": [ "22150" ] }, "country": { "maxLength": 2, "type": "string", "description": "Two-letter ISO 3166-1 alpha-2 country code (e.g. `US`).", "examples": [ "US" ] } }, "additionalProperties": false }, "ClientAddressType": { "type": "string", "description": "The purpose of this address.", "enum": [ "LEGAL", "BILLING", "PHYSICAL" ], "x-enumDescriptions": { "LEGAL": "The client's registered legal address.", "BILLING": "The address used for billing the client.", "PHYSICAL": "The client's physical location address." }, "default": "LEGAL", "examples": [ "LEGAL", "BILLING", "PHYSICAL" ] }, "Amount": { "type": "integer", "format": "int32", "title": "Amount", "description": "Amount in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).", "minimum": 50, "maximum": 99999999, "examples": [ 10000, 100000, 1000000 ] }, "AvsResultCode": { "oneOf": [ { "type": "string", "enum": [ "A", "B", "N", "P", "R", "S", "U", "W", "X", "Y", "Z" ] }, { "type": "integer", "description": "Numeric code returned when AVS was not performed or is inapplicable. `0` indicates no AVS check was requested.", "enum": [ 0 ] } ], "x-enumDescriptions": { "0": "AVS not requested or not applicable.", "A": "The street address matched, but the postal code did not.", "B": "No address information was provided or transaction declined.", "N": "Neither the street address nor postal code matched.", "P": "AVS is not applicable for this transaction.", "R": "Retry — AVS was unavailable or timed out.", "S": "AVS is not supported by card issuer.", "U": "Address information is unavailable.", "W": "The US ZIP+4 code matches, but the street address does not.", "X": "Both the street address and the US ZIP+4 code matched.", "Y": "The street address and postal code matched.", "Z": "The postal code matched, but the street address did not." }, "description": "The result of the Address Verification Service (AVS) check. May be a single-letter string code or integer `0` when AVS was not performed.", "examples": [ "A", "Y", 0 ] }, "BatchClose": { "required": [ "batch_type", "client_id", "created_at", "processor" ], "type": "object", "description": "Request body for manually closing a batch of transactions.", "properties": { "client_id": { "type": "string", "description": "The unique identifier of the client whose batch should be closed.", "examples": [ "CLIENT-01KFDKXMQ637EKEAY410MSQSXB" ] }, "batch_id": { "type": [ "string", "null" ], "description": "The unique identifier of the specific batch to close. Omit to close all open batches for the client.", "examples": [ "BATCH-01KEW32V6YNV11T33XGDR7TGWC" ] }, "processor": { "$ref": "#/components/schemas/Processor" }, "batch_type": { "$ref": "#/components/schemas/BatchType" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the batch was created.", "examples": [ "2026-07-15T08:00:00Z" ] }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone identifier for the batch (e.g. `America/New_York`).", "examples": [ "America/New_York" ] } }, "additionalProperties": false }, "BatchCloseResponse": { "required": [ "response_text" ], "type": "object", "description": "Response returned after a batch close operation.", "properties": { "response_text": { "type": "string", "description": "Human-readable message describing the outcome of the batch close.", "examples": [ "Batch closed successfully. 1 batch submitted for settlement." ] }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "BatchElasticModel": { "required": [ "approved_amount", "batch_id", "batch_number", "batch_type", "captured_amount", "client_dba", "client_id", "closed_at_date_time", "created_at", "created_at_date_time", "id", "net_amount", "processor", "refund_amount", "request", "response", "settled_at_date_time", "status", "void_amount" ], "type": "object", "description": "A batch record returned from the transaction search index.", "properties": { "id": { "type": "string", "description": "Unique identifier for the batch assigned by the API server.", "examples": [ "BATCH-01KEW32V6YNV11T33XGDR7TGWC" ] }, "processor": { "type": [ "string", "null" ], "description": "The payment processor that processed this batch. Null when the processor is unknown or not assigned.", "examples": [ "TSYS" ] }, "status": { "type": "string", "description": "Current status of the batch (e.g. `open`, `closed`, `settled`).", "examples": [ "closed" ] }, "client_id": { "type": "string", "description": "Unique identifier of the client that owns this batch.", "examples": [ "CLIENT-01KFDKXMQ637EKEAY410MSQSXB" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the batch was closed. Null if still open.", "examples": [ "2026-07-15T23:00:12Z" ] }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the batch was settled. Null if not yet settled.", "examples": [ "2026-07-16T02:14:33Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the batch was created.", "examples": [ "2026-07-15T08:00:00Z" ] }, "client_dba": { "type": "string", "description": "Doing Business As (DBA) name of the client.", "examples": [ "Acme Jewelry" ] }, "net_amount": { "type": "integer", "format": "int64", "description": "Net batch amount in dollars (approved minus refunds and voids). Amount in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).", "examples": [ 4550000 ] }, "approved_amount": { "type": "integer", "format": "int64", "description": "Total approved transaction amount in dollars. Amount in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).", "examples": [ 4800000 ] }, "captured_amount": { "type": "integer", "format": "int64", "description": "Total captured transaction amount in dollars. Amount in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).", "examples": [ 4800000 ] }, "void_amount": { "type": "integer", "format": "int64", "description": "Total voided transaction amount in dollars. Amount in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).", "examples": [ 150000 ] }, "refund_amount": { "type": "integer", "format": "int64", "description": "Total refunded transaction amount in dollars. Amount in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).", "examples": [ 100000 ] }, "request": { "type": [ "string", "null" ], "description": "Raw request payload sent to the processor for batch close. Null when not available.", "examples": [ "{\"batch_number\":42,\"transaction_count\":17}" ] }, "response": { "type": [ "string", "null" ], "description": "Raw response payload received from the processor. Null when not available.", "examples": [ "{\"response_code\":\"00\",\"batch_number\":42}" ] }, "batch_number": { "type": "integer", "format": "int32", "description": "Sequential batch number assigned by the processor.", "examples": [ 42 ] }, "batch_type": { "type": "string", "description": "The type of batch (e.g. `Credit` or `Debit`).", "examples": [ "Credit" ] }, "batch_id": { "type": "string", "description": "Unique batch identifier assigned by the API server.", "examples": [ "BATCH-01KEW32V6YNV11T33XGDR7TGWC" ] }, "closed_at_date_time": { "type": [ "string", "null" ], "description": "Human-readable form of `closed_at`, in the gateway's local time with no offset. Null while the batch is still open. Twelve-hour clock — prefer `closed_at`, which is ISO 8601 and unambiguous.", "examples": [ "06/05/2026 02:00:51 PM" ] }, "settled_at_date_time": { "type": [ "string", "null" ], "description": "Human-readable form of `settled_at`, in the gateway's local time with no offset. Null until the batch settles. Twelve-hour clock — prefer `settled_at`, which is ISO 8601 and unambiguous.", "examples": [ "06/05/2026 02:14:33 PM" ] }, "created_at_date_time": { "type": "string", "description": "Human-readable form of `created_at`, in the gateway's local time with no offset. Twelve-hour clock — prefer `created_at`, which is ISO 8601 and unambiguous.", "examples": [ "06/03/2026 03:08:14 PM" ] }, "batch_net_deposit": { "type": [ "integer", "null" ], "format": "int64", "description": "Net amount deposited for the batch, in cents (e.g. `10000` = $100.00). Null until the processor reports it.", "examples": [ 4550000 ] } }, "additionalProperties": false }, "BatchElasticModelTransResponse": { "required": [ "count", "results" ], "type": "object", "description": "Paginated response containing a list of batch records.", "properties": { "count": { "type": "integer", "format": "int64", "description": "Total number of batch records matching the query.", "examples": [ 3 ] }, "results": { "type": "array", "description": "List of batch records.", "items": { "$ref": "#/components/schemas/BatchElasticModel" } }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "CardInput": { "description": "Credit or debit card details for tokenization or direct use in a transaction.", "type": "object", "required": [ "type", "pan", "expiry" ], "properties": { "type": { "$ref": "#/components/schemas/PaymentMethodTypeInput", "const": "Card", "description": "The type of payment method.", "examples": [ "Card" ] }, "pan": { "type": "string", "description": "Primary account number (PAN) — the full card number.", "pattern": "^\\d{14,19}$", "examples": [ "4012000098765439", "4012881888818888" ] }, "expiry": { "$ref": "#/components/schemas/ExpiryInput" }, "cvv": { "pattern": "^\\d{3,4}$", "type": "string", "description": "Card verification value (CVV/CVC) — three digits for Visa, Mastercard, Discover. Four digits for American Express.", "examples": [ "999" ] }, "first_name": { "type": "string", "description": "First name of the cardholder.", "examples": [ "John" ] }, "last_name": { "type": "string", "description": "Last name of the cardholder.", "examples": [ "Doe" ] }, "contact": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneNullable" }, "email": { "$ref": "#/components/schemas/Email" } } }, "billing_address": { "$ref": "#/components/schemas/Address" }, "entry_method": { "$ref": "#/components/schemas/EntryMethod" } }, "additionalProperties": false }, "CardOutput": { "description": "Credit or debit card details returned on a transaction response.", "required": [ "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PaymentMethodTypeOutput", "const": "CARD", "description": "The type of payment method.", "examples": [ "CARD" ] }, "truncated_pan": { "type": "string", "description": "Masked card number with only the last 4 digits visible (e.g. `****1111`).", "examples": [ "****-****-****-5439" ] }, "payment_token": { "$ref": "#/components/schemas/PaymentToken" }, "expiry": { "oneOf": [ { "$ref": "#/components/schemas/Expiry" }, { "type": "null" } ], "description": "Card expiration date. Null on capture/void/refund responses where expiry is not echoed back.", "examples": [ { "month": "01", "year": "2028" } ] }, "first_name": { "type": [ "string", "null" ], "description": "First name of the cardholder. Null if not provided.", "examples": [ "John" ] }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the cardholder. Null if not provided.", "examples": [ "Doe" ] }, "entry_method": { "type": "string", "description": "How the card payment method was entered (e.g. `keyed`, `swiped`, `chip`, `contactless`, `magstripe`, `barcode`, `qr`, `other`).", "examples": [ "keyed" ] }, "auth_code": { "type": "string", "description": "Authorization code generated by the card provider when the card is successfully authorized.", "examples": [ "123456" ] }, "retrieval_reference_number": { "type": [ "string", "null" ], "description": "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. ", "examples": [ "000000603076" ] }, "card_type": { "$ref": "#/components/schemas/CardType", "description": "The type of card. A transaction response always reports `UNKNOWN`: the processor does not return the card type on the authorization, so the gateway has nothing to report yet. Read the transaction back from a reporting endpoint — `GET /v1/transactions` or `GET /v1/transactions/{id}` — for the determined value. Treat `UNKNOWN` as \"not yet known\" on a transaction response and as \"the processor could not determine it\" on a reporting response." }, "card_brand": { "type": "string", "description": "Card network brand (e.g. `Visa`, `Mastercard`, `Amex`, `Discover`).", "examples": [ "Visa" ] }, "cvv_result_code": { "description": "The result returned from a card verification value check. Null on void/refund responses where CVV is not re-checked.", "type": [ "string", "null" ], "maxLength": 1, "examples": [ "M" ] }, "avs_result_code": { "$ref": "#/components/schemas/AvsResultCode" }, "avs_response": { "type": "string", "description": "Human-readable AVS response message.", "examples": [ "Exact Match - Street address and postal code match" ] } }, "additionalProperties": false }, "CardType": { "type": "string", "enum": [ "DEBIT", "CREDIT", "UNKNOWN" ], "description": "The type of card. `UNKNOWN` is returned when the processor cannot determine the card type.", "examples": [ "DEBIT", "CREDIT", "UNKNOWN" ] }, "OpenBatchCardType": { "type": "string", "enum": [ "DEBIT", "CREDIT" ], "description": "The card types the open-batch transaction filter accepts. This is a narrower set than `CardType`, which is what a transaction response carries. Open-batch eligibility groups transactions the way batch close does, and that grouping has no separate bucket for an undetermined card type — so `UNKNOWN` cannot be selected there and `CREDIT` covers it.", "examples": [ "DEBIT", "CREDIT" ] }, "ExpiryInput": { "type": "object", "description": "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`.", "additionalProperties": false, "properties": { "month": { "type": "integer", "format": "int32", "description": "Month of the card expiration date, as a number from 1 to 12.", "minimum": 1, "maximum": 12, "examples": [ 1 ] }, "year": { "type": "integer", "format": "int32", "description": "Four-digit year of the card expiration date.", "minimum": 2020, "maximum": 2100, "examples": [ 2028 ] } }, "required": [ "month", "year" ] }, "Expiry": { "type": "object", "description": "Card expiration date returned on a response. Both fields are strings. A request uses a different shape — see `ExpiryInput`.", "additionalProperties": false, "properties": { "month": { "type": "string", "description": "Month of the card expiration date as a two-digit number", "minLength": 2, "maxLength": 2, "pattern": "^(0[1-9]|1[0-2])$", "examples": [ "01" ] }, "year": { "type": "string", "description": "Year of the card expiration date as a four-digit number.", "minLength": 4, "maxLength": 4, "pattern": "^\\d{4}$", "examples": [ "2028" ] } }, "required": [ "month", "year" ] }, "Email": { "type": "string", "description": "Email address.", "format": "email", "examples": [ "james.t.kirk@example.com" ], "writeOnly": true }, "EntryMethod": { "type": [ "string", "null" ], "enum": [ "MOTO", "ECOMMERCE", null ], "default": "ECOMMERCE", "x-enumDescriptions": { "MOTO": "A Card Not Present entry method where the payment method information was obtained over the phone or via postal mail.", "ECOMMERCE": "A Card Not Present entry method where the payment method information was obtained over the Internet via a web browser." }, "description": "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.\nOptional. Defaults to `ECOMMERCE` when omitted or sent as `null`.", "examples": [ "ECOMMERCE" ] }, "PaymentMethodInput": { "description": "Schema for payment methods supplied on a transaction create request. Concrete subtypes are discriminated by the `type` property.", "oneOf": [ { "$ref": "#/components/schemas/BankAccountInput", "title": "ACH" }, { "$ref": "#/components/schemas/CardInput", "title": "Card" }, { "$ref": "#/components/schemas/PaymentTokenInput", "title": "Token" } ], "discriminator": { "propertyName": "type", "mapping": { "ACH": "#/components/schemas/BankAccountInput", "Card": "#/components/schemas/CardInput", "Token": "#/components/schemas/PaymentTokenInput" } } }, "PaymentMethodOutput": { "description": "Base schema for payment methods returned on a transaction response. Concrete subtypes are discriminated by the `type` property.\n\nA 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.", "oneOf": [ { "$ref": "#/components/schemas/CardOutput", "title": "CARD" }, { "$ref": "#/components/schemas/BankAccountOutput", "title": "ACH" } ], "discriminator": { "propertyName": "type", "mapping": { "ACH": "#/components/schemas/BankAccountOutput", "CARD": "#/components/schemas/CardOutput" } } }, "PaymentToken": { "description": "Reference to a previously stored (tokenized) payment method. Null when tokenization was not performed or failed.", "type": [ "string", "null" ], "examples": [ "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB" ] }, "PaymentTokenInput": { "description": "Reference to a previously stored (tokenized) payment method supplied on a request.", "type": "object", "required": [ "type", "payment_token" ], "properties": { "type": { "$ref": "#/components/schemas/PaymentMethodTypeInput", "const": "Token", "description": "The type of payment method.", "examples": [ "Token" ] }, "payment_token": { "$ref": "#/components/schemas/PaymentToken" } }, "additionalProperties": false }, "BatchStatusDto": { "type": "object", "description": "Summary status for a single batch.", "properties": { "batch_id": { "type": [ "string", "null" ], "description": "Unique identifier of the batch.", "examples": [ "BATCH-01KEW32V6YNV11T33XGDR7TGWC" ] }, "status": { "type": [ "string", "null" ], "description": "Current processing status of the batch.", "examples": [ "in_progress" ] } }, "additionalProperties": false }, "BatchStatusResponse": { "type": "object", "description": "Response containing the current status of batches for a client.", "properties": { "has_in_progress": { "type": [ "boolean", "null" ], "description": "Whether the client has any batches currently being processed.", "examples": [ true ] }, "in_progress_batches": { "type": [ "array", "null" ], "description": "List of batches currently in progress.", "items": { "$ref": "#/components/schemas/BatchStatusDto" } }, "completed_batches": { "type": [ "array", "null" ], "description": "List of batches that have completed processing.", "items": { "$ref": "#/components/schemas/BatchStatusDto" } }, "max_closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of the most recently closed batch.", "examples": [ "2026-07-15T23:00:12Z" ] }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "BatchType": { "type": "string", "description": "The type of batch.", "enum": [ "Credit", "Debit" ], "x-enumDescriptions": { "Credit": "Credit batch — contains credit/sale transactions.", "Debit": "Debit batch — contains debit transactions." }, "examples": [ "Credit", "Debit" ] }, "Phone": { "type": "string", "description": "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.", "format": "tel", "pattern": "^(\\+\\d{1,2})?[\\s.-]?\\(?\\d{3}\\)?[\\s.-]?\\d{3}[\\s.-]?\\d{4}$", "examples": [ "+18005551234", "+1-800-555-1234", "800.555.1245", "800 555 1234" ] }, "PhoneNullable": { "oneOf": [ { "$ref": "#/components/schemas/Phone" }, { "type": "null" } ], "description": "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.", "examples": [ "+17035550123", null ] }, "TransactionCreateRequest": { "required": [ "amount", "payment_method", "type" ], "type": "object", "description": "Request body for creating a new payment transaction.", "properties": { "type": { "$ref": "#/components/schemas/TransactionCreateType", "examples": [ "SALE" ] }, "amount": { "$ref": "#/components/schemas/Amount" }, "tip": { "$ref": "#/components/schemas/Tip" }, "currency": { "type": "string", "description": "Three-letter ISO 4217 currency code. Optional; defaults to `USD`, which is the only value the gateway accepts.", "const": "USD", "default": "USD", "examples": [ "USD" ] }, "payment_method": { "$ref": "#/components/schemas/PaymentMethodInput" }, "initiator": { "$ref": "#/components/schemas/Initiator", "description": "The initiator of the transaction." }, "recurring": { "type": "boolean", "default": false, "description": "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.", "examples": [ true ] }, "recurring_details": { "$ref": "#/components/schemas/RecurringDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": false }, "TransactionCaptureRequest": { "required": [ "amount" ], "type": "object", "description": "Request body for capturing a previously authorized transaction.", "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "tip": { "$ref": "#/components/schemas/Tip" } } }, "TransactionCreateType": { "type": "string", "description": "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`.\n\nWhich 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" ], "x-enumDescriptions": { "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." }, "examples": [ "SALE" ] }, "TransactionType": { "type": "string", "description": "The type of transaction.", "enum": [ "SALE", "AUTH", "PAYOUT", "REFUND", "VOID", "CAPTURE" ], "x-enumDescriptions": { "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 for payment card authorization that is not automatically captured. Transaction is completed by manual capture of authorized funds.", "PAYOUT": "An ACH credit. Funds tranferred from merchant to customer.", "REFUND": "Refunds a settled payment. Funds tranferred from merchant to customer.", "VOID": "Cancels a `SALE` or captured `AUTH` before settlement.", "CAPTURE": "Manually captures an authorized payment." }, "examples": [ "SALE" ] }, "TransactionResponseType": { "type": "string", "description": "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" ], "x-enumDescriptions": { "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." }, "examples": [ "SALE" ] }, "PaymentMethodTypeInput": { "type": "string", "description": "The type of payment method supplied on a request. A response returns a different set of values — see `PaymentMethodTypeOutput`.", "enum": [ "ACH", "Card", "Token" ], "x-enumDescriptions": { "ACH": "A bank account debited or credited over ACH.", "Card": "A credit or debit card.", "Token": "A stored payment method, referenced by its token." }, "examples": [ "ACH", "Card", "Token" ] }, "PaymentMethodTypeOutput": { "type": "string", "description": "The type of payment method returned on a response. A request supplies a different set of values — see `PaymentMethodTypeInput`.\n\nA 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" ], "x-enumDescriptions": { "ACH": "A bank account debited or credited over ACH.", "CARD": "A credit or debit card." }, "examples": [ "ACH", "CARD" ] }, "RecurringDetails": { "type": "object", "description": "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.", "required": [ "sequence" ], "properties": { "sequence": { "$ref": "#/components/schemas/RecurringSequence" }, "initial_transaction_id": { "type": [ "string", "null" ], "description": "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.", "examples": [ "TRANSACTION-01KEW32V6YNV11T336VEDKL123" ] }, "initial_network_transaction_id": { "type": [ "string", "null" ], "description": "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.", "examples": [ "MCC1234567890" ] } }, "additionalProperties": false }, "RecurringSequence": { "type": "string", "description": "The position of this transaction within a recurring payment agreement.", "enum": [ "INITIAL", "SUBSEQUENT" ], "x-enumDescriptions": { "INITIAL": "The first, customer-initiated (CIT) transaction in the agreement. Establishes the stored credential.", "SUBSEQUENT": "A follow-on transaction billed against the agreement established by the INITIAL transaction. Usually merchant-initiated (MIT)." }, "examples": [ "INITIAL" ] }, "TransactionRefundRequest": { "required": [ "type", "amount" ], "type": "object", "description": "Request body for refunding a settled transaction.", "properties": { "type": { "$ref": "#/components/schemas/TransactionType", "const": "REFUND", "description": "Discriminates this request from a void. `TransactionRequestConverter` handles only `VOID` and `REFUND` on this operation.", "examples": [ "REFUND" ] }, "amount": { "$ref": "#/components/schemas/Amount", "description": "Refund amount in cents (e.g. `10000` = $100.00). Amount must be less than or equal to the transaction amount. \n\nMaximum 99,999,999 cents ($999,999.99). All transactions are in US dollars (USD).", "examples": [ 2500 ] } }, "additionalProperties": false }, "Result": { "type": "string", "enum": [ "APPROVED", "DECLINED", "ERROR" ], "x-enumDescriptions": { "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." }, "examples": [ "APPROVED" ] }, "SettlementIssue": { "type": [ "string", "null" ], "description": "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 ], "x-enumDescriptions": { "REMOVED_FROM_BATCH": "The transaction was removed from its batch before settlement." }, "examples": [ "REMOVED_FROM_BATCH" ] }, "Tip": { "type": "integer", "format": "int32", "description": "Tip amount in cents (e.g. `1000` = $10.00). If no tip is included, use `0` or omit the field.\n\n`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.\n\nMinimum 0 cents ($0.00). Maximum 99,999,999 cents ($999,999.99). All transactions are in US dollars (USD).", "minimum": 0, "maximum": 99999999, "examples": [ 0, 1000 ] }, "TimeCreated": { "type": "string", "format": "date-time", "description": "the API server generated time indicating when the object was created. In ISO-8601 format (YYYY-MM-DDTHH:MM:SS.SSSZ).", "examples": [ "2026-01-15T14:30:00Z" ] }, "TransactionResponse": { "type": "object", "description": "Response returned after processing a payment transaction.\n\nThe transaction endpoints and the reporting endpoints return this same object, and a transaction response is the earlier of the two. Some values are not known when the gateway answers the original request — they arrive from the processor seconds, minutes, or hours later. A field in that position carries a placeholder on the transaction response and its settled value on any reporting read of the same transaction, so read the field's own description before treating the first response as final. `payment_method.card_type` is the current example.", "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction assigned by the API server.", "examples": [ "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC" ] }, "reference_transaction_id": { "type": [ "string", "null" ], "description": "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.", "examples": [ "TRANSACTION-01KEW32V6YNV11T336VEDKL123" ] }, "type": { "$ref": "#/components/schemas/TransactionResponseType", "examples": [ "SALE" ] }, "result": { "$ref": "#/components/schemas/Result" }, "client_id": { "type": "string", "description": "The `client_id` of the client account that requested this transaction.", "examples": [ "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y" ] }, "client_dba": { "type": "string", "description": "Doing Business As (DBA) name of the client account.", "examples": [ "Acme Jewelry" ] }, "integrations": { "$ref": "#/components/schemas/Integrations" }, "response_code": { "type": "string", "description": "Response code generated by the payment processor. ", "examples": [ "00" ] }, "response_description": { "type": "string", "description": "Human-readable description of the transaction outcome.", "examples": [ "Approved" ] }, "batch_id": { "type": [ "string", "null" ], "description": "Unique identifier of the batch containing this transaction. Null when the transaction has not yet been assigned to a batch.", "examples": [ "BATCH-01KEW32V6YNV11T33XGDR7TGWC" ] }, "is_settled": { "type": "boolean", "description": "Whether the transaction is settled.", "examples": [ false ] }, "settlement_issue": { "$ref": "#/components/schemas/SettlementIssue" }, "is_returned": { "type": "boolean", "description": "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.", "examples": [ false ] }, "returned_at": { "type": [ "string", "null" ], "format": "date-time", "description": "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.", "examples": [ "2026-09-02T15:38:07.8304618Z" ] }, "return_code": { "type": [ "string", "null" ], "description": "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.", "examples": [ "R03" ] }, "return_reason": { "type": [ "string", "null" ], "description": "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.", "examples": [ "NO ACCOUNT/ UNABLE TO LOCATE ACCOUNT" ] }, "time_created": { "$ref": "#/components/schemas/TimeCreated" }, "amount": { "$ref": "#/components/schemas/Amount" }, "tip": { "$ref": "#/components/schemas/Tip" }, "currency": { "type": "string", "description": "Three-letter ISO 4217 currency code for the transaction.", "const": "USD", "examples": [ "USD" ] }, "payment_method": { "$ref": "#/components/schemas/PaymentMethodOutput" }, "recurring": { "type": "boolean", "description": "Whether the transaction is part of a recurring payment agreement.", "examples": [ false ] }, "initiator": { "oneOf": [ { "$ref": "#/components/schemas/Initiator" }, { "type": "null" } ], "description": "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": { "oneOf": [ { "$ref": "#/components/schemas/RecurringDetails" }, { "type": "null" } ], "description": "Stored-credential details for the recurring agreement this transaction belongs to. Null on a one-off transaction." }, "network_transaction_id": { "type": [ "string", "null" ], "description": "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.", "examples": [ "MCC1234567890" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": false }, "TransactionCancelRequest": { "required": [ "type" ], "type": "object", "description": "Request body for canceling (voiding) an authorized but unsettled transaction.", "properties": { "type": { "$ref": "#/components/schemas/TransactionType", "const": "VOID", "description": "Discriminates this request from a refund. `TransactionRequestConverter` handles only `VOID` and `REFUND` on this operation.", "examples": [ "VOID" ] } }, "additionalProperties": false }, "TransactionsListResponse": { "type": "object", "description": "Paginated list of transactions.", "properties": { "total_count": { "type": "integer", "format": "int32", "description": "Total number of transactions matching the query.", "examples": [ 42 ] }, "limit": { "type": "integer", "format": "int32", "description": "Maximum number of records returned in this response.", "examples": [ 100 ] }, "offset": { "type": "integer", "format": "int32", "description": "Number of records skipped.", "examples": [ 20 ] }, "has_more": { "type": "boolean", "description": "Whether additional records exist beyond this result set. If `true`, increment `offset` by `limit` to fetch the next page.", "examples": [ true ] }, "transactions": { "type": "array", "description": "Array of transaction objects matching the query.", "items": { "$ref": "#/components/schemas/TransactionResponse" } } }, "additionalProperties": false }, "ClientAdminContactDetails": { "required": [ "first_name", "last_name", "email", "time_zone" ], "type": "object", "description": "Contact information for the primary admin user of a client account, as returned on a response. The four required properties are always present and may be null, because a client created through an internal path is not held to the rules `ClientAdminContactDetailsInput` applies. A request uses `ClientAdminContactDetailsInput` to create and `ClientAdminContactDetailsUpdate` to amend.", "properties": { "first_name": { "type": [ "string", "null" ], "description": "First name of the admin contact.", "examples": [ "John" ] }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the admin contact.", "examples": [ "Doe" ] }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email address of the admin contact. Used as the login username.", "examples": [ "john.doe@example.com" ] }, "phone": { "$ref": "#/components/schemas/PhoneNullable" }, "time_zone": { "$ref": "#/components/schemas/TimeZone" } }, "additionalProperties": false }, "ClientAdminContactDetailsInput": { "required": [ "first_name", "last_name", "email", "time_zone" ], "type": "object", "description": "Contact information for the primary admin user, supplied when creating a client. The four required properties must each carry a value — null is rejected, and so is an empty string.", "properties": { "first_name": { "type": "string", "minLength": 1, "description": "First name of the admin contact.", "examples": [ "John" ] }, "last_name": { "type": "string", "minLength": 1, "description": "Last name of the admin contact.", "examples": [ "Doe" ] }, "email": { "type": "string", "minLength": 1, "format": "email", "description": "Email address of the admin contact. Used as the login username.", "examples": [ "john.doe@example.com" ] }, "phone": { "$ref": "#/components/schemas/PhoneNullable" }, "time_zone": { "$ref": "#/components/schemas/TimeZone" } }, "additionalProperties": false }, "ClientAdminContactDetailsUpdate": { "type": "object", "description": "Contact information supplied when updating a client. Every property is optional; send only the ones you are changing. Omitting a property leaves it as it was.", "properties": { "first_name": { "type": "string", "description": "First name of the admin contact.", "examples": [ "John" ] }, "last_name": { "type": "string", "description": "Last name of the admin contact.", "examples": [ "Doe" ] }, "email": { "type": "string", "format": "email", "description": "Email address of the admin contact. Used as the login username.", "examples": [ "john.doe@example.com" ] }, "phone": { "$ref": "#/components/schemas/PhoneNullable" }, "time_zone": { "$ref": "#/components/schemas/TimeZone" } }, "additionalProperties": false }, "ClientDTO": { "required": [ "active", "id" ], "type": "object", "description": "Summary representation of a client account.", "properties": { "id": { "type": "string", "description": "Unique identifier for the client assigned by the API server.", "examples": [ "CLIENT-3MTWBWLKDIWHU7IX28A3TQPA" ] }, "dba": { "type": [ "string", "null" ], "description": "Doing Business As (DBA) name of the client.", "examples": [ "Acme Jewelry" ] }, "first_name": { "type": [ "string", "null" ], "description": "First name of the primary admin contact.", "examples": [ "John" ] }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the primary admin contact.", "examples": [ "Doe" ] }, "email_address": { "type": [ "string", "null" ], "format": "email", "description": "Email address of the primary admin contact.", "examples": [ "john.doe@example.com" ] }, "phone_number": { "$ref": "#/components/schemas/PhoneNullable" }, "parent_id": { "type": [ "string", "null" ], "description": "Unique identifier of the parent client account.", "examples": [ "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y" ] }, "active": { "type": "boolean", "description": "Whether the client account is active.", "examples": [ true ] }, "date_added": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the client account was created.", "examples": [ "2026-02-11T09:24:17Z" ] }, "metadata": { "type": [ "object", "null" ], "description": "Arbitrary key-value metadata attached to the client account.", "examples": [ { "crm_account_id": "CRM-88213", "onboarding_rep": "jsmith" } ] } }, "additionalProperties": false }, "ClientDetailsDTO": { "required": [ "active", "dba", "id" ], "type": "object", "description": "Detailed representation of a client account including audit metadata.", "properties": { "id": { "type": "string", "description": "Unique identifier for the client assigned by the API server.", "examples": [ "CLIENT-3MTWBWLKDIWHU7IX28A3TQPA" ] }, "dba": { "type": "string", "description": "Doing Business As (DBA) name of the client.", "examples": [ "Acme Jewelry" ] }, "user_id": { "type": [ "string", "null" ], "description": "Identifier of the admin user associated with this client.", "examples": [ "USER-3MTWBWLKDIWHU7IX28A3TQPA" ] }, "parent_id": { "type": [ "string", "null" ], "description": "Unique identifier of the parent client account.", "examples": [ "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y" ] }, "effective": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the client account became effective.", "examples": [ "2026-02-11T00:00:00Z" ] }, "expiry": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the client account expires. Null if no expiry.", "examples": [ null ] }, "active": { "type": "boolean", "description": "Whether the client account is active.", "examples": [ true ] }, "modified": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of the last modification to this record.", "examples": [ "2026-06-30T14:02:51Z" ] }, "modified_by": { "type": [ "integer", "null" ], "format": "int32", "description": "Internal ID of the user who last modified this record.", "examples": [ 1042 ] }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": false }, "ClientType": { "type": "string", "description": "The type of client account.", "enum": [ "reseller", "merchant" ], "x-enumDescriptions": { "reseller": "Reseller — a client that resells services to merchants.", "merchant": "Merchant — a client that processes payments." }, "examples": [ "reseller", "merchant" ] }, "CorrelationId": { "type": "string", "description": "Identifier the gateway assigns to the request and carries across the services that handled it. Quote it when reporting a problem.", "examples": [ "01KFDKXMQ637EKEAY410MSQSXB" ] }, "CreateClientRequest": { "required": [ "admin_contact_details", "dba", "parent_id", "type" ], "type": "object", "description": "Request body for creating a new client account.", "properties": { "parent_id": { "minLength": 1, "type": "string", "description": "Unique identifier of the parent client account (reseller or ISO).", "examples": [ "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y" ] }, "type": { "$ref": "#/components/schemas/ClientType" }, "dba": { "minLength": 1, "type": "string", "description": "Doing Business As (DBA) name for the new client.", "examples": [ "Acme Jewelry" ] }, "address": { "type": "array", "description": "One or more client addresses. Each address carries a `type` identifying its purpose (legal, billing, or physical).", "items": { "$ref": "#/components/schemas/ClientAddress" } }, "primary_phone": { "$ref": "#/components/schemas/PhoneNullable", "description": "Client primary phone number", "examples": [ "+18006555667" ] }, "support_phone": { "$ref": "#/components/schemas/PhoneNullable", "description": "Client support or customer service phone number. If left blank, this number will default to `primary_phone`.", "examples": [ "+18005255656" ] }, "website": { "type": "string", "format": "url", "description": "URL of client website", "examples": [ "https://www.acme.com" ] }, "admin_contact_details": { "$ref": "#/components/schemas/ClientAdminContactDetailsInput" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": false }, "CreateClientResponse": { "required": [ "admin_contact_details", "api_key", "dba", "id", "parent_id", "type" ], "type": "object", "description": "Response returned after successfully creating a new client account.", "properties": { "id": { "minLength": 1, "type": "string", "description": "Unique identifier for the newly created client assigned by the API server.", "examples": [ "CLIENT-3MTWBWLKDIWHU7IX28A3TQPA" ] }, "parent_id": { "minLength": 1, "type": "string", "description": "Unique identifier of the parent client account.", "examples": [ "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y" ] }, "type": { "$ref": "#/components/schemas/ClientType" }, "dba": { "minLength": 1, "type": "string", "description": "Doing Business As (DBA) name of the newly created client.", "examples": [ "Acme Jewelry" ] }, "address": { "type": "array", "description": "One or more client addresses. Each address carries a `type` identifying its purpose (legal, billing, or physical).", "items": { "$ref": "#/components/schemas/ClientAddress" } }, "primary_phone": { "$ref": "#/components/schemas/PhoneNullable", "description": "Client primary phone number", "examples": [ "+18006555667" ] }, "support_phone": { "$ref": "#/components/schemas/PhoneNullable", "description": "Client support or customer service phone number. If left blank, this number will default to `primary_phone`.", "examples": [ "+18005255656" ] }, "website": { "type": [ "string", "null" ], "format": "url", "description": "URL of client website. Null when the client was created without one — the gateway returns the field rather than omitting it.", "examples": [ "https://www.acme.com" ] }, "admin_contact_details": { "$ref": "#/components/schemas/ClientAdminContactDetails" }, "api_key": { "minLength": 1, "type": "string", "description": "API key issued for the new client. Returned once, on this response only — store it, because no later call returns it again.", "examples": [ "pk_live_01KFDKXMQ637EKEAY410MSQSXB" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "GetAllClientsResponse": { "required": [ "all_clients" ], "type": "object", "description": "Response containing a list of all client accounts accessible to the caller.", "properties": { "all_clients": { "type": "array", "description": "List of client account summaries.", "items": { "$ref": "#/components/schemas/ClientDTO" } }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "GetClientResponse": { "required": [ "client_details" ], "type": "object", "description": "Response containing details for a specific client account.", "properties": { "client_details": { "$ref": "#/components/schemas/ClientDetailsDTO" }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "Integrations": { "type": "array", "description": "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": { "$ref": "#/components/schemas/IntegrationsEnum" }, "examples": [ [ "TSYS" ] ] }, "IntegrationsEnum": { "type": "string", "enum": [ "TSYS", "VERICHECK" ], "x-enumDescriptions": { "TSYS": "The TSYS card processor. Returned on card transactions.", "VERICHECK": "The Vericheck ACH processor. Returned on bank account (ACH) transactions." }, "examples": [ "TSYS" ] }, "Initiator": { "type": "string", "description": "Who initiated the transaction, per the card-network stored-credential framework. `CUSTOMER` = customer-initiated (CIT); `MERCHANT` = merchant-initiated (MIT).", "enum": [ "MERCHANT", "CUSTOMER", "THIRD_PARTY" ], "x-enumDescriptions": { "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." }, "examples": [ "CUSTOMER" ] }, "IntegrationCreateRequest": { "required": [ "integration_details", "is_active", "processor" ], "type": "object", "description": "Request body for creating a new processor integration for a client.", "properties": { "client": { "type": [ "string", "null" ], "description": "The client ID to associate with this integration. Defaults to the caller's client if omitted.", "examples": [ "CLIENT-01KFDKXMQ637EKEAY410MSQSXB" ] }, "is_active": { "type": "boolean", "description": "Whether the integration should be active immediately upon creation.", "default": false, "examples": [ true ] }, "processor": { "$ref": "#/components/schemas/Processor" }, "integration_details": { "$ref": "#/components/schemas/IntegrationDetailRequest" } }, "additionalProperties": false }, "IntegrationDetailRequest": { "oneOf": [ { "$ref": "#/components/schemas/TSYSHostDetailsRequest", "title": "TSYS" }, { "$ref": "#/components/schemas/VericheckOnboardingRequest", "title": "Vericheck" } ] }, "IntegrationDetailResponse": { "type": "object", "description": "Processor-specific integration details returned in responses. Shape varies by processor.", "oneOf": [ { "$ref": "#/components/schemas/TSYSHostDetailsResponse" }, { "$ref": "#/components/schemas/VericheckOnboardingResponse" } ], "properties": { "created_by": { "type": [ "integer", "null" ], "format": "int32", "description": "Internal ID of the user who created this integration.", "examples": [ 1042 ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the integration was created.", "examples": [ "2026-02-11T09:24:17Z" ] }, "modified_by": { "type": [ "integer", "null" ], "format": "int32", "description": "Internal ID of the user who last modified this integration.", "examples": [ 1042 ] }, "modified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of the last modification to this integration.", "examples": [ "2026-06-30T14:02:51Z" ] } } }, "IntegrationGetResponse": { "required": [ "integration_details", "is_active", "processor" ], "type": "object", "description": "Response containing details for a specific processor integration.", "properties": { "id": { "type": [ "string", "null" ], "description": "Unique identifier for this integration configuration.", "examples": [ "INTEGRATION-01KFDKXMQ637EKEAY410MSQSXB" ] }, "is_active": { "type": "boolean", "description": "Whether the integration is currently active.", "examples": [ true ] }, "client": { "type": [ "string", "null" ], "description": "The client ID associated with this integration.", "examples": [ "CLIENT-01KFDKXMQ637EKEAY410MSQSXB" ] }, "processor": { "$ref": "#/components/schemas/Processor" }, "integration_details": { "$ref": "#/components/schemas/IntegrationDetailResponse" }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "IntegrationSummary": { "required": [ "is_active", "processor" ], "type": "object", "description": "Summary of a processor integration returned in list responses.", "properties": { "id": { "type": [ "string", "null" ], "description": "Unique identifier for this integration configuration.", "examples": [ "INTEGRATION-01KFDKXMQ637EKEAY410MSQSXB" ] }, "processor": { "$ref": "#/components/schemas/Processor" }, "is_active": { "type": "boolean", "description": "Whether the integration is currently active.", "examples": [ true ] } }, "additionalProperties": false }, "IntegrationSummaryResponse": { "required": [ "integrations" ], "type": "object", "description": "Response containing a list of processor integrations.", "properties": { "integrations": { "type": "array", "description": "The integrations the client account has onboarded with.", "items": { "$ref": "#/components/schemas/IntegrationSummary" } }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "IntegrationUpdateRequest": { "required": [ "integration_details", "is_active", "processor" ], "type": "object", "description": "Request body for updating an existing processor integration.", "properties": { "is_active": { "type": "boolean", "description": "Whether the integration should be active after this update.", "examples": [ false ] }, "processor": { "$ref": "#/components/schemas/Processor" }, "integration_details": { "$ref": "#/components/schemas/IntegrationDetailRequest" } }, "additionalProperties": false }, "Metadata": { "type": [ "object", "null" ], "description": "Key-value pairs for storing additional information on the transaction. Send `null` to clear all metadata.\n\nAt 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.", "maxProperties": 50, "propertyNames": { "pattern": "^[a-zA-Z0-9_-]+$", "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 }, "examples": [ { "order_id": "ORD-10432", "sales_channel": "web", "customer_reference": "cust-8891" } ] }, "UpdateClientsRequest": { "type": "object", "description": "Request body for updating an existing client account. All fields are optional; omit to leave unchanged.", "properties": { "dba": { "type": [ "string", "null" ], "description": "Updated Doing Business As (DBA) name for the client.", "examples": [ "Acme Jewelry & Watches" ] }, "type": { "$ref": "#/components/schemas/ClientType" }, "admin_contact_details": { "$ref": "#/components/schemas/ClientAdminContactDetailsUpdate" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": false }, "Processor": { "type": "string", "description": "The payment processor or service provider for the integration. Send the value exactly as spelled here. On the integration operations the gateway parses this field case-sensitively, so `TSYS` is rejected.", "enum": [ "Tsys", "Vericheck" ], "x-enumDescriptions": { "Tsys": "TSYS payment processor", "Vericheck": "Vericheck ACH processor" }, "examples": [ "Tsys" ] }, "SortOrder": { "type": "string", "description": "The sort order for list results.", "enum": [ "ASC", "DESC" ], "x-enumDescriptions": { "ASC": "Ascending order (oldest first).", "DESC": "Descending order (newest first)." }, "examples": [ "DESC" ] }, "StandardEntryClass": { "type": "string", "description": "ACH Standard Entry Class (SEC) code that defines the transaction type and authorization method.", "enum": [ "PPD", "CCD", "WEB", "TEL", "POP", "BOC" ], "x-enumDescriptions": { "PPD": "Prearranged Payment and Deposit — consumer account transactions authorized in writing.", "CCD": "Corporate Credit or Debit — business-to-business ACH transactions.", "WEB": "Internet-initiated entries — consumer transactions authorized via the internet.", "TEL": "Telephone-initiated entries — consumer transactions authorized by phone.", "POP": "Point-of-Purchase — check conversion transactions at the point of sale.", "BOC": "Back Office Conversion — check conversion after the sale." }, "examples": [ "PPD", "CCD" ] }, "TimeZone": { "type": "string", "description": "The time zone of the account.", "enum": [ "America/Los_Angeles", "America/Phoenix", "America/Denver", "America/Chicago", "America/New_York", "Pacific/Honolulu", "America/Anchorage" ], "x-enumDescriptions": { "America/Los_Angeles": "Pacific Time Zone", "America/Phoenix": "Mountain Standard Time (MST, no DST)", "America/Denver": "Mountain Time Zone", "America/Chicago": "Central Time Zone", "America/New_York": "Eastern Time Zone", "Pacific/Honolulu": "Hawaii-Aleutian Standard Time (HAST)", "America/Anchorage": "Alaska Time Zone" }, "examples": [ "America/New_York", "America/Los_Angeles" ] }, "TSYSHostDetailsRequest": { "required": [ "address1", "agent_bank_number", "agent_chain_number", "amex_number", "amex_opt_blue", "association", "bank_number", "bin", "descriptor_city", "descriptor_postal", "descriptor_state", "discover_number", "industry", "mcc", "merchant_aba_number", "merchant_area_code", "merchant_settlement_agent_number", "mid", "mvv", "name", "phone_number", "reimbursement_attribute", "settlement_time", "sharing_group", "store_number", "terminal_id", "terminal_number", "url", "v_number" ], "type": "object", "description": "TSYS processor-specific configuration details for creating a merchant integration.", "properties": { "name": { "type": "string", "maxLength": 25, "description": "Client legal name as registered with TSYS.", "examples": [ "Acme Jewelry LLC" ] }, "dba": { "type": [ "string", "null" ], "description": "Doing Business As (DBA) name, if different from legal name.", "examples": [ "Acme Jewelry" ] }, "url": { "type": "string", "description": "URL of processor server.", "examples": [ "https://example.apiserver.com" ] }, "phone_number": { "type": "integer", "format": "int64", "description": "Merchant contact phone number, as digits only. `TsysHostDetailsRequest` binds this as a 64-bit integer, so punctuation and a leading `+` are not accepted.", "examples": [ 17035550123 ] }, "fax_number": { "$ref": "#/components/schemas/PhoneNullable", "examples": [ "+17035550199" ] }, "mid": { "type": "string", "description": "Merchant ID (MID) assigned by the payment processor.", "examples": [ "888000001234" ] }, "amex_number": { "type": "string", "description": "American Express identification number for the merchant.", "examples": [ "1234567890" ] }, "association": { "type": "string", "description": "Association or network identifier for the merchant.", "examples": [ "VISA" ] }, "bin": { "type": "string", "description": "Bank Identification Number (BIN) for the acquiring bank.", "examples": [ "431940" ] }, "discover_number": { "type": "string", "description": "Discover network identifier for the merchant.", "examples": [ "601100999999" ] }, "mcc": { "type": "string", "description": "Merchant Category Code (MCC) — four-digit ISO 18245 code classifying the business type.", "examples": [ "5944" ] }, "bank_number": { "type": "string", "maxLength": 4, "description": "Acquiring bank number assigned by TSYS.", "examples": [ "1234" ] }, "industry": { "description": "Industry type identifier for the merchant (processor-specific).", "enum": [ "0", "A", "B", "D", "H", "L", "O", "P", "R" ], "x-enumDescriptions": { "0": "Industry type not specified.", "A": "Auto rental", "B": "Bank/Financial Institution", "D": "Direct Marketing", "H": "Hotel", "L": "Limited Amount Terminal", "O": "Oil Company/Automated Fueling System", "P": "Passenger Transport", "R": "Retail/Restaurant/Grocery" }, "type": "string", "examples": [ "0", "A", "B", "D", "H", "L", "O", "P", "R" ], "default": "R" }, "amex_opt_blue": { "type": "boolean", "description": "Whether the merchant participates in the American Express OptBlue program.", "examples": [ true ] }, "agent_chain": { "type": [ "string", "null" ], "description": "Agent chain identifier associated with the merchant account.", "examples": [ "012345" ] }, "store_number": { "type": "string", "description": "Store number for the merchant location, if applicable.", "examples": [ "0001" ] }, "mvv": { "type": "string", "description": "Merchant Verification Value — unique identifier for the merchant's POS system.", "examples": [ "123456" ] }, "terminal_number": { "type": "string", "description": "Terminal number associated with the merchant account.", "examples": [ "0001" ] }, "agent_bank_number": { "type": "string", "description": "Agent bank number assigned by TSYS.", "examples": [ "123456" ] }, "agent_chain_number": { "type": "string", "description": "Agent chain number assigned by TSYS.", "examples": [ "654321" ] }, "descriptor_postal": { "type": "string", "maxLength": 10, "description": "ZIP code shown on the cardholder's billing statement descriptor.", "examples": [ "22150" ] }, "descriptor_city": { "type": "string", "maxLength": 32, "description": "City shown on the cardholder's billing statement descriptor.", "examples": [ "Springfield" ] }, "descriptor_state": { "type": "string", "maxLength": 2, "description": "State shown on the cardholder's billing statement descriptor.", "examples": [ "VA" ] }, "descriptor_country": { "type": [ "string", "null" ], "maxLength": 3, "description": "Country shown on the cardholder's billing statement descriptor.", "examples": [ "US" ] }, "descriptor_phone": { "type": [ "integer", "null" ], "format": "int64", "description": "Phone number shown on the cardholder's billing statement descriptor, as digits only. `TsysHostDetailsRequest` binds this as a nullable 64-bit integer, so punctuation and a leading `+` are not accepted.", "examples": [ 17035550123 ] }, "descriptor_store_number": { "type": [ "string", "null" ], "maxLength": 4, "description": "Store number shown on the cardholder's billing statement descriptor.", "examples": [ "0001" ] }, "address1": { "type": "string", "maxLength": 32, "description": "Primary street address of the merchant.", "examples": [ "123 Main St" ] }, "address2": { "type": [ "string", "null" ], "description": "Secondary address line of the merchant.", "examples": [ "Suite 100" ] }, "descriptor_line3": { "type": [ "string", "null" ], "description": "Third line of the billing statement descriptor.", "examples": [ "ACME JEWELRY 703-555-0123" ] }, "terminal_id": { "type": "string", "maxLength": 8, "description": "Terminal ID assigned by the processor for the merchant's POS device.", "examples": [ "00000001" ] }, "v_number": { "type": "string", "maxLength": 8, "description": "Visa-assigned number for the merchant.", "examples": [ "V1234567" ] }, "settlement_time": { "type": "string", "description": "Daily batch settlement time in HH:MM format (24-hour, local to merchant).", "examples": [ "23:00" ] }, "merchant_area_code": { "type": "integer", "format": "int32", "description": "Area code of the merchant's primary phone number.", "examples": [ 703 ] }, "descriptor_area_code": { "type": [ "integer", "null" ], "format": "int32", "description": "Area code shown on the cardholder's billing statement descriptor.", "examples": [ 703 ] }, "sharing_group": { "type": "string", "maxLength": 30, "description": "Visa-assigned sharing group identifier specifying which direct debit and EBT networks the merchant's POS device can access.", "examples": [ "AEFGKMQ" ] }, "merchant_aba_number": { "type": "string", "maxLength": 9, "description": "Merchant's ABA routing number for settlement.", "examples": [ "123456789" ] }, "merchant_settlement_agent_number": { "type": "string", "maxLength": 4, "description": "Settlement agent number assigned to the merchant by TSYS.", "examples": [ "1234" ] }, "reimbursement_attribute": { "type": "string", "description": "Reimbursement attribute code for interchange qualification.", "examples": [ "0" ] }, "fcsid": { "type": [ "string", "null" ], "maxLength": 7, "description": "FCS ID — Fiserv/TSYS internal identifier for the merchant configuration.", "examples": [ "12345" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": false }, "TSYSHostDetailsResponse": { "required": [ "merchant_area_code" ], "type": "object", "description": "TSYS processor-specific configuration details returned in integration responses.", "properties": { "name": { "type": [ "string", "null" ], "description": "Merchant legal name as registered with TSYS.", "examples": [ "Acme Jewelry LLC" ] }, "dba": { "type": [ "string", "null" ], "description": "Doing Business As (DBA) name.", "examples": [ "Acme Jewelry" ] }, "url": { "type": [ "string", "null" ], "description": "Merchant website URL.", "examples": [ "https://example.apiserver.com" ] }, "phone_number": { "type": "integer", "format": "int64", "description": "Merchant contact phone number, as digits only. `TsysHostDetailsResponse` returns this as a 64-bit integer, so it carries no punctuation and no leading `+`.", "examples": [ 17035550123 ] }, "fax_number": { "type": [ "string", "null" ], "description": "Merchant fax number.", "examples": [ "+17035550199" ] }, "mid": { "type": [ "string", "null" ], "description": "Merchant ID (MID) assigned by the payment processor.", "examples": [ "888000001234" ] }, "amex_number": { "type": [ "string", "null" ], "description": "American Express identification number for the merchant.", "examples": [ "1234567890" ] }, "association": { "type": [ "string", "null" ], "description": "Association or network identifier for the merchant.", "examples": [ "VISA" ] }, "bin": { "type": [ "string", "null" ], "description": "Bank Identification Number (BIN) for the acquiring bank.", "examples": [ "431940" ] }, "discover_number": { "type": [ "string", "null" ], "description": "Discover network identifier for the merchant.", "examples": [ "601100999999" ] }, "mcc": { "type": [ "string", "null" ], "description": "Merchant Category Code (MCC) classifying the business type.", "examples": [ "5944" ] }, "bank_number": { "type": [ "string", "null" ], "description": "Acquiring bank number assigned by TSYS.", "examples": [ "1234" ] }, "industry": { "type": [ "string", "null" ], "description": "Industry type identifier for the merchant.", "examples": [ "R" ] }, "amex_opt_blue": { "type": [ "boolean", "null" ], "description": "Whether the merchant participates in the American Express OptBlue program.", "examples": [ true ] }, "agent_chain": { "type": [ "string", "null" ], "description": "Agent chain identifier associated with the merchant.", "examples": [ "012345" ] }, "store_number": { "type": [ "string", "null" ], "description": "Store number for the merchant location.", "examples": [ "0001" ] }, "mvv": { "type": [ "string", "null" ], "description": "Merchant Verification Value for the merchant's POS system.", "examples": [ "123456" ] }, "terminal_number": { "type": [ "string", "null" ], "description": "Terminal number associated with the merchant account.", "examples": [ "0001" ] }, "agent_bank_number": { "type": [ "string", "null" ], "description": "Agent bank number assigned by TSYS.", "examples": [ "123456" ] }, "agent_chain_number": { "type": [ "string", "null" ], "description": "Agent chain number assigned by TSYS.", "examples": [ "654321" ] }, "descriptor_postal": { "type": [ "string", "null" ], "description": "ZIP code on the cardholder's billing statement descriptor.", "examples": [ "22150" ] }, "descriptor_city": { "type": [ "string", "null" ], "description": "City on the cardholder's billing statement descriptor.", "examples": [ "Springfield" ] }, "descriptor_state": { "type": [ "string", "null" ], "description": "State on the cardholder's billing statement descriptor.", "examples": [ "VA" ] }, "descriptor_country": { "type": [ "string", "null" ], "description": "Country on the cardholder's billing statement descriptor.", "examples": [ "US" ] }, "descriptor_phone": { "type": [ "integer", "null" ], "format": "int64", "description": "Phone number shown on the cardholder's billing statement descriptor, as digits only. `TsysHostDetailsResponse` returns this as a nullable 64-bit integer, so it carries no punctuation and no leading `+`.", "examples": [ 17035550123 ] }, "descriptor_store_number": { "type": [ "string", "null" ], "description": "Store number on the cardholder's billing statement descriptor.", "examples": [ "0001" ] }, "address1": { "type": [ "string", "null" ], "description": "Primary street address of the merchant.", "examples": [ "123 Main St" ] }, "address2": { "type": [ "string", "null" ], "description": "Secondary address line of the merchant.", "examples": [ "Suite 100" ] }, "descriptor_line3": { "type": [ "string", "null" ], "description": "Third line of the billing statement descriptor.", "examples": [ "ACME JEWELRY 703-555-0123" ] }, "terminal_id": { "type": [ "string", "null" ], "description": "Terminal ID for the merchant's POS device.", "examples": [ "00000001" ] }, "v_number": { "type": [ "string", "null" ], "description": "Visa-assigned number for the merchant.", "examples": [ "V1234567" ] }, "settlement_time": { "type": [ "string", "null" ], "description": "Daily batch settlement time in HH:MM format.", "examples": [ "23:00" ] }, "merchant_area_code": { "type": "integer", "format": "int32", "description": "Area code of the merchant's primary phone number.", "examples": [ 703 ] }, "descriptor_area_code": { "type": [ "integer", "null" ], "format": "int32", "description": "Area code on the cardholder's billing statement descriptor.", "examples": [ 703 ] }, "sharing_group": { "type": [ "string", "null" ], "description": "Visa-assigned sharing group identifier for direct debit and EBT network access.", "examples": [ "AEFGKMQ" ] }, "merchant_aba_number": { "type": [ "string", "null" ], "description": "Merchant's ABA routing number for settlement.", "examples": [ "123456789" ] }, "merchant_settlement_agent_number": { "type": [ "string", "null" ], "description": "Settlement agent number for the merchant.", "examples": [ "1234" ] }, "reimbursement_attribute": { "type": [ "string", "null" ], "description": "Reimbursement attribute code for interchange qualification.", "examples": [ "0" ] }, "fcsid": { "type": [ "string", "null" ], "description": "FCS ID — internal identifier for the merchant configuration.", "examples": [ "12345" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "created_by": { "type": [ "integer", "null" ], "format": "integer", "description": "Internal ID of the user who created this integration.", "examples": [ 1042 ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the integration was created.", "examples": [ "2026-02-11T09:24:17Z" ] }, "modified_by": { "type": [ "integer", "null" ], "format": "integer", "description": "Internal ID of the user who last modified this integration.", "examples": [ 1042 ] }, "modified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of the last modification to this integration.", "examples": [ "2026-06-30T14:02:51Z" ] } }, "additionalProperties": false }, "UpdateClientsResponse": { "required": [ "admin_contact_details", "dba", "id", "parent_id", "type" ], "type": "object", "description": "Response returned after successfully updating a client account.", "properties": { "id": { "minLength": 1, "type": "string", "description": "Unique identifier for the client.", "examples": [ "CLIENT-3MTWBWLKDIWHU7IX28A3TQPA" ] }, "parent_id": { "minLength": 1, "type": "string", "description": "Unique identifier of the parent client account.", "examples": [ "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y" ] }, "dba": { "minLength": 1, "type": "string", "description": "Updated Doing Business As (DBA) name of the client.", "examples": [ "Acme Jewelry" ] }, "type": { "$ref": "#/components/schemas/ClientType" }, "admin_contact_details": { "$ref": "#/components/schemas/ClientAdminContactDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "correlation_id": { "$ref": "#/components/schemas/CorrelationId" } }, "additionalProperties": false }, "VericheckOnboardingRequest": { "description": "Request object for onboarding merchant to Vericheck.", "required": [ "client_id", "client_secret" ], "properties": { "client_id": { "description": "Merchant's Client Id provided by Vericheck for API authentication.", "type": "string", "maxLength": 50, "examples": [ "fe121095-6b52-4fcd-a103-be814684800a" ] }, "client_secret": { "description": "Merchant's password provided by Vericheck for API authentication.", "type": "string", "maxLength": 50, "examples": [ "ffc10d27d40241529d97af3gd021f5e7c3bb" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "VericheckOnboardingResponse": { "description": "Response object for onboarding merchant to Vericheck.", "required": [ "client_id" ], "properties": { "client_id": { "description": "Merchant's Client Id provided by Vericheck for API authentication.", "type": "string", "maxLength": 50, "examples": [ "fe121095-6b52-4fcd-a103-be814684800a" ] }, "client_secret": { "description": "Merchant's secret at Vericheck, returned masked. The real value is write-only — send it on the request and do not expect to read it back.", "type": "string", "readOnly": true, "examples": [ "******" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "BaseProblem": { "type": "object", "additionalProperties": true, "description": "Error response object.", "properties": { "error_code": { "type": "string", "description": "The Gateway generated error code." }, "error_message": { "type": "string", "description": "Human-readable explanation that is specific to this occurrence of the problem." }, "details": { "type": [ "object", "null" ], "description": "The field in the request that caused the error. May be null if not applicable.", "additionalProperties": { "type": "string" } }, "source": { "type": [ "object", "null" ], "description": "Object containing host-processor-specific error information. May be null if not applicable.", "properties": { "system": { "type": [ "string", "null" ], "description": "The host processor name.", "examples": [ "TSYS" ] }, "code": { "type": [ "string", "null" ], "description": "The host processor code.", "examples": [ "51" ] }, "message": { "type": [ "string", "null" ], "description": "The host processor message.", "examples": [ "Insufficient funds" ] } } } } }, "BadRequest": { "title": "BadRequest", "$ref": "#/components/schemas/BaseProblem" }, "Conflict": { "title": "Conflict", "$ref": "#/components/schemas/BaseProblem" }, "Unauthorized": { "title": "Unauthorized", "$ref": "#/components/schemas/BaseProblem" }, "Forbidden": { "title": "Forbidden", "$ref": "#/components/schemas/BaseProblem" }, "NotFound": { "title": "NotFound", "$ref": "#/components/schemas/BaseProblem" }, "InternalServerError": { "title": "Internal Server Error", "$ref": "#/components/schemas/BaseProblem" }, "BadGateway": { "title": "Bad Gateway", "$ref": "#/components/schemas/BaseProblem" } }, "examples": { "BadRequestExample": { "summary": "Invalid field value in the request body", "value": { "error_code": "INVALID_REQUEST_DATA", "error_message": "The API request contains invalid data.", "details": { "amount": "Invalid amount", "payment_method.pan": "Malformed PAN" }, "source": { "system": "TSYS", "code": "13", "message": "Invalid amount" } } }, "UnauthorizedExample": { "summary": "Missing or invalid API key", "value": { "error_code": "NOT_AUTHENTICATED", "error_message": "Access credentials missing or invalid.", "details": null, "source": { "system": null, "code": null, "message": null } } }, "ForbiddenExample": { "summary": "Authenticated but not authorized for this action", "value": { "error_code": "UNAUTHORIZED_ACTION", "error_message": "Requested action is unavailable or forbidden.", "details": null, "source": { "system": null, "code": null, "message": null } } }, "NotFoundExample": { "summary": "Resource ID does not exist", "value": { "error_code": "RESOURCE_NOT_FOUND", "error_message": "Resource not found.", "details": null, "source": { "system": null, "code": null, "message": null } } }, "ConflictExample": { "summary": "Duplicate or state-conflicting action", "value": { "error_code": "DUPLICATE_ACTION", "error_message": "Duplicate action requested.", "details": null, "source": { "system": "TSYS", "code": "12", "message": "Invalid transaction" } } }, "BadGatewayExample": { "summary": "The processor returned an invalid or unexpected response", "description": "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.", "value": { "error_code": "DOWNSTREAM_ERROR", "error_message": "Downstream service returned invalid or unexpected response.", "details": null, "source": { "system": "VERICHECK", "code": "502", "message": "Bad Gateway" } } }, "InternalServerErrorExample": { "summary": "Unhandled server fault or downstream processor error", "value": { "error_code": "SYSTEM_ERROR", "error_message": "Internal system error.", "details": null, "source": { "system": "TSYS", "code": "96", "message": "System malfunction" } } }, "SaleWithCardRequestExample": { "summary": "Sale with a card", "description": "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.", "x-discriminator-value": "Card", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "Card", "entry_method": "ECOMMERCE", "pan": "4012000098765439", "expiry": { "month": 1, "year": 2028 }, "cvv": "999", "first_name": "John", "last_name": "Doe", "contact": { "phone": "+17035550123", "email": "john.doe@example.com" }, "billing_address": { "line1": "123 Main St", "line2": "Suite 100", "city": "Springfield", "state": "VA", "postal_code": "22150", "country": "US" } }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10432", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "SaleWithCardResponseExample": { "summary": "Sale with a card — approved", "description": "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.", "value": { "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": { "month": "01", "year": "2028" }, "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" } } }, "TransactionGetResponseExample": { "summary": "The same sale, read back from reporting", "description": "The sale from `SaleWithCardResponseExample`, read back after the processor reported the card type. Everything else is unchanged; the one difference is `payment_method.card_type`, which was `UNKNOWN` on the transaction response and is `CREDIT` here. See `TransactionResponse` for why the two differ.", "value": { "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": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "auth_code": "123456", "retrieval_reference_number": "000000603076", "card_type": "CREDIT", "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" } } }, "SaleWithTokenRequestExample": { "summary": "Sale with a stored payment token", "description": "The same $100.00 sale, charged against a previously stored payment token instead of raw card details. No PAN, expiry, or CVV is sent.", "x-discriminator-value": "Token", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "Token", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB" }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10433", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "SaleWithTokenResponseExample": { "summary": "Sale with a stored payment token — approved", "description": "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.", "value": { "id": "TRANSACTION-01KEW33H5PQ2K8M4VNCDW7YRT9", "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:31:47Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": { "month": "01", "year": "2028" }, "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-10433", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "AuthWithCardRequestExample": { "summary": "Authorization with a card", "description": "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.", "x-discriminator-value": "Card", "value": { "type": "AUTH", "amount": 10000, "tip": 0, "payment_method": { "type": "Card", "entry_method": "ECOMMERCE", "pan": "4012000098765439", "expiry": { "month": 1, "year": 2028 }, "cvv": "999", "first_name": "John", "last_name": "Doe", "contact": { "phone": "+17035550123", "email": "john.doe@example.com" }, "billing_address": { "line1": "123 Main St", "line2": "Suite 100", "city": "Springfield", "state": "VA", "postal_code": "22150", "country": "US" } }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10434", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "AuthWithCardResponseExample": { "summary": "Authorization with a card — approved", "description": "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.", "value": { "id": "TRANSACTION-01KEW32V6YNV11T336VEDKL123", "reference_transaction_id": null, "type": "AUTH", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "00", "response_description": "Approved", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:02:11Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": { "month": "01", "year": "2028" }, "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-10434", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "AuthWithTokenRequestExample": { "summary": "Authorization with a stored payment token", "description": "A two-step authorization charged against a stored payment token. The `captureToken` example on the Capture operation captures this one.", "x-discriminator-value": "Token", "value": { "type": "AUTH", "amount": 10000, "tip": 0, "payment_method": { "type": "Token", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB" }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10435", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "AuthWithTokenResponseExample": { "summary": "Authorization with a stored payment token — approved", "description": "The approved token authorization. `batch_id` is null until the transaction is captured.", "value": { "id": "TRANSACTION-01KEW34J7RS3N9P5WQDEX8ZTB2", "reference_transaction_id": null, "type": "AUTH", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "00", "response_description": "Approved", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:14:39Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": { "month": "01", "year": "2028" }, "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-10435", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "AchSaleRequestExample": { "summary": "Sale charged to a bank account (ACH)", "description": "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.\n\n`routing_number` is exactly nine digits and `account_number` is four to twenty. `standard_entry_class` and `description` are both optional; they default to `WEB` and `ACH Transaction`. `first_name` and `last_name` are supplied because the ACH processor requires them.\n\nA bank account accepts `SALE` and `PAYOUT`. It does not accept `AUTH`.", "x-discriminator-value": "ACH", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "ACH", "account_type": "CHECKING", "routing_number": "021000021", "account_number": "123456789012", "standard_entry_class": "WEB", "first_name": "John", "last_name": "Doe", "description": "Blue jeans" }, "metadata": { "order_id": "ORD-10438", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "PayoutRequestExample": { "summary": "Payout to a bank account (ACH credit)", "description": "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.\n\nThe 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.\n\nA 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`.", "x-discriminator-value": "ACH", "value": { "type": "PAYOUT", "amount": 25000, "tip": 0, "payment_method": { "type": "ACH", "account_type": "CHECKING", "routing_number": "021000021", "account_number": "123456789012", "standard_entry_class": "CCD", "first_name": "Dana", "last_name": "Reyes", "description": "Vendor payment" }, "metadata": { "invoice_id": "INV-2291", "sales_channel": "api" } } }, "PayoutResponseExample": { "summary": "Payout to a bank account — approved", "description": "The approved payout. `payment_method.type` is `ACH` and the account identifiers are truncated, the way they are on any ACH response.\n\n`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. `batch_id` is assigned, so the payout leaves at the next batch close.", "value": { "id": "TRANSACTION-01KEW3J7NRW9T4M2QVBXK8HZD3", "reference_transaction_id": null, "type": "PAYOUT", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "VERICHECK" ], "response_code": "00", "response_description": "Approved", "batch_id": "BATCH-01KEW32V6YNV11T33XGDR7TGWC", "is_settled": false, "is_returned": false, "returned_at": null, "time_created": "2026-07-15T17:31:44Z", "amount": 25000, "tip": 0, "currency": "USD", "payment_method": { "type": "ACH", "standard_entry_class": "CCD", "account_type": "CHECKING", "route_number_truncated": "****21", "account_number_truncated": "****9012", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637ETEAY410MSQTUH", "first_name": "Dana", "last_name": "Reyes", "description": "Vendor payment" }, "metadata": { "invoice_id": "INV-2291", "sales_channel": "api" } } }, "SaleDeclinedRequestExample": { "summary": "Sale that returns a decline", "description": "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.\n\nSelecting 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`.", "x-discriminator-value": "Card", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "Card", "entry_method": "ECOMMERCE", "pan": "4012000098765439", "expiry": { "month": 1, "year": 2028 }, "cvv": "999", "first_name": "John", "last_name": "Doe", "contact": { "phone": "+17035550123", "email": "john.doe@example.com" }, "billing_address": { "line1": "123 Main St", "line2": "Suite 100", "city": "Springfield", "state": "VA", "postal_code": "22150", "country": "US" } }, "initiator": "CUSTOMER", "metadata": { "order_id": "ORD-10436", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "SaleDeclinedResponseExample": { "summary": "Sale — declined for insufficient funds", "description": "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.", "value": { "id": "TRANSACTION-01KEW36C9TQ5N1P7YRFGZ0BVW4", "reference_transaction_id": null, "type": "SALE", "result": "DECLINED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "51", "response_description": "Insufficient funds", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:47:52Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "retrieval_reference_number": "000000603077", "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": null, "metadata": { "order_id": "ORD-10436", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "SaleRecurringSubsequentRequestExample": { "summary": "Subsequent recurring payment on a stored credential", "description": "A merchant-initiated (MIT) payment billed against the stored-credential agreement that `saleWithCard` established.\n\nThree 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`.\n\n`initial_transaction_id` points at the transaction returned by `saleWithCard`. Use `initial_network_transaction_id` instead when the agreement began outside this gateway. No CVV is sent — the cardholder is not present.", "x-discriminator-value": "Card", "value": { "type": "SALE", "amount": 10000, "tip": 0, "payment_method": { "type": "Card", "entry_method": "ECOMMERCE", "pan": "4012000098765439", "expiry": { "month": 1, "year": 2028 }, "first_name": "John", "last_name": "Doe", "billing_address": { "line1": "123 Main St", "line2": "Suite 100", "city": "Springfield", "state": "VA", "postal_code": "22150", "country": "US" } }, "initiator": "MERCHANT", "recurring_details": { "sequence": "SUBSEQUENT", "initial_transaction_id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC" }, "metadata": { "order_id": "ORD-10437", "sales_channel": "recurring", "customer_reference": "cust-8891" } } }, "SaleRecurringSubsequentResponseExample": { "summary": "Subsequent recurring payment — approved", "description": "The approved recurring payment. `initiator` and `recurring_details` echo the request, and `network_transaction_id` carries the network-assigned identifier that links this payment to the agreement. The payment falls in a later batch than the initial sale.", "value": { "id": "TRANSACTION-01KEW3D4YMV8Q7T3FNJZ2XPB56", "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-01KEXA7M2QP5N8T3VDFGH1JKR9", "is_settled": false, "time_created": "2026-08-15T09:00:00Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "auth_code": "123456", "retrieval_reference_number": "000000603078", "card_type": "UNKNOWN", "card_brand": "Visa", "cvv_result_code": null, "avs_result_code": "Y", "avs_response": "Exact Match - Street address and postal code match" }, "initiator": "MERCHANT", "recurring_details": { "sequence": "SUBSEQUENT", "initial_transaction_id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC" }, "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10437", "sales_channel": "recurring", "customer_reference": "cust-8891" } } }, "CaptureCardRequestExample": { "summary": "Capture a card authorization", "description": "Captures the full $100.00 authorized by `authWithCard`. Send this to the transaction ID returned by that authorization.", "value": { "amount": 10000, "tip": 0 } }, "CaptureCardResponseExample": { "summary": "Capture a card authorization — approved", "description": "The capture record. It is a new transaction whose `reference_transaction_id` points at the authorization it captured. `expiry` is null because expiry is not echoed back on capture responses. `batch_id` is now assigned, so the funds settle at the next batch close.", "value": { "id": "TRANSACTION-01KEW35B8QP4M2X9YHFT0KDN47", "reference_transaction_id": "TRANSACTION-01KEW32V6YNV11T336VEDKL123", "type": "CAPTURE", "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-15T16:08:23Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": null, "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" }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10434", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "CaptureTokenRequestExample": { "summary": "Capture a stored-token authorization", "description": "Captures the full $100.00 authorized by `authWithToken`. The capture request body is identical whichever payment method the authorization used — only the response differs.", "value": { "amount": 10000, "tip": 0 } }, "CaptureTokenResponseExample": { "summary": "Capture a stored-token authorization — approved", "description": "The capture record for a token authorization. `payment_method` reports the card the token resolves to, with `expiry` null because a capture does not echo it, and `reference_transaction_id` points at the authorization it captured.", "value": { "id": "TRANSACTION-01KEW37D0SR6P2Q8ZTGHA1CWX5", "reference_transaction_id": "TRANSACTION-01KEW34J7RS3N9P5WQDEX8ZTB2", "type": "CAPTURE", "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-15T16:19:05Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": null, "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" }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10435", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "VoidTransactionRequestExample": { "summary": "Void an unsettled transaction", "description": "Voids the sale created by `saleWithCard` before it settles. A void needs only the transaction `type`; the amount is always the full original amount. Send it to the transaction ID being voided.", "value": { "type": "VOID" } }, "VoidTransactionResponseExample": { "summary": "Void — approved", "description": "The void record. `type` comes back as `CANCEL`, which is the type returned on void and refund response records, and `reference_transaction_id` points at the sale that was voided. `expiry` and `cvv_result_code` are null because neither is re-checked on a void.", "value": { "id": "TRANSACTION-01KEW38F2RT6N4Z1AJGV5MPQ82", "reference_transaction_id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC", "type": "CANCEL", "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-15T17:30:44Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": null, "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": null }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10432", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "RefundTransactionRequestExample": { "summary": "Partially refund a settled transaction", "description": "Refunds $25.00 of the $100.00 sale created by `saleWithCard`. The amount must be less than or equal to the original transaction amount; this partial refund shows that rule in use. Send it to the transaction ID being refunded.", "value": { "type": "REFUND", "amount": 2500 } }, "RefundTransactionResponseExample": { "summary": "Partial refund — approved", "description": "The refund record. `amount` is the refunded amount, not the original sale amount. `type` comes back as `CANCEL`, and `reference_transaction_id` points at the sale that was refunded. The refund lands in the next open batch, so its own `batch_id` is not yet assigned.", "value": { "id": "TRANSACTION-01KEW3B7XKC9P5W2DMHY6NRS13", "reference_transaction_id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC", "type": "REFUND", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "00", "response_description": "Approved", "batch_id": null, "is_settled": false, "time_created": "2026-07-16T10:12:58Z", "amount": 2500, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB", "expiry": null, "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": null }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10432", "sales_channel": "web", "customer_reference": "cust-8891" } } }, "TransactionListResponseExample": { "summary": "First page of a transaction list", "description": "Three transactions from the same merchant and batch — the approved sale, the approved authorization, and the declined sale. `total_count` is 3 and `limit` is 10, so `has_more` is false and there is no next page to fetch.", "value": { "total_count": 3, "limit": 10, "offset": 0, "has_more": false, "transactions": [ { "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", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "auth_code": "123456", "retrieval_reference_number": "000000603076", "card_type": "CREDIT", "card_brand": "Visa", "cvv_result_code": "M", "avs_result_code": "Y" }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10432" } }, { "id": "TRANSACTION-01KEW32V6YNV11T336VEDKL123", "reference_transaction_id": null, "type": "AUTH", "result": "APPROVED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "00", "response_description": "Approved", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:02:11Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "auth_code": "123456", "retrieval_reference_number": "000000603076", "card_type": "CREDIT", "card_brand": "Visa", "cvv_result_code": "M", "avs_result_code": "Y" }, "initiator": "CUSTOMER", "network_transaction_id": "MCC1234567890", "metadata": { "order_id": "ORD-10434" } }, { "id": "TRANSACTION-01KEW36C9TQ5N1P7YRFGZ0BVW4", "reference_transaction_id": null, "type": "SALE", "result": "DECLINED", "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "client_dba": "Acme Jewelry", "integrations": [ "TSYS" ], "response_code": "51", "response_description": "Insufficient funds", "batch_id": null, "is_settled": false, "time_created": "2026-07-15T15:47:52Z", "amount": 10000, "tip": 0, "currency": "USD", "payment_method": { "type": "CARD", "truncated_pan": "****-****-****-5439", "expiry": { "month": "01", "year": "2028" }, "first_name": "John", "last_name": "Doe", "entry_method": "keyed", "retrieval_reference_number": "000000603077", "card_type": "CREDIT", "card_brand": "Visa", "cvv_result_code": "M", "avs_result_code": "Y" }, "initiator": "CUSTOMER", "network_transaction_id": null, "metadata": { "order_id": "ORD-10436" } } ] } }, "TsysIntegrationRequestExample": { "summary": "Onboard a TSYS merchant integration", "description": "A complete TSYS host configuration for the merchant. Twenty-nine of these fields are required — the gateway enforces them in `TsysHostDetailsValidator` — so this payload is close to the minimum a real onboarding needs rather than a generous illustration. The processor-specific identifiers here are illustrative placeholders.", "value": { "client": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "is_active": true, "processor": "Tsys", "integration_details": { "name": "Acme Jewelry LLC", "amex_number": "1234567890", "association": "123456", "bin": "888888", "discover_number": "123456789012345", "dba": "Acme Jewelry", "url": "https://example.apiserver.com", "phone_number": 17035550123, "fax_number": "+17035550199", "mid": "888000001234", "mcc": "5944", "bank_number": "1234", "industry": "R", "amex_opt_blue": true, "agent_chain": "012345", "store_number": "0001", "mvv": "123456", "terminal_number": "0001", "agent_bank_number": "123456", "agent_chain_number": "654321", "descriptor_postal": "22150", "descriptor_city": "Springfield", "descriptor_state": "VA", "descriptor_country": "US", "descriptor_phone": 17035550123, "descriptor_store_number": "0001", "address1": "123 Main St", "address2": "Suite 100", "descriptor_line3": "ACME JEWELRY 703-555-0123", "terminal_id": "00000001", "v_number": "V1234567", "settlement_time": "23:00", "merchant_area_code": 703, "descriptor_area_code": 703, "sharing_group": "AEFGKMQ", "merchant_aba_number": "123456789", "merchant_settlement_agent_number": "1234", "reimbursement_attribute": "0", "fcsid": "12345" } } }, "TsysIntegrationResponseExample": { "summary": "TSYS merchant integration created", "description": "The stored configuration, echoing back what was submitted and adding the `id` to reference it, the network identifiers TSYS assigns during onboarding (`amex_number`, `discover_number`, `association`, `bin`), and the audit fields.", "value": { "id": "INTEGRATION-01KFDKXMQ637EKEAY410MSQSXB", "is_active": true, "client": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "processor": "Tsys", "integration_details": { "name": "Acme Jewelry LLC", "dba": "Acme Jewelry", "url": "https://example.apiserver.com", "phone_number": 17035550123, "fax_number": "+17035550199", "mid": "888000001234", "amex_number": "1234567890", "association": "VISA", "bin": "431940", "discover_number": "601100999999", "mcc": "5944", "bank_number": "1234", "industry": "R", "amex_opt_blue": true, "agent_chain": "012345", "store_number": "0001", "mvv": "123456", "terminal_number": "0001", "agent_bank_number": "123456", "agent_chain_number": "654321", "descriptor_postal": "22150", "descriptor_city": "Springfield", "descriptor_state": "VA", "descriptor_country": "US", "descriptor_phone": 17035550123, "descriptor_store_number": "0001", "address1": "123 Main St", "address2": "Suite 100", "descriptor_line3": "ACME JEWELRY 703-555-0123", "terminal_id": "00000001", "v_number": "V1234567", "settlement_time": "23:00", "merchant_area_code": 703, "descriptor_area_code": 703, "sharing_group": "AEFGKMQ", "merchant_aba_number": "123456789", "merchant_settlement_agent_number": "1234", "reimbursement_attribute": "0", "fcsid": "12345", "created_by": 1042, "created_at": "2026-02-11T09:24:17Z", "modified_by": 1042, "modified_at": "2026-06-30T14:02:51Z" }, "correlation_id": "01KFDKXMQ637EKEAY410MSQSXB" } } }, "headers": { "RequestId": { "description": "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.", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "examples": [ "73039bd9-c380-4186-bffe-259125144a56" ] } } }, "responses": { "Conflict": { "description": "Conflict", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" }, "examples": { "duplicateAction": { "$ref": "#/components/examples/ConflictExample" } } } } }, "Unauthorized": { "description": "Not authenticated", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" }, "examples": { "notAuthenticated": { "$ref": "#/components/examples/UnauthorizedExample" } } } } }, "Forbidden": { "description": "Forbidden", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" }, "examples": { "unauthorizedAction": { "$ref": "#/components/examples/ForbiddenExample" } } } } }, "NotFound": { "description": "Not Found", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" }, "examples": { "resourceNotFound": { "$ref": "#/components/examples/NotFoundExample" } } } } }, "BadRequest": { "description": "Bad request", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" }, "examples": { "invalidRequestData": { "$ref": "#/components/examples/BadRequestExample" } } } } }, "BadGateway": { "description": "The gateway reached the downstream processor and could not use its response. Distinct from a 500, which is a fault inside the gateway.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadGateway" }, "examples": { "downstreamError": { "$ref": "#/components/examples/BadGatewayExample" } } } } }, "InternalServerError": { "description": "Internal server error", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" }, "examples": { "systemError": { "$ref": "#/components/examples/InternalServerErrorExample" } } } } } }, "parameters": { "BatchId": { "name": "batch_id", "description": "Filter results to transactions belonging to a specific batch.", "in": "query", "required": false, "schema": { "type": "string" }, "style": "form" }, "IsSettled": { "name": "is_settled", "description": "Whether the transaction is settled.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": true }, "CardType": { "name": "card_type", "description": "Filters transactions by card type. Send one value, or a comma-separated list to match any of several types — `card_type=CREDIT,DEBIT`. Values are matched case-insensitively.\n\nAccepts every value a transaction response can carry, including `UNKNOWN` for transactions whose card type the processor could not determine. `UNKNOWN` is the common case on most merchants, so a filter of `CREDIT` or `DEBIT` alone returns very few rows.\n\nThe open-batch filter on `GET /v1/batches/transactions` is a different parameter and does not behave the same way. See `OpenBatchCardType`.", "in": "query", "style": "form", "explode": false, "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CardType" } } }, "OpenBatchCardType": { "name": "card_type", "description": "Filters open-batch transactions by card type. Send a single value; this filter does not accept a list. Values are matched case-insensitively.\n\nTwo differences from the `card_type` filter on `GET /v1/transactions` are worth knowing before you rely on this one. `UNKNOWN` is rejected with a 400, because open-batch eligibility has no bucket for an undetermined card type. And `CREDIT` returns transactions whose card type is credit **or** undetermined, since the two are grouped together here. So the same value selects a wider set of rows on this operation than on `GET /v1/transactions`.", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OpenBatchCardType" } }, "Client-Id": { "name": "Client-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "ulid", "examples": [ "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "CLIENT-01KFDKXMQ637ETEAY410MSQTUH" ] } }, "X-Acting-As-Client-Id": { "name": "X-Acting-As-Client-Id", "in": "header", "required": false, "description": "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.\n\nThis 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.", "schema": { "type": "string", "format": "ulid", "examples": [ "CLIENT-01KFDKXMQ637EKEAY410MSQSXB", "CLIENT-01KFDKXMQ637ETEAY410MSQTUH" ] } }, "ClientId": { "name": "client_id", "description": "Filter results to transactions belonging to a specific client. Resellers use this to view transactions for a child merchant under their account. The authenticated caller must have permission to access the specified client's data. More than one client_id can be included by using a comma-separated list.", "in": "query", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true, "examples": { "merchant": { "value": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB" } } }, "CreatedGte": { "name": "created.gte", "description": "Return transactions created at or after this timestamp (inclusive). ISO 8601 format (UTC).", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, "CreatedLte": { "name": "created.lte", "description": "Return transactions created at or before this timestamp (inclusive). ISO 8601 format (UTC).", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, "Integration": { "name": "integration", "description": "Filter results to transactions belonging to a specific integration (e.g., payment processor such as TSYS or Vericheck).", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "TSYS", "VERICHECK" ] } }, "IncludeBadTransactions": { "name": "include_bad_transactions", "description": "Include bad transactions in the response. Bad transactions are transactions that failed to process due to errors or other issues.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, "Limit": { "name": "limit", "description": "Maximum number of transactions to return. Range: 1–1000.", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 100 } }, "Offset": { "name": "offset", "description": "Number of transactions to skip before returning results. Use with `limit` to select a specific window. For example, `offset=20&limit=20` returns records 21–40.", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0, "default": 0 } }, "CreatedAt": { "name": "created_at", "description": "Filter by time created.", "in": "query", "required": false, "schema": { "type": "string", "description": "Gateway API generated time indicating when the object was created. ", "pattern": "^\\d{2}/\\d{2}/\\d{4} \\d{2}:\\d{2}:\\d{2}$", "examples": [ "05/18/2026 16:49:29", "10/28/2026 05:49:29" ] } }, "TimeZone": { "name": "timezone", "description": "The time zone of the account.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "America/Los_Angeles", "America/Phoenix", "America/Denver", "America/Chicago", "America/New_York", "Pacific/Honolulu", "America/Anchorage" ], "x-enumDescriptions": { "America/Los_Angeles": "Pacific Time Zone", "America/Phoenix": "Mountain Standard Time (MST, no DST)", "America/Denver": "Mountain Time Zone", "America/Chicago": "Central Time Zone", "America/New_York": "Eastern Time Zone", "Pacific/Honolulu": "Hawaii-Aleutian Standard Time (HAST)", "America/Anchorage": "Alaska Time Zone" }, "examples": [ "America/New_York", "America/Los_Angeles" ] } }, "Type": { "name": "type", "description": "Filter by transaction type. Send one value, or a comma-separated list to match any of several types — `type=SALE,AUTH`. Values are matched case-insensitively.\n\nTwo current limitations are worth knowing before you rely on this filter. Filtering by `PAYOUT` is accepted but ignored, and returns unfiltered results rather than an error. Sending `VOID` returns a server error; a cancelled payment is reported as `CANCEL`, so filter on that instead.", "in": "query", "style": "form", "explode": false, "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionResponseType" } } }, "Result": { "name": "result", "description": "Filter by transaction result. Use `approved` to return only approved transactions or `declined` to return only declined transactions. When omitted, transactions with any result are returned.\nPossible values:\n\n - APPROVED\n - DECLINED\n - ERROR", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "APPROVED", "DECLINED", "ERROR" ] }, "x-enumDescriptions": { "APPROVED": "Approved transactions only", "DECLINED": "Declined transactions only", "ERROR": "Error transactions only" } }, "SortBy": { "name": "sort_by", "description": "Field to sort results by.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "CREATED", "TYPE", "RESULT" ], "x-enumDescriptions": { "CREATED": "Created timestamp.", "TYPE": "Transaction type.", "RESULT": "Transaction result." }, "default": "CREATED" } }, "SortOrder": { "name": "sort_order", "description": "Sort direction.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC", "x-enumDescriptions": { "ASC": "Ascending sort order.", "DESC": "Descending sort order." } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Api-Key", "description": "API key authentication. Include the API key in the `Api-Key` header.\n\n**WARNING**: API key-based authentication offers no cryptographic security; always use [HTTPS](https://developer.mozilla.org/en-US/docs/Glossary/HTTPS).\n\n**Example**:\n```http\n Api-Key: AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe\n```" } } } }