Cobra una tarjeta en un solo paso

POST

payment

purchase

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

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

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

El 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

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

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

Respuesta rechazada

{
  "status": "declined",
  "paymentCode": "PC-9876543210",
  "orderCode": "ORDER-20240101-002",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 4999, "exponent": 2 },
  "refusalCode": {
    "reason": "Insufficient funds",
    "reasonCode": "INSUFFICIENT_FUNDS",
    "recoveryAction": "switch_method"
  }
}

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.

Si 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

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

card

Raw card (PCI DSS) · object

Card input for one-off payments: exactly one instrument (cardData / nonceData / tokenData) plus optional stored-credential and installment modifiers.

Raw card (PCI DSS)
SDK nonce
Vault token

Show child attributes

apm

object

Alternative payment method data — use instead of card for APMs such as Pix, ACH or Boleto. Structure varies by method.

paymentMethod

string

Payment method code. Omit for card payments; for APMs pass the code, e.g. pix, ach, boleto.

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.

connectionCode

string

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

ipAddress

string

Cardholder's IP address, passed to fraud scoring when available.

metadata

object

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

Show child attributes

Respuesta

200 - application/json

Payment processed

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; cancelled - authorization voided; refunded - captured funds returned.

Opciones disponibles:

captured,

authorized,

declined,

pending_3ds,

pending_action,

failed,

cancelled,

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 gateway connection that processed the payment.

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.

Show child attributes

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

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

Pagos

Tokenización

Suscripciones

Planes

Sesión del SDK

Cobra una tarjeta en un solo paso

Ejemplos

Cobrar una tarjeta

Autorizaciones

Encabezados

Cuerpo

Respuesta

​Ejemplos

​Cobrar una tarjeta

Autorizaciones

Encabezados

Cuerpo

Respuesta

Ejemplos

Cobrar una tarjeta