--- updatedAt: 2026-06-16T13:42:46.000Z agentTools: projectIndex: https://docs.revaly.co/llms.txt --- # Get transaction details by merchant transaction ID Retrieve detailed information about a specific transaction by its merchant transaction ID. This endpoint returns complete transaction data including payment method details, gateway response information, recovery data and status of transaction using the merchant-provided transaction identifier. **Inline-retry resolution:** platform-initiated inline retry attempts carry platform-assigned transaction identifiers. This lookup resolves the payment submitted under the merchant id and returns its definitive (latest) attempt, so an approval won on a retry is found under the id the merchant submitted. In that case the returned `merchantTransactionId` is the platform-assigned attempt id rather than the path value; use the grouped view (`includeAllTransactions=true`) to list every attempt. **Pending intent:** when the platform has accepted a payment with this merchantTransactionId (intent recorded before gateway dispatch) but no transaction record is visible yet, the lookup returns a `PendingTransactionResponse` (`state: pending`) instead of 404 — hold and re-poll until it resolves to the full transaction. A 404 means no payment with this id was ever accepted. Pending intents are not returned on the grouped view (`includeAllTransactions=true`), which lists only visible transaction records. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Revaly", "version": "2.6.0", "description": "Payment processing API for transaction and payment method management.\n\n## API Versioning\n\nRAP supports an explicit, selectable API version so you can build against a\nstable, pinned contract while existing integrations keep working unchanged.\n\n- **How to select a version:** send the `X-Api-Version` request header\n (e.g. `X-Api-Version: 2.0`). The version lives in the header — request\n URLs do not change.\n- **Default when omitted:** requests without the header (or with an\n unrecognised header name) bind to the **base version `2.0`**, which is the\n current contract. Existing integrations therefore continue unchanged.\n- **Unsupported versions:** a header naming a version that does not exist\n returns **HTTP 400** with a structured error listing the supported\n versions — a request is never silently bound to a different contract.\n This includes an **empty or whitespace value**: if the `X-Api-Version`\n header is present, it must name a supported version. Only a fully\n absent header binds to the default.\n- **Supported versions** are advertised via the `api-supported-versions`\n header on every response from the versioned API endpoints (payments,\n payment methods, transactions, notify). Currently: `2.0`, `2.1`.\n- **Which version to use:** new integrations should pin **`2.1`**. It is\n behaviourally identical to `2.0` today, and it is where future contract\n refinements will land — pinning it now means you never migrate the\n header. `2.0` is the frozen launch contract and remains the binding for\n requests that send no version header.\n\n## Request tracing\n\nEvery API response — success and error alike — carries an\n`X-Correlation-ID` header. Send your own value (any non-empty string) and\nit is echoed back verbatim; omit it and the platform generates one. Quote\nthe id when contacting support: it joins the request directly to platform\ntelemetry. Treat it as an opaque string.\n" }, "servers": [ { "url": "https://api.revaly.co", "description": "Production API" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Transactions", "description": "Operations related to transactions", "externalDocs": { "description": "Transactions Guide", "url": "https://docs.revaly.co/transactions" } } ], "paths": { "/transactions/merchant/{merchantTransactionId}": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" } ], "get": { "tags": [ "Transactions" ], "summary": "Get transaction details by merchant transaction ID", "description": "Retrieve detailed information about a specific transaction by its merchant transaction ID.\n\nThis endpoint returns complete transaction data including payment method details,\ngateway response information, recovery data and status of transaction using the\nmerchant-provided transaction identifier.\n\n**Inline-retry resolution:** platform-initiated inline retry attempts carry\nplatform-assigned transaction identifiers. This lookup resolves the payment submitted\nunder the merchant id and returns its definitive (latest) attempt, so an approval won\non a retry is found under the id the merchant submitted. In that case the returned\n`merchantTransactionId` is the platform-assigned attempt id rather than the path value;\nuse the grouped view (`includeAllTransactions=true`) to list every attempt.\n\n**Pending intent:** when the platform has accepted a payment with this\nmerchantTransactionId (intent recorded before gateway dispatch) but no transaction\nrecord is visible yet, the lookup returns a `PendingTransactionResponse`\n(`state: pending`) instead of 404 — hold and re-poll until it resolves to the full\ntransaction. A 404 means no payment with this id was ever accepted. Pending intents\nare not returned on the grouped view (`includeAllTransactions=true`), which lists\nonly visible transaction records.\n", "operationId": "getTransactionByMerchantTransactionId", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantTransactionId", "in": "path", "required": true, "description": "Merchant-provided unique identifier for the transaction", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "merchant_auth_12345638934760478405277" }, { "name": "includeAllTransactions", "in": "query", "required": false, "description": "When `true`, returns every transaction belonging to the same payment (all attempts and\nlifecycle operations sharing the initial transaction id) as a `TransactionGroupResponse`\nenvelope, instead of the single matching `TransactionResponse`. Supported only on\nrepository-backed lookups; otherwise returns `400`. If the matched transaction has no\ninitial transaction id, only that single transaction is returned.\n", "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "description": "Successfully retrieved transaction details. Returns a single `TransactionResponse` by\ndefault, or a `TransactionGroupResponse` envelope when `includeAllTransactions=true`.\nReturns a `PendingTransactionResponse` (`state: pending`) when the payment intent was\naccepted but no transaction record is visible yet.\n\nDiscriminate by required members: a body with `state: \"pending\"` is a\n`PendingTransactionResponse`; a body with `transactions` is a `TransactionGroupResponse`\nenvelope; otherwise it is a single `TransactionResponse`. Branches are ordered\nmost-specific first for match-in-order deserializers.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PendingTransactionResponse" }, { "$ref": "#/components/schemas/TransactionGroupResponse" }, { "$ref": "#/components/schemas/TransactionResponse" } ] }, "examples": { "pendingIntent": { "summary": "Accepted payment intent, transaction not yet visible", "value": { "state": "pending", "merchantTransactionId": "merchant_auth_12345638934760478405277", "transactionType": "Charge", "receivedAt": "2026-07-13T18:30:00Z" } }, "approvedTransaction": { "summary": "Successful transaction with full details", "value": { "transactionId": "06CMKH53T000000G002AV9009TDGM", "transactionDate": "2025-09-14T19:47:27.824Z", "transactionStatus": 1, "message": "Approved.", "responseCode": "10000", "transactionType": "Charge", "merchantTransactionId": "merchant_auth_12345638934760478405277", "customerId": "ruskoff-05911", "gatewayRoutingId": "B26LRWGVAYCEDE5MAGMTIWRJFY", "currency": "USD", "amount": 2500, "gatewayType": "authorize_net", "gatewayTransactionId": "order_987654321", "orderId": "order_987654321", "customerIp": "192.168.1.100", "description": "Payment for online purchase", "engagedRecoveryState": 0, "response": { "avsCode": "", "avsMessage": "", "cvvCode": "", "cvvMessage": "", "errorDetail": "Successful purchase" }, "paymentMethod": { "paymentMethodId": "F66XGUAJNK3E7HSUAGMUTRFGSA", "paymentMethodType": "creditCard", "lastFourDigits": "1111", "firstSixDigits": "411111", "cardType": "VISA", "fingerprint": "cb1fb16ddae22529333efc44c35219901c38", "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "email": "john.doe@example.com", "creditCardNumber": "411111******1111", "expiryMonth": "12", "expiryYear": "2025", "cvv": "***", "phoneNumber": "1-555-123-4567", "bin": "41111111", "dateCreated": "2025-09-14T19:47:28.528Z", "storageState": "Stored", "billingAddress": { "address1": "123 Main Street", "address2": "Apt 4B", "city": "New York", "state": "NY", "zip": "10001", "country": "US", "phoneNumber": "1-555-123-4567" }, "shippingAddress": { "address1": "456 Oak Avenue", "address2": "Suite 201", "city": "Los Angeles", "state": "CA", "zip": "90210", "country": "US" } }, "recovery": { "disableCustomerRecovery": false, "retryCount": 0, "paymentReferenceData": "initial_ref_id", "dateFirstAttempt": "2025-09-14T19:47:27.824Z" }, "paymentPlanData": { "sku": "PRODUCT-001", "category": "Electronics", "billingPlan": "monthly", "billingCycle": 1, "subscriptionId": "sub_123456789" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "parameters": { "ApiVersionHeader": { "name": "X-Api-Version", "in": "header", "required": false, "description": "Selects the RAP API version for this request. New integrations should pin `2.1` (identical to `2.0` today; future refinements land there). Omit to use the base version (`2.0`). A value naming an unsupported version — including an empty value — returns HTTP 400; if the header is sent, it must name a supported version. See the API description for the full version policy.", "schema": { "type": "string", "enum": [ "2.0", "2.1" ], "default": "2.0" }, "example": "2.1" } }, "headers": { "XCorrelationId": { "description": "The request correlation id. Echoed verbatim when the caller sends an X-Correlation-ID request header (any non-empty value); generated by the platform otherwise. Present on every API response, success and error alike. Quote it when contacting support — it joins the request directly to platform telemetry. Treat it as an opaque string.", "schema": { "type": "string" }, "example": "0af7651916cd43dd8448eb211c80319c" } }, "responses": { "BadRequest": { "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "description": "Bad request - invalid parameters or request body. Validation failures carry a `details` object keyed by the offending fields; business-rule rejections may carry `error` alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Invalid request parameters" } } } }, "Unauthorized": { "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "details": "API key is required." } } } }, "NotFound": { "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Resource not found" } } } }, "InternalServerError": { "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "An unexpected error occurred.", "code": "outcome_unknown" } } } }, "Forbidden": { "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "description": "Forbidden - the authenticated principal is not permitted to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Forbidden" } } } }, "UnprocessableEntity": { "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "description": "Unprocessable entity - validation succeeded but the request cannot be processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unprocessable entity" } } } }, "ServiceUnavailable": { "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "description": "Service unavailable - upstream dependency temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notProcessed": { "summary": "Rejected before dispatch — safe to fail over", "description": "The upstream circuit breaker was already open, so the request was rejected before any dispatch attempt. The payment was definitively not processed.", "value": { "error": "Service is temporarily unavailable.", "code": "not_processed" } }, "outcomeUnknown": { "summary": "Upstream failure at or after dispatch — outcome unknown", "description": "An upstream dependency reported a failure after the request may have been dispatched. Reconcile the transaction before retrying.", "value": { "error": "Service Unavailable: Please try again later.", "code": "outcome_unknown" } } } } } } }, "schemas": { "Address": { "type": "object", "description": "Address information for billing or shipping", "properties": { "address1": { "type": "string", "description": "Primary address line", "maxLength": 255, "example": "123 Main St", "nullable": true }, "address2": { "type": "string", "description": "Secondary address line (apartment, suite, etc.)", "maxLength": 255, "example": "Apt 4B", "nullable": true }, "city": { "type": "string", "description": "City name", "maxLength": 100, "example": "New York", "nullable": true }, "state": { "type": "string", "description": "State or province code", "maxLength": 10, "example": "NY", "nullable": true }, "zip": { "type": "string", "description": "Postal or ZIP code", "maxLength": 20, "example": "10001", "nullable": true }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "example": "US", "nullable": true }, "phoneNumber": { "type": "string", "description": "Phone number associated with the address", "maxLength": 20, "example": "+1-555-123-4567", "nullable": true } }, "example": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "state": "NY", "zip": "10001", "country": "US", "phoneNumber": "+1-555-123-4567" } }, "BillingPlan": { "type": "string", "description": "Billing plan frequency and type for the subscription or payment model.\n\nAvailable billing plans:\n- **trial**: Free or limited introductory period (variable interval, days/weeks)\n- **weekly**: Billed every week (1 week interval)\n- **twicePerWeek**: Billed twice per week (3-4 days interval) - User is billed 2x per week\n- **biWeekly**: Billed every 2 weeks (different than twice per month)\n- **biMonthly**: Billed twice per month (2x per month)\n- **monthly**: Standard monthly billing (1 month interval) - Standard SaaS cadence\n- **quarterly**: Billed every 3 months - Often used for small business or agency plans\n- **semiAnnual**: Billed every 6 months - Common prepaid option\n- **annual**: Billed yearly (12 months interval) - Discounted yearly plan\n- **biennial**: Billed every 2 years (24 months) - Long-term or enterprise contracts\n- **triennial**: Billed every 3 years (36 months) - Multi-year hosting or enterprise terms\n- **usageBased**: Pay-as-you-go or metered billing - Billed per usage or seat count each cycle (varies)\n- **lifetime**: One-time payment with no renewal required\n- **custom**: Negotiated or legacy plans with custom terms (variable)\n- **other**: Fallback for undefined, experimental, or unspecified billing plans\n", "enum": [ "trial", "weekly", "twicePerWeek", "biWeekly", "biMonthly", "monthly", "quarterly", "semiAnnual", "annual", "biennial", "triennial", "usageBased", "lifetime", "custom", "other" ], "example": "monthly", "nullable": true }, "ErrorResponse": { "type": "object", "description": "Standard error response format used across all API endpoints", "properties": { "error": { "type": "string", "description": "A human-readable error message describing what went wrong", "example": "Invalid request parameters" }, "details": { "description": "Optional additional details about the error; structure varies by error type (may be an object, a string, or null)", "example": null }, "code": { "type": "string", "enum": [ "not_processed", "outcome_unknown" ], "description": "Machine-readable safety signal, present on every 5xx error response and never on 4xx responses. `not_processed` is emitted only when the platform can prove the request was never dispatched to a payment gateway or upstream (for example, the upstream circuit breaker was already open), so the caller may safely fail over without risking a duplicate charge. `outcome_unknown` means the request may have reached an upstream and the outcome cannot be proven; reconcile the transaction before retrying. Emission is conservative — any 5xx without a provable determination carries `outcome_unknown`.", "example": "outcome_unknown" } }, "required": [ "error" ] }, "PaymentMethodResponse": { "type": "object", "description": "Payment method information associated with a transaction", "properties": { "paymentMethodId": { "type": "string", "description": "Unique identifier for the payment method", "minLength": 1, "maxLength": 50, "example": "7DA6XQ33AIPUZLLDAGMXYHNTG4", "nullable": true }, "creditCardNumber": { "type": "string", "description": "Masked credit card number", "example": "****-****-****-4242", "nullable": true }, "expiryMonth": { "type": "string", "description": "Credit card expiry month", "pattern": "^(0[1-9]|1[0-2])$", "example": "12", "nullable": true }, "expiryYear": { "type": "string", "description": "Credit card expiry year", "pattern": "^20[0-9]{2}$", "example": "2025", "nullable": true }, "cvv": { "type": "string", "description": "Masked card verification value", "example": "***", "nullable": true }, "firstName": { "type": "string", "description": "Cardholder's first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Cardholder's last name", "example": "Doe", "nullable": true }, "fullName": { "type": "string", "description": "Cardholder's full name", "example": "John Doe", "nullable": true }, "customerId": { "type": "string", "description": "Customer identifier", "example": "cust_9876543210fedcba", "nullable": true }, "billingAddress": { "$ref": "#/components/schemas/Address" }, "shippingAddress": { "$ref": "#/components/schemas/Address" }, "email": { "type": "string", "format": "email", "description": "Customer's email address", "example": "john.doe@example.com", "nullable": true }, "phoneNumber": { "type": "string", "description": "Customer's phone number", "example": "+1234567890", "nullable": true }, "paymentMethodType": { "type": "string", "description": "Type of payment method", "example": "creditCard", "nullable": true }, "fingerprint": { "type": "string", "description": "Unique fingerprint for the payment method", "example": "abc123def456", "nullable": true }, "lastFourDigits": { "type": "string", "description": "Last four digits of the payment method", "pattern": "^[0-9]{4}$", "example": "4242", "nullable": true }, "firstSixDigits": { "type": "string", "description": "First six digits of the payment method (BIN)", "pattern": "^[0-9]{6}$", "example": "424242", "nullable": true }, "cardType": { "type": "string", "description": "Type of credit card", "example": "visa", "nullable": true }, "dateCreated": { "type": "string", "format": "date-time", "description": "Date when the payment method was created", "example": "2024-01-15T10:30:00Z", "nullable": true }, "storageState": { "type": "string", "description": "Storage state of the payment method", "example": "stored", "nullable": true }, "bin": { "type": "string", "description": "Bank Identification Number. Must contain exactly 6 or 8 digits.", "pattern": "^(?:[0-9]{6}|[0-9]{8})$", "example": "424242", "nullable": true }, "vaultToken": { "type": "string", "description": "Opaque reference to the stored card this payment method used, returned so a transaction can be tied back to its credential without a second lookup.\n\nPresent on the payment method nested inside a **charge or authorize** response, and on the **single-transaction reads** (`GET /transactions/{transactionId}` and `GET /transactions/merchant/{merchantTransactionId}`), whenever that transaction ran against a vault credential — either one you presented, or one this API created for you when it vaulted the card you sent. The paged list reports it too, but **flat on the row** rather than nested here. The transaction-group reads (`?includeAllTransactions=true`) report it on every transaction in the group. Follow-up responses (capture, void, refund, refund-cancel) carry no payment method today, so they report no token. Always omitted on the stored payment method endpoints (`/paymentmethods` show, list): a stored payment method cannot be created from a vault token, so it never has one to report.\n\nReads are a snapshot of the value recorded at processing time and do not re-resolve the credential. Where the token can be resolved live, this is the token **currently live** for the credential, which is not always the token submitted — if the card was replaced by the Account Updater, the value is the new head of the lineage. Otherwise it is the token the transaction was dispatched with, and does not reflect a roll. Which of the two you get depends on how the transaction was processed, so treat it as optional throughout and do **not** treat a missing or unchanged value as proof the card was not rolled. Recording began with API version **2.6.0**: transactions processed earlier report no token at all and cannot be backfilled. This is the only place the token is reported — there is deliberately no copy at the transaction level.", "example": "5454541rYN4c5454", "nullable": true } }, "example": { "paymentMethodId": "7DA6XQ33AIPUZLLDAGMXYHNTG4", "paymentMethodType": "creditCard", "lastFourDigits": "4242", "firstSixDigits": "424242", "cardType": "visa", "fingerprint": "abc123def456", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "billingAddress": { "address1": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "country": "US" } } }, "TransactionResponse": { "type": "object", "description": "Complete transaction information including processing details", "properties": { "transactionId": { "type": "string", "description": "Unique identifier for the transaction", "minLength": 1, "maxLength": 50, "example": "06CQR5TMB800000G0011NCFRVY37A", "nullable": true }, "transactionDate": { "type": "string", "format": "date-time", "description": "Date and time when the transaction was processed (ISO 8601)", "example": "2024-01-15T10:30:00Z", "nullable": true }, "transactionStatus": { "type": "integer", "description": "Current status of the transaction (1 = Approved, 2 = Declined, 3 = Error)", "example": 1, "nullable": true }, "message": { "type": "string", "description": "Human-readable message about the transaction result", "example": "Transaction approved successfully", "nullable": true }, "responseCode": { "type": "string", "description": "Gateway-specific response code", "example": "00", "nullable": true }, "transactionType": { "type": "string", "description": "Type of transaction performed. Passthrough of the processing platform's transaction type — not a closed set. Payment operations return \"Charge\", \"Authorize\", \"Capture\", \"Void\" or \"Refund\" (refund cancellation returns \"Refund\"). Transaction lookups can additionally return types created by other platform flows, e.g. \"Verify\", \"SuccessfulPayment\", \"RefundedPayment\", \"CreateCreditCard\", \"UpdatePaymentMethod\", \"RedactPaymentMethod\", \"RecachePaymentMethod\", \"CreateGatewayPaymentMethod\". Treat unrecognized values as informational.", "example": "Charge", "nullable": true }, "merchantTransactionId": { "type": "string", "description": "Merchant-provided transaction identifier", "example": "order_12345", "nullable": true }, "customerId": { "type": "string", "description": "Customer identifier associated with the transaction", "example": "cust_9876543210fedcba", "nullable": true }, "gatewayRoutingId": { "type": "string", "description": "Gateway-specific token for the transaction", "example": "gateway_routing_id_abc123", "nullable": true }, "currency": { "type": "string", "description": "Transaction currency code (ISO 4217)", "pattern": "^[A-Z]{3}$", "example": "USD", "nullable": true }, "amount": { "type": "integer", "format": "int64", "description": "Transaction amount in smallest currency unit (e.g., cents for USD)", "minimum": 0, "example": 2500, "nullable": true }, "gatewayType": { "type": "string", "description": "Payment gateway used for processing", "example": "stripe", "nullable": true }, "gatewayTransactionId": { "type": "string", "description": "Gateway-specific transaction identifier", "example": "pi_1234567890abcdef", "nullable": true }, "acquirerAuthCode": { "type": "string", "description": "Authorization code returned by the acquiring bank or network", "example": "AUTH1234", "nullable": true }, "inlineRetryPreviousTransactionId": { "type": "string", "description": "Transaction identifier of the inline retry attempt when one was executed", "example": "txn_inline_123456", "nullable": true }, "inlineRetryPreviousMerchantTransactionId": { "type": "string", "description": "Original merchant transaction identifier before an inline retry was executed", "example": "merchant_txn_original", "nullable": true }, "isInlineRetry": { "type": "boolean", "description": "Indicates that an inline retry attempt occurred", "example": true, "nullable": true }, "retryDate": { "type": "string", "format": "date-time", "description": "Date for retry attempt (if applicable)", "example": "2024-01-16T10:30:00Z", "nullable": true }, "mitStoredTransactionId": { "type": "string", "description": "Merchant-initiated transaction stored credential ID", "example": "mit_1234567890abcdef", "nullable": true }, "storedCredential": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StoredCredentialResponse" } ] }, "orderId": { "type": "string", "description": "Order identifier from the merchant system", "example": "order_67890", "nullable": true }, "statementDescriptor": { "type": "string", "maxLength": 255, "description": "Merchant-supplied text intended for the customer's card or bank statement, echoed back bounded to 255 characters. Adapted per gateway (length/charset) at submission and never blocks the charge.", "example": "ACME* SUBSCRIPTION", "nullable": true }, "customerIp": { "type": "string", "description": "Customer's IP address at time of transaction", "example": "192.168.1.100", "nullable": true }, "engagedRecoveryState": { "type": "integer", "description": "Recovery state indicator (0 = not engaged, 1+ = recovery level)", "minimum": 0, "example": 0, "nullable": true }, "description": { "type": "string", "description": "Transaction description or notes", "example": "Payment for premium subscription", "nullable": true }, "gatewayFields": { "type": "object", "description": "Additional gateway-specific fields", "additionalProperties": true, "example": { "processor_id": "12345", "network_transaction_id": "abc123xyz789" }, "nullable": true }, "gatewaySpecificResponseFields": { "type": "object", "description": "Additional gateway-specific response details returned directly from the processor", "additionalProperties": true, "example": { "gatewayCode": "00", "gatewayMessage": "Approved" }, "nullable": true }, "paymentPlanData": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PaymentPlanData" } ] }, "recovery": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Recovery" } ] }, "response": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionResponseDetails" } ] }, "paymentMethod": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PaymentMethodResponse" } ] } }, "example": { "transactionId": "1234567890abcdef", "transactionDate": "2024-01-15T10:30:00Z", "transactionStatus": 1, "message": "Transaction approved successfully", "responseCode": "00", "transactionType": "Charge", "merchantTransactionId": "order_12345", "customerId": "cust_9876543210fedcba", "gatewayRoutingId": "gateway_routing_id_abc123", "currency": "USD", "amount": 2500, "gatewayType": "stripe", "gatewayTransactionId": "pi_1234567890abcdef", "acquirerAuthCode": "AUTH1234", "inlineRetryPreviousTransactionId": "txn_inline_123456", "inlineRetryPreviousMerchantTransactionId": "merchant_txn_original", "isInlineRetry": true, "mitStoredTransactionId": "mit_1234567890abcdef", "storedCredential": { "reasonType": "recurring", "initialNetworkTransactionId": "019078743540000", "latestNetworkTransactionId": "019078743540001", "gatewayInitialTransactionId": "gw_initial_abc123", "gatewayLatestTransactionId": "gw_latest_def456" }, "orderId": "order_67890", "statementDescriptor": "ACME* SUBSCRIPTION", "customerIp": "192.168.1.100", "description": "Payment for premium subscription", "engagedRecoveryState": 0, "gatewayFields": { "processor_id": "12345", "network_transaction_id": "abc123xyz789" }, "gatewaySpecificResponseFields": { "gatewayCode": "00", "gatewayMessage": "Approved" }, "response": { "avsCode": "Y", "avsMessage": "Address verification successful", "cvvCode": "M", "cvvMessage": "CVV verification successful" }, "paymentMethod": { "paymentMethodId": "7DA6XQ33AIPUZLLDAGMXYHNTG4", "paymentMethodType": "creditCard", "lastFourDigits": "4242", "firstSixDigits": "424242", "cardType": "visa", "fingerprint": "abc123def456" }, "recovery": { "disableCustomerRecovery": false, "customerAccountNumber": "ACC-001234", "customerBalance": 0 }, "paymentPlanData": { "sku": "PREMIUM_MONTHLY", "category": "FDT", "billingPlan": "monthly", "subscriptionId": "sub_1234567890" } } }, "PendingTransactionResponse": { "type": "object", "description": "Pending payment intent. Returned by the merchant-transaction lookup when the platform has accepted a payment with this merchantTransactionId (the intent was durably recorded before gateway dispatch) but no transaction record is visible yet. Poll the same lookup again: it resolves to the full TransactionResponse once the transaction becomes visible. This shape is deliberately distinct from TransactionResponse — use the required `state` field as the discriminator.", "required": [ "state", "merchantTransactionId" ], "properties": { "state": { "type": "string", "description": "Always `pending` — discriminates this shape from a completed transaction.", "enum": [ "pending" ], "example": "pending" }, "merchantTransactionId": { "type": "string", "description": "Merchant-provided transaction identifier the intent was recorded under", "minLength": 1, "maxLength": 100, "example": "charge_order_12345" }, "transactionType": { "type": "string", "description": "Operation the intent was recorded for — \"Charge\" or \"Authorize\" (same vocabulary as TransactionResponse.transactionType).", "example": "Charge", "nullable": true }, "receivedAt": { "type": "string", "format": "date-time", "description": "When the platform recorded the payment intent (ISO 8601)", "example": "2026-07-13T18:30:00Z", "nullable": true } }, "example": { "state": "pending", "merchantTransactionId": "charge_order_12345", "transactionType": "Charge", "receivedAt": "2026-07-13T18:30:00Z" } }, "TransactionGroupResponse": { "type": "object", "description": "Envelope returned by the V2 transaction-details lookups when `includeAllTransactions=true`.\nContains the matched transaction plus every transaction belonging to the same payment — all\nattempts and lifecycle operations (capture, refund, void) that share the same initial\ntransaction id. If the matched transaction has no initial transaction id, `transactions`\ncontains only the matched record.\n\nThe required `transactions` member is always present and discriminates this envelope from\na single `TransactionResponse`, which never carries a `transactions` member.\n", "required": [ "transactions" ], "properties": { "transaction": { "allOf": [ { "$ref": "#/components/schemas/TransactionResponse" } ], "description": "The transaction matching the supplied id (the record the non-expanded lookup returns)." }, "transactions": { "type": "array", "description": "Every transaction in the payment, ordered by transaction date ascending. Capped at 100.", "items": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "PaymentPlanData": { "type": "object", "description": "Payment plan and subscription information for recurring transactions", "properties": { "sku": { "type": "string", "description": "Stock Keeping Unit identifier for the product", "example": "PREMIUM_MONTHLY", "nullable": true }, "category": { "type": "string", "description": "Product category", "example": "subscription", "nullable": true }, "billingPlan": { "$ref": "#/components/schemas/BillingPlan" }, "subscriptionId": { "type": "string", "description": "Subscription identifier", "example": "sub_1234567890", "nullable": true }, "billingCycle": { "type": "integer", "description": "Number of billing cycles", "example": 1, "nullable": true }, "paymentModel": { "type": "string", "description": "Payment model type", "example": "recurring", "nullable": true }, "productDisplayName": { "type": "string", "description": "Human-readable product name", "example": "Premium Monthly Plan", "nullable": true } }, "example": { "sku": "PREMIUM_MONTHLY", "category": "FDT", "billingPlan": "monthly", "subscriptionId": "sub_1234567890", "billingCycle": 1, "paymentModel": "recurring", "productDisplayName": "Premium Monthly Plan" } }, "Recovery": { "type": "object", "description": "Recovery settings and customer recovery information", "properties": { "disableCustomerRecovery": { "type": "boolean", "description": "Whether customer recovery is disabled for this transaction", "example": false, "nullable": true }, "externalApproval": { "type": "boolean", "description": "Describes whether the approval should be attributed to the merchant for billing purposes", "example": false, "nullable": true }, "customerAccountNumber": { "type": "string", "description": "Customer account number for recovery purposes", "maxLength": 100, "example": "ACC123456", "nullable": true }, "customerBalance": { "type": "integer", "format": "int32", "description": "Customer account balance in smallest currency unit (e.g., cents for USD)", "minimum": 0, "example": 0, "nullable": true }, "disableSMSNotification": { "type": "boolean", "description": "Whether SMS notifications are disabled for recovery", "example": false, "nullable": true }, "disableEmailNotification": { "type": "boolean", "description": "Whether email notifications are disabled for recovery", "example": false, "nullable": true }, "retryCount": { "type": "integer", "description": "Number of retry attempts for this billing cycle (initial attempt is 0)", "minimum": 0, "example": 0, "nullable": true }, "paymentReferenceData": { "type": "string", "description": "Reference data received when a payment failed. This data should be returned on retry transactions for the same payment.", "maxLength": 500, "example": "ref_original_12345", "nullable": true }, "dateFirstAttempt": { "type": "string", "format": "date-time", "description": "Date and time of the first transaction attempt for this billing cycle. Required when retry count is greater than 0.", "example": "2025-01-15T10:30:00Z", "nullable": true } }, "example": { "disableCustomerRecovery": false, "customerAccountNumber": "ACC123456", "customerBalance": 0, "disableSMSNotification": false, "disableEmailNotification": false, "retryCount": 0, "paymentReferenceData": "ref_original_12345", "dateFirstAttempt": "2025-01-15T10:30:00Z" } }, "StoredCredentialResponse": { "type": "object", "description": "Stored credential information returned from the gateway for recurring, installment, or unscheduled transactions", "properties": { "reasonType": { "$ref": "#/components/schemas/StoredCredentialReasonType" }, "initialNetworkTransactionId": { "type": "string", "description": "Network transaction ID from the initial transaction that established the stored credential, returned by the gateway", "maxLength": 100, "example": "019078743540000", "nullable": true }, "latestNetworkTransactionId": { "type": "string", "description": "Network transaction ID from the most recent transaction using this stored credential, returned by the gateway", "maxLength": 100, "example": "019078743540001", "nullable": true }, "gatewayInitialTransactionId": { "type": "string", "description": "Gateway's own transaction ID from the initial transaction that established the stored credential", "maxLength": 100, "example": "gw_initial_abc123", "nullable": true }, "gatewayLatestTransactionId": { "type": "string", "description": "Gateway's own transaction ID from the most recent transaction using this stored credential", "maxLength": 100, "example": "gw_latest_def456", "nullable": true } }, "example": { "reasonType": "recurring", "initialNetworkTransactionId": "019078743540000", "latestNetworkTransactionId": "019078743540001", "gatewayInitialTransactionId": "gw_initial_abc123", "gatewayLatestTransactionId": "gw_latest_def456" } }, "StoredCredentialReasonType": { "type": "string", "description": "Indicates the reason for using a stored credential:\n- **unscheduled**: An unscheduled transaction using stored credentials\n- **recurring**: A recurring payment using stored credentials\n- **installment**: An installment payment using stored credentials\n", "enum": [ "unscheduled", "recurring", "installment" ], "example": "recurring", "nullable": true }, "TransactionResponseDetails": { "type": "object", "description": "Detailed transaction processing response information from the payment gateway", "properties": { "avsCode": { "type": "string", "description": "Address Verification System result code", "example": "Y", "nullable": true }, "avsMessage": { "type": "string", "description": "Address Verification System result message", "example": "Address verification successful", "nullable": true }, "cvvCode": { "type": "string", "description": "Card Verification Value result code", "example": "M", "nullable": true }, "cvvMessage": { "type": "string", "description": "Card Verification Value result message", "example": "CVV verification successful", "nullable": true }, "errorCode": { "type": "string", "description": "Error code if transaction failed", "example": "DECLINED", "nullable": true }, "errorDetail": { "type": "string", "description": "Detailed error message if transaction failed", "example": "Insufficient funds available", "nullable": true } }, "example": { "avsCode": "Y", "avsMessage": "Address verification successful", "cvvCode": "M", "cvvMessage": "CVV verification successful" } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API Key authentication using the Authorization header.\nFormat: `Authorization: ApiKey YOUR_API_KEY_HERE`\n" } } } } ```