Process a payment (charge)

post

https://api.revaly.co/payments

Process a direct payment charge against a payment method.

This endpoint performs an immediate charge and settlement of funds.
Unlike authorization, the funds are immediately captured and transferred.

Payment Method Types:

creditCard: Process using raw credit card details
gatewayPaymentMethodId: Process using an existing gateway payment method id
vaultToken: Process using a vault-issued token (requires the request-level customerId)

paymentMethodType may be omitted when exactly one of paymentMethod.creditCard,
paymentMethod.gatewayPaymentMethod, or paymentMethod.vaultPaymentMethod is supplied —
the type is inferred. See the PaymentRequest schema for the per-type required fields.

To charge a previously stored payment method, omit paymentMethodType and supply paymentMethod.paymentMethodId.

A 404 originates from the fallback-processor path (reached when bypassPlatform: true
routes the payment directly to it, or when platform failover dispatches it): the fallback
processor could not find a resource the request references.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request to process a payment (charge) transaction

paymentMethodType

string | null

enum

Type of payment method to use:

creditCard: Use raw credit card details. Requires paymentMethod.creditCard
(number, expiryMonth, expiryYear) and a cardholder name — paymentMethod.fullName,
or paymentMethod.firstName together with paymentMethod.lastName.
gatewayPaymentMethodId: Use an existing gateway payment method identifier. Requires
paymentMethod.gatewayPaymentMethod.gatewayPaymentMethodId and
paymentMethod.merchantAccountReferenceId.
vaultToken: Use a vault-issued token (any provider). Requires
paymentMethod.vaultPaymentMethod.vaultToken and the request-level customerId — the
token is scoped to the customer it was minted for and cannot be detokenized without it.
Vault tokens are gateway-agnostic and can be processed on any gateway.

Omitting this property. When exactly one of paymentMethod.creditCard,
paymentMethod.gatewayPaymentMethod, or paymentMethod.vaultPaymentMethod is supplied,
the type is inferred from it. Supplying more than one of those objects without an explicit
type is rejected with 400. To bill a stored payment method, omit this property (and the
objects above) and send paymentMethod.paymentMethodId; recommendation flows
(previousTransaction / gateway) also carry no type.

Allowed:

amount

int64

required

≥ 0

Payment amount in smallest currency unit (e.g., cents for USD)

merchantTransactionId

string

required

length ≤ 100

Merchant-provided unique identifier for this transaction. The platform accepts up to 100 characters, but downstream gateways may enforce shorter limits on merchant references (limits near 50 characters have been observed); keep ids at or below 48 characters for the broadest gateway compatibility.

gatewayRoutingId

string | null

Gateway-specific token for payment processing

currency

string | null

^[A-Z]{3}$

Three-letter ISO currency code

initiatedBy

string | null

enum

Indicates who initiated the payment transaction:

MIT: Merchant-Initiated Transaction - Transaction initiated by the merchant without customer involvement
CIT: Customer-Initiated Transaction - Transaction initiated by the customer

Allowed:

mitStoredTransactionId

string | null

Merchant-initiated transaction stored credential ID

storedCredential

object

Stored credential information for recurring, installment, or unscheduled transactions

paymentMethod

object

Payment method details. Which fields are required depends on the payment-method type of the request: creditCard requires a cardholder name (fullName, or firstName together with lastName) plus creditCard.number/expiryMonth/expiryYear; gatewayPaymentMethodId requires gatewayPaymentMethod.gatewayPaymentMethodId and merchantAccountReferenceId; vaultToken requires vaultPaymentMethod.vaultToken plus the request-level customerId. When billing a stored payment method, supply paymentMethodId alone.

orderId

string | null

Order identifier from the merchant system

storeOnSuccess

boolean | null

Whether to store the payment method on successful transaction

bypassPlatform

boolean

Defaults to false

When true, bypass the primary Revaly processor and execute only the fallback flow

customerIp

string | null

Customer's IP address

customerId

string | null

Customer identifier

gatewayFields

object | null

Additional gateway-specific fields

rtnData

object

Typed RTN 1.1 fraud-signal payload (customer signals only). Transaction-core fields (bin, lastFourCardNumber, purchaseAmount, purchaseCurrency, clientInitiatedDate, traceId, providerId) are derived by Revaly at submission time and must not be sent. The full PAN (additionalTransactionData.fullPan) is optional and, if sent, is forwarded to RTN in-flight only.

description

string | null

Transaction description

statementDescriptor

string | null

Merchant-supplied text intended to appear on the customer's bank/card statement. Accepted as free text; per-gateway length and character adaptation is applied at submission and never blocks the charge.

threeDS

object | null

3D Secure authentication data for payment processing

paymentPlanData

object

Payment plan and subscription information for recurring transactions

recovery

object

Recovery settings and customer recovery information

previousTransaction

object

Information about a previous transaction for reference

gateway

object

Gateway configuration and settings

Headers

X-Api-Version

string

enum

Defaults to 2.0

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.

Allowed:

Responses

200Payment processed successfully

400Bad request - invalid parameters or request body. Validation failures carry a details object keyed by the offending fields; business-rule rejections may carry error alone.

401Unauthorized - invalid or missing API key

403Forbidden - the authenticated principal is not permitted to perform this action

404Resource not found

422Unprocessable entity - validation succeeded but the request cannot be processed

500Internal server error

503Service unavailable - upstream dependency temporarily unavailable