Crear un enlace de pago

POST

payment-link

curl -X POST https://api.therius.io/v1/payment-link \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "type": "one-time",
    "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
    "title": "Invoice 4821",
    "reference": "INV-4821",
    "customerEmail": "ana@example.com",
    "returnUrl": "https://shop.example.com/thanks",
    "expiresInDays": 14
  }'

{
  "id": "5b1f0a52-3c0e-4a52-9d57-0c1d7e9f2a10",
  "url": "https://pay.therius.io/pay/Zk3x...",
  "type": "one-time",
  "status": "active",
  "amountMode": "fixed",
  "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
  "title": "Invoice 4821",
  "reference": "INV-4821",
  "customerEmail": "ana@example.com",
  "returnUrl": "https://shop.example.com/thanks",
  "saveCardEnabled": false,
  "reusable": false,
  "usesCount": 0,
  "environment": "production",
  "expiresAt": "2026-10-28T12:00:00Z",
  "createdAt": "2026-10-14T12:00:00Z"
}

POST /payment-link crea una página de checkout alojada que puedes enviar al pagador por correo, chat o código QR, sin integrar el SDK. La respuesta contiene la url para compartir.

Tipos de enlace

Pago único, monto fijo — defines amount (amountMode: "fixed", el valor por defecto). Úsalo para facturas y boletos.
Pago único, monto ingresado por el pagador — define amountMode: "customer_entered" y una currency. El pagador escribe el monto, acotado opcionalmente por amountMin y amountMax (unidades menores).
Suscripción — define type: "subscription" y un subscriptionPlanId. El plan fija el precio. Si omites subscriptionPlanId, el pagador elige entre tus planes activos. No envíes amount en enlaces de suscripción.

Enlaces de un solo uso y reutilizables

Por defecto un enlace es de un solo uso: pasa a used tras el primer pago exitoso. Los intentos fallidos no lo consumen, así que el pagador puede reintentar. Define reusable: true para aceptar muchos pagos. Agrega maxUses para limitar la cantidad de pagos exitosos; el enlace pasa a used al alcanzar el tope. Sin maxUses, un enlace reutilizable sigue active hasta que expira o lo cancelas. maxUses requiere reusable: true, y los enlaces de suscripción no pueden ser reutilizables.

Entorno y vencimiento

Un enlace toma el entorno de la clave que lo creó: las claves prv_sandbox_ crean enlaces de sandbox y las prv_production_ crean enlaces de producción. Los enlaces vencen a los 7 días salvo que definas expiresInDays (1–365) o expiresAt (YYYY-MM-DD, fin de ese día en UTC).

Referencia y URL de retorno

reference es tu propio identificador (por ejemplo, un número de factura). Se convierte en el orderCode del pago resultante. returnUrl debe ser una URL https (en sandbox se acepta http).

Ejemplo

curl -X POST https://api.therius.io/v1/payment-link \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "type": "one-time",
    "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
    "title": "Invoice 4821",
    "reference": "INV-4821",
    "customerEmail": "ana@example.com",
    "returnUrl": "https://shop.example.com/thanks",
    "expiresInDays": 14
  }'

{
  "id": "5b1f0a52-3c0e-4a52-9d57-0c1d7e9f2a10",
  "url": "https://pay.therius.io/pay/Zk3x...",
  "type": "one-time",
  "status": "active",
  "amountMode": "fixed",
  "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
  "title": "Invoice 4821",
  "reference": "INV-4821",
  "customerEmail": "ana@example.com",
  "returnUrl": "https://shop.example.com/thanks",
  "saveCardEnabled": false,
  "reusable": false,
  "usesCount": 0,
  "environment": "production",
  "expiresAt": "2026-10-28T12:00:00Z",
  "createdAt": "2026-10-14T12:00:00Z"
}

Envía un encabezado Idempotency-Key para que una solicitud reintentada devuelva el enlace original en lugar de crear uno segundo. Consulta Idempotencia.

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

type

enum<string>

requerido

Opciones disponibles:

one-time,

subscription

merchantCode

string

Your merchant account identifier. Required if the key maps to more than one merchant account.

amountMode

enum<string>

predeterminado:fixed

One-time links only.

Opciones disponibles:

fixed,

customer_entered

amount

object

Required for one-time links. value is required when amountMode is fixed; for customer_entered only currency is needed. Not allowed on subscription links.

Show child attributes

amountMin

integer<int64>

customer_entered only. Minimum amount the payer may enter, minor units.

amountMax

integer<int64>

customer_entered only. Maximum amount the payer may enter, minor units.

subscriptionPlanId

integer<int64>

Subscription links only. Omit to let the payer choose among your active plans.

checkoutConfigId

string<uuid>

Checkout Builder configuration to style the page.

title

string

Maximum string length: 255

description

string

Maximum string length: 2000

reference

string

Your own reference (invoice number, PNR). It becomes the orderCode of the resulting payment.

Maximum string length: 128

customerEmail

string

customerName

string

returnUrl

string<uri>

Where to send the payer after paying. Must be https (sandbox also allows http).

expiresInDays

integer

predeterminado:7

Rango requerido: 1 <= x <= 365

expiresAt

string

Expiry date, YYYY-MM-DD (end of that day, UTC). Takes precedence over expiresInDays.

saveCardEnabled

boolean

predeterminado:false

reusable

boolean

predeterminado:false

Accept many payments instead of one. One-time links only.

maxUses

integer

Cap on successful payments for a reusable link. Requires reusable: true.

Rango requerido: x >= 1

Respuesta

Payment link created

string<uuid>

url

string<uri>

The hosted checkout URL to share with the payer.

type

enum<string>

Opciones disponibles:

one-time,

subscription

status

enum<string>

used once a single-use link takes its first successful payment, or a reusable link reaches maxUses.

Opciones disponibles:

active,

used,

expired,

cancelled

amountMode

enum<string>

Opciones disponibles:

fixed,

customer_entered

amount

object

Absent on subscription links. For customer_entered links only currency and exponent are set.

Show child attributes

amountMin

integer<int64>

Minimum payer-entered amount, minor units.

amountMax

integer<int64>

Maximum payer-entered amount, minor units.

subscriptionPlanId

integer<int64>

checkoutConfigId

string<uuid>

title

string

description

string

reference

string

customerEmail

string

customerName

string

returnUrl

string<uri>

saveCardEnabled

boolean

reusable

boolean

maxUses

integer

usesCount

integer

Number of successful payments taken through this link.

environment

enum<string>

Opciones disponibles:

production,

sandbox

expiresAt

string<date-time>

usedAt

string<date-time>

createdAt

string<date-time>

curl -X POST https://api.therius.io/v1/payment-link \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "type": "one-time",
    "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
    "title": "Invoice 4821",
    "reference": "INV-4821",
    "customerEmail": "ana@example.com",
    "returnUrl": "https://shop.example.com/thanks",
    "expiresInDays": 14
  }'

{
  "id": "5b1f0a52-3c0e-4a52-9d57-0c1d7e9f2a10",
  "url": "https://pay.therius.io/pay/Zk3x...",
  "type": "one-time",
  "status": "active",
  "amountMode": "fixed",
  "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
  "title": "Invoice 4821",
  "reference": "INV-4821",
  "customerEmail": "ana@example.com",
  "returnUrl": "https://shop.example.com/thanks",
  "saveCardEnabled": false,
  "reusable": false,
  "usesCount": 0,
  "environment": "production",
  "expiresAt": "2026-10-28T12:00:00Z",
  "createdAt": "2026-10-14T12:00:00Z"
}

Pagos

Enlaces de pago

Tokenización

Suscripciones

Subscription Plans

Sesión del SDK

Crear un enlace de pago

Tipos de enlace

Enlaces de un solo uso y reutilizables

Entorno y vencimiento

Referencia y URL de retorno

Ejemplo

Autorizaciones

Encabezados

Cuerpo

Respuesta

​Tipos de enlace

​Enlaces de un solo uso y reutilizables

​Entorno y vencimiento

​Referencia y URL de retorno

​Ejemplo

Autorizaciones

Encabezados

Cuerpo

Respuesta

Tipos de enlace

Enlaces de un solo uso y reutilizables

Entorno y vencimiento

Referencia y URL de retorno

Ejemplo