Authorize a payment
Authorizes the requested amount and leaves the payment in the AUTHORIZED state for later capture or void. The request can optionally save the payment method for future use. When the issuer requires 3-D Secure, the call returns 201 with status REQUIRES_ACTION and a nextAction redirect for the customer; the final state settles asynchronously (poll GET /payments/:id).
Authorization
basic Basic HTTP authentication
In: header
Header Parameters
Optional client-supplied retry key (≤255 chars; UUID v4 recommended). Don't use sensitive data — emails, PANs, or other personal identifiers. Identical requests retried with the same key return the original response. Mismatched bodies return 422; in-flight duplicates return 409. Keys are scoped per merchant + endpoint and expire after 24 hours. On 5xx, retry with the same key: a retry cannot create a duplicate charge.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/payments/auth" \ -H "Content-Type: application/json" \ -d '{ "amount": 7200, "cardNumber": "5555555555554444", "cardExpiration": "1133", "cardCvv": "456", "cardholderName": "Jordan Example", "cardholderEmail": "jordan@example.com", "cardholderPhone": "+14155550101", "cardholderBillingAddress": "100 Example Street", "cardholderBillingZipcode": "94105", "cardholderBillingCity": "Springfield", "cardholderBillingState": "CA" }'{ "paymentId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b", "status": "AUTHORIZED", "amount": 7200, "cardNumber": "555555xxxxxxxx4444", "cardExpiration": "1133", "cardholderName": "Jordan Example", "customerId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9bcc", "paymentMethodId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9bff", "nextAction": { "kind": "REDIRECT", "url": "https://pay.gateway.example/3ds/redirect/…", "method": "GET", "data": { "property1": "string", "property2": "string" }, "fallbackUrl": "string" }}{ "statusCode": 400, "message": "Some fields are invalid, please check the errors", "fieldErrors": { "amount": [ "amount must not be less than 1", "amount must be an integer number" ], "cardNumber": [ "cardNumber must be 12-19 digits with no spaces or separators" ] }}{ "statusCode": 401, "error": "Unauthorized", "message": "Invalid credentials"}{ "statusCode": 403, "error": "Forbidden", "message": "Merchant account can only process refunds and voids"}{ "statusCode": 404, "error": "Not Found", "message": "Payment not found: 01928e1c-2a4d-7c8e-8b1a-1234567890ab"}{ "statusCode": 429, "message": "Duplicate purchase blocked", "code": "VELOCITY_LIMIT"}Errors and conventions
Every request convention, HTTP status code, response body shape and retry rule of the merchant API.
Authorize and capture a payment POST
Authorizes and captures the requested amount in a single operation. The request can optionally save the payment method for future use. When the issuer requires 3-D Secure, the call returns 201 with status REQUIRES_ACTION and a nextAction redirect for the customer; the final state settles asynchronously (poll GET /payments/:id).