Cobra una tarjeta en un solo paso
Autoriza y captura un pago en una sola solicitud. Úsalo para bienes digitales o cualquier pedido que cumplas de inmediato.
POST /payment/purchase autoriza y captura fondos en un solo ida y vuelta. Úsalo cuando puedes cumplir el pedido de inmediato — bienes digitales, suscripciones SaaS o retail con stock. Para bienes físicos que se envían más tarde, considera Authorize + Capture para retener fondos hasta el cumplimiento sin liquidar antes de tiempo.
La forma completa de la solicitud y la respuesta — cada campo de card/shopper/amount, los valores de status y el detalle de refusalCode/actionRequired/token — está documentada en los paneles de parámetros y respuesta de arriba (generados a partir de la especificación de la API).
id de la respuesta es el UUID de pago de Therius — guárdalo, es el identificador para una llamada posterior a Refund o Cancel or Refund. paymentCode (p. ej. "PC-1234567890") es una referencia separada para conciliación, soporte e Inquiry — no se acepta para reembolso/cancelación.Ejemplos
Cobrar una tarjeta
amount.value siempre está en unidades menores. 1999 = $19.99 para USD (exponent 2). 5000 = ¥5000 para JPY (exponent 0). Usa siempre el campo exponent para determinar la posición decimal.status es "pending_3ds", redirige al titular de la tarjeta a actionRequired.url para completar el desafío 3D Secure. Una vez que termina, llama a POST /payment/resume con el sessionId de la respuesta pending_3ds para continuar. Si usas el SDK JS de Therius, llama a sdk.handleAction(result.actionRequired) — maneja el redirect y el resume automáticamente.Autorizaciones
Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).
Encabezados
A UUID you generate per operation. Required in production. Retrying with the same key returns the original response.
Cuerpo
Your merchant account identifier. Validated against the Bearer key's merchant; required if the key maps to more than one merchant account.
Your internal order reference. Must be unique per merchant — use it to correlate Therius payments with your own records.
The payment instrument/method to charge. Always required.
Shopper information. Required when tokenizing a card (card.<instrument>.tokenize: true).
Per-payment webhook URL override (HTTPS only). Therius posts the final payment status here when it changes asynchronously.
Pin this payment to a specific connection by its opaque id (as returned by POST /payment/bank-options). Takes precedence over connectionCode. Omit to use your routing rules.
Pin this payment to a specific gateway connection. Omit to use your routing rules.
Cardholder's IP address, used for fraud scoring and by some providers. If you omit it, Therius uses the address of the connecting client, which is your server when you call from a backend, so send the shopper's real IP in that case.
Arbitrary string key/value pairs, echoed back in webhook payloads.
Shared, request-level line items (description, quantity, line total). On a card payment they also supply the Level 3 breakdown when commercialData is sent. Used by BNPL providers for credit scoring and generic across every Adyen bank-redirect method, not method-specific -- a sibling of paymentMethod, never nested inside it.
Shared, request-level billing address used by APM methods that need one (e.g. Boleto, Efecty).
Shared, request-level delivery address used by BNPL providers for fraud scoring.
Opt in to Level 2/3 card data (customer reference, tax, freight, ship-to and, with lineItems that carry unitAmount, the per-line breakdown). Card payments only. See the Level 2 and 3 card data guide.
Respuesta
Payment processed
The Therius payment id. Returned by POST /payment/authorization and POST /payment/purchase; use it as the {id} path segment for capture, refund, cancel and cancel_or_refund.
"9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e"
captured - funds settled; authorized - funds reserved, call capture to settle; declined - issuer declined, see refusalCode; pending_3ds - a 3DS challenge is required, see actionRequired; pending_action - an external action (redirect, voucher) is required, see actionRequired; failed - processing error unrelated to the issuer; canceled - authorization voided; refunded - captured funds returned.
captured, authorized, declined, pending_3ds, pending_action, failed, canceled, refunded Therius receipt ID, for reconciliation, support and Inquiry. NOT the handle for capture/refund/cancel — use id for that.
"PC-1234567890"
Your orderCode, echoed back.
Your merchantCode, echoed back.
Issuer authorization code on an approved payment. The field name is misspelled on the wire (no h) - this is intentional and stable.
Payment method used, e.g. card, pix, ach.
Code of the connection that processed the payment. Omitted for payfac merchants.
Display name of the gateway connection that processed the payment.
Card details from the response: masked PAN, brand, type, and the network transaction/reference IDs to cite on future MIT charges.
Alternative-payment-method details (redirect URL, QR code, barcode) when paymentMethod is an APM.
Present when the card was tokenized (tokenize: true).
Present when status is pending_3ds or pending_action. Describes what the cardholder must do next — with the Therius JS SDK, pass the whole object to sdk.handleAction().
Present when status is declined. See the Declined Payments concept page for the full code table and how to react to each recoveryAction. For alternative payment methods reasonCode is an APM_* code.