Coloca una reserva de fondos

POST

payment

authorization

curl -X POST https://api.therius.io/v1/payment/authorization \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "orderCode": "ORDER-20240101-002",
    "amount": { "currency": "USD", "value": 9900, "exponent": 2 },
    "card": {
      "cardData": {
        "cardNumber": "4111111111111111",
        "cardholderName": "Ada Lovelace",
        "expiryMonth": "12",
        "expiryYear": "2030",
        "cvv": "123"
      }
    }
  }'

{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "authorized",
  "paymentCode": "PC-1234567890",
  "orderCode": "ORDER-20240101-002",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 9900, "exponent": 2 },
  "card": {
    "cardData": { "brand": "visa", "cardNumber": "411111****1111", "type": "credit" },
    "networkTransactionId": "txn_def456"
  }
}

POST /payment/authorization reserva fondos en la cuenta del titular de la tarjeta sin liquidarlos. La retención de autorización suele ser válida durante 7 días, aunque la ventana exacta depende del adquirente y de la red de tarjetas. Llama a Capture para liquidar los fondos cuando estés listo para cumplir, o a Cancel para liberar la retención si no puedes cumplir el pedido. Consulta la referencia de Purchase para la descripción completa de los campos de card/shopper/respuesta — la forma de la solicitud y la respuesta es idéntica, solo cambia el resultado (una retención en vez de un cargo liquidado).

curl -X POST https://api.therius.io/v1/payment/authorization \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "orderCode": "ORDER-20240101-002",
    "amount": { "currency": "USD", "value": 9900, "exponent": 2 },
    "card": {
      "cardData": {
        "cardNumber": "4111111111111111",
        "cardholderName": "Ada Lovelace",
        "expiryMonth": "12",
        "expiryYear": "2030",
        "cvv": "123"
      }
    }
  }'

{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "authorized",
  "paymentCode": "PC-1234567890",
  "orderCode": "ORDER-20240101-002",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 9900, "exponent": 2 },
  "card": {
    "cardData": { "brand": "visa", "cardNumber": "411111****1111", "type": "credit" },
    "networkTransactionId": "txn_def456"
  }
}

Se soporta la captura parcial. Cuando llamas a Capture, puedes pasar un amount menor o igual al monto autorizado. Por ejemplo, si autorizaste $99.00 pero solo enviaste $75.00 en bienes, captura $75.00 y la retención restante se libera automáticamente.

Las retenciones de autorización expiran — normalmente después de 7 días, pero esto varía según el adquirente y la red de tarjetas. Si no llamas a Capture antes del vencimiento, la retención se libera y necesitarás volver a autorizar. Monitorea la antigüedad de la retención en tu sistema de gestión de pedidos.

Autorizaciones

Authorization

string

header

requerido

Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).

Encabezados

Idempotency-Key

string<uuid>

A UUID you generate per operation. Required in production. Retrying with the same key returns the original response.

Cuerpo

application/json

merchantCode

string

requerido

Your merchant account identifier. Validated against the Bearer key's merchant; required if the key maps to more than one merchant account.

orderCode

string

requerido

Your internal order reference. Must be unique per merchant — use it to correlate Therius payments with your own records.

amount

object

requerido

Show child attributes

paymentMethod

object

requerido

The payment instrument/method to charge. Always required.

Show child attributes

Ejemplo:

{
  "type": "pix",
  "pix": {
    "payerName": "Ada Lovelace",
    "payerEmail": "ada@example.com",
    "payerTaxId": "12345678909"
  }
}

shopper

object

Shopper information. Required when tokenizing a card (card.<instrument>.tokenize: true).

Show child attributes

webhookUrl

string

Per-payment webhook URL override (HTTPS only). Therius posts the final payment status here when it changes asynchronously.

connectionId

string

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.

connectionCode

string

Pin this payment to a specific gateway connection. Omit to use your routing rules.

ipAddress

string

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.

metadata

object

Arbitrary string key/value pairs, echoed back in webhook payloads.

Show child attributes

lineItems

object[]

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.

Show child attributes

billingAddress

object

Shared, request-level billing address used by APM methods that need one (e.g. Boleto, Efecty).

Show child attributes

deliveryAddress

object

Shared, request-level delivery address used by BNPL providers for fraud scoring.

Show child attributes

commercialData

object

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.

Show child attributes

Respuesta

200 - application/json

Authorization result

string<uuid>

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.

Ejemplo:

"9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e"

status

enum<string>

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.

Opciones disponibles:

captured,

authorized,

declined,

pending_3ds,

pending_action,

failed,

canceled,

refunded

paymentCode

string

Therius receipt ID, for reconciliation, support and Inquiry. NOT the handle for capture/refund/cancel — use id for that.

Ejemplo:

"PC-1234567890"

orderCode

string

Your orderCode, echoed back.

merchantCode

string

Your merchantCode, echoed back.

autorizationCode

string

Issuer authorization code on an approved payment. The field name is misspelled on the wire (no h) - this is intentional and stable.

paymentMethod

string

Payment method used, e.g. card, pix, ach.

connectionCode

string

Code of the connection that processed the payment. Omitted for payfac merchants.

connectionName

string

Display name of the gateway connection that processed the payment.

amount

object

Show child attributes

card

object

Card details from the response: masked PAN, brand, type, and the network transaction/reference IDs to cite on future MIT charges.

apm

object

Alternative-payment-method details (redirect URL, QR code, barcode) when paymentMethod is an APM.

token

object

Present when the card was tokenized (tokenize: true).

Show child attributes

actionRequired

object

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().

Show child attributes

refusalCode

object

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.

Show child attributes

curl -X POST https://api.therius.io/v1/payment/authorization \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "orderCode": "ORDER-20240101-002",
    "amount": { "currency": "USD", "value": 9900, "exponent": 2 },
    "card": {
      "cardData": {
        "cardNumber": "4111111111111111",
        "cardholderName": "Ada Lovelace",
        "expiryMonth": "12",
        "expiryYear": "2030",
        "cvv": "123"
      }
    }
  }'

{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "authorized",
  "paymentCode": "PC-1234567890",
  "orderCode": "ORDER-20240101-002",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 9900, "exponent": 2 },
  "card": {
    "cardData": { "brand": "visa", "cardNumber": "411111****1111", "type": "credit" },
    "networkTransactionId": "txn_def456"
  }
}

Pagos

Enlaces de pago

Tokenización

Suscripciones

Subscription Plans

Sesión del SDK

Coloca una reserva de fondos

Autorizaciones

Encabezados

Cuerpo

Respuesta