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.
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 (2xx and 4xx are cached). Mismatched bodies return 422; in-flight duplicates return 409. Keys are scoped per merchant + endpoint and expire after 24 hours. NOTE: on 5xx the idempotency record is discarded — retry with the same key (provider-side dedup protects against duplicate execution).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
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": "Mary Jo Verke", "cardholderEmail": "maryoverke@gmail.com", "cardholderPhone": "+14155550101", "cardholderBillingAddress": "4944 HOLLYCREST WAY", "cardholderBillingZipcode": "95628", "cardholderBillingCity": "Fair Oaks", "cardholderBillingState": "CA" }'{ "paymentId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b", "status": "AUTHORIZED", "amount": 7200, "cardNumber": "555555xxxxxxxx4444", "cardExpiration": "1133", "cardholderName": "Mary Jo Verke", "customerId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9bcc", "paymentMethodId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9bff"}{ "statusCode": 400, "error": "Bad Request", "message": [ "amount must not be less than 100" ]}{ "statusCode": 401, "error": "Unauthorized", "message": "Missing Authorization header"}{ "statusCode": 404, "error": "Not Found", "message": "Merchant not found: 01928e1c-2a4d-7c8e-8b1a-1234567890ab"}