Crear un link de pago (API Recaudación)

curl --request POST \
  --url https://api.tupana.ai/v2/payment-requests/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 50000,
  "currency": "CLP",
  "recipient_id": "ment_4829301923847",
  "redirect_url": "https://tuapp.com/confirmation",
  "target_dte_type": 39,
  "dte_recipient": {
    "rut": "11111111-1",
    "name": "Juan Soto",
    "email": "juan@ejemplo.com"
  },
  "items": [
    {
      "description": "Sesión de psicoterapia",
      "quantity": 1,
      "unit_price": 50000
    }
  ],
  "expires_in_minutes": 30,
  "skip_portal": false,
  "auto_issue": true,
  "external_id": "booking_abc123",
  "metadata": {
    "patient_name": "Juan Soto",
    "appointment_start_time": "2026-04-15T10:00:00-04:00"
  }
}
'

{
  "payment_request_id": "pare_4829301923847",
  "status": "pending",
  "payment_url": "https://www.tupana.ai/pagos/tok_xyz",
  "expires_at": "2026-04-06T12:30:00Z",
  "created_at": "2026-04-06T12:00:00Z",
  "amount": 50000,
  "target_dte_type": "39",
  "auto_issue": true,
  "external_id": "booking_abc123",
  "metadata": {},
  "issued_document_id": "docu_9182736455123",
  "document_ids": [
    "docu_9182736455123",
    "docu_9182736455124"
  ]
}

POST

payment-requests

curl --request POST \
  --url https://api.tupana.ai/v2/payment-requests/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 50000,
  "currency": "CLP",
  "recipient_id": "ment_4829301923847",
  "redirect_url": "https://tuapp.com/confirmation",
  "target_dte_type": 39,
  "dte_recipient": {
    "rut": "11111111-1",
    "name": "Juan Soto",
    "email": "juan@ejemplo.com"
  },
  "items": [
    {
      "description": "Sesión de psicoterapia",
      "quantity": 1,
      "unit_price": 50000
    }
  ],
  "expires_in_minutes": 30,
  "skip_portal": false,
  "auto_issue": true,
  "external_id": "booking_abc123",
  "metadata": {
    "patient_name": "Juan Soto",
    "appointment_start_time": "2026-04-15T10:00:00-04:00"
  }
}
'

{
  "payment_request_id": "pare_4829301923847",
  "status": "pending",
  "payment_url": "https://www.tupana.ai/pagos/tok_xyz",
  "expires_at": "2026-04-06T12:30:00Z",
  "created_at": "2026-04-06T12:00:00Z",
  "amount": 50000,
  "target_dte_type": "39",
  "auto_issue": true,
  "external_id": "booking_abc123",
  "metadata": {},
  "issued_document_id": "docu_9182736455123",
  "document_ids": [
    "docu_9182736455123",
    "docu_9182736455124"
  ]
}

¿Para qué se usa?

Crea una sesión de pago y retorna la payment_url a la que debes redirigir al usuario para que complete el pago. Tupana se encarga de procesar el pago, emitir el DTE (si corresponde) y notificarte vía webhook.

Qué hace

Crea una sesión de cobro en estado pending.
Retorna una URL de pago única con tiempo de expiración.
Al confirmarse el pago:
- Modo emisión (default): Tupana emite automáticamente el DTE si auto_issue=true.
- Modo cobro directo (con document_ids): los documentos referenciados se marcan como pagados; no hay emisión de DTE.

Modos de uso

Modo	Cuándo usarlo	Campos requeridos
Emisión	Cobras un servicio nuevo y necesitas emitir un DTE al confirmarse el pago	`amount`, `target_dte_type`, `dte_recipient`, `items`
Cobro directo	Quieres cobrar uno o más DTEs ya emitidos	`document_ids`

Los modos son mutuamente excluyentes: si envías document_ids, no puedes incluir amount, target_dte_type, dte_recipient ni items (Tupana retorna CANNOT_MIX_MODES).

Ejemplo: modo cobro directo

{
  "recipient_id": "ment_4829301923847",
  "redirect_url": "https://tuapp.com/confirmation",
  "document_ids": ["docu_9182736455123", "docu_9182736455124"],
  "expires_in_minutes": 30,
  "external_id": "collection_session_001",
  "metadata": {
    "campaign": "cobranza-abril"
  }
}

Reglas de validación en este modo:

Todos los document_ids deben pertenecer al recipient_id (su sender debe coincidir).
Todos deben compartir el mismo pagador (receiver) — un solo cobro = un solo pagador.
Solo se aceptan tipos de DTE cobrables: 33, 34, 39, 41, 80, 110.
Ninguno puede estar ya pagado.
El monto del cobro se calcula automáticamente como la suma de los amount_with_iva de los documentos.
Si usas una API key de sandbox, el folio de cada documento debe empezar con SANDBOX. Esto evita que cobres documentos reales con una key de prueba — si la regla no se cumple, el endpoint retorna DOCUMENT_NOT_SANDBOX.

En modo cobro directo no hay emisión posterior, por lo que PATCH /v2/payment-requests/{id}/ con status=issued retorna NOT_APPLICABLE.

Ejemplos de uso

Cobro de una sesión de salud mental: Un paciente agenda una consulta y paga antes de la atención.
Pago de servicio: Un cliente de una plataforma de servicios paga por una prestación.
Cobro recurrente manual: Tu plataforma crea sesiones de cobro para cada período.

Consideraciones importantes

Idempotencia con `external_id`

Si envías el mismo external_id en dos requests distintos, Tupana retorna la sesión original sin crear una nueva. Usa esto para evitar sesiones duplicadas si tu request se reintenta.

Checkout con o sin portal

El parámetro skip_portal controla la experiencia de pago:

Valor	Comportamiento
`false` (default)	El usuario ve una pantalla de Tupana con el detalle del cobro antes de pagar.
`true`	El usuario es redirigido directo a Transbank. Útil cuando el contexto del cobro ya es claro en tu interfaz.

Redirect post-pago

Si enviaste redirect_url, Tupana redirige al usuario a esa URL después del pago con parámetros de estado:

# Pago exitoso
https://tuapp.com/confirmation?payment_request_id=pare_4829301923847&status=paid

# Pago fallido
https://tuapp.com/confirmation?payment_request_id=pare_4829301923847&status=failed&error_code=CARD_DECLINED

# Sesión vencida
https://tuapp.com/confirmation?payment_request_id=pare_4829301923847&status=expired

No uses los parámetros del redirect como fuente de verdad del estado del pago. Un usuario podría modificarlos en el browser. Siempre verifica el estado real vía el webhook recibido o consultando GET /v2/payment-requests/{id}/.

Emisión automática de DTE (`auto_issue`)

Por defecto (auto_issue=true), Tupana emite el DTE automáticamente al confirmarse el pago. Si necesitas controlar el momento de la emisión, envía auto_issue=false y emite el DTE cuando lo necesites con PATCH /v2/payment-requests/{id}/ enviando {"status": "issued"}. Esto es útil cuando quieres validar datos adicionales antes de emitir la boleta o factura.

Tipos de DTE soportados

`target_dte_type`	Documento emitido
`39`	Boleta afecta electrónica
`41`	Boleta exenta electrónica
`33`	Factura afecta electrónica

El destinatario debe estar habilitado para emitir ese tipo de documento en Tupana. Si no lo está, la sesión será rechazada al crearla.

Authorizations

Authorization

string

header

required

API Key para autenticación. Formato: Api-Key YOUR-API-KEY

Body

application/json

La sesión de cobro soporta dos modos:

Modo emisión (default): Tupana cobra y emite un DTE nuevo. Requiere amount, target_dte_type, dte_recipient y items.
Modo cobro directo: cobra documentos ya existentes. Requiere document_ids y rechaza amount, target_dte_type, dte_recipient e items.

recipient_id

string

required

ID de la empresa que cobra y emite (ment_…): el company_id que devuelve GET /v2/connections/. Debe tener cuenta bancaria registrada. En modo cobro directo, todos los document_ids deben pertenecer a este destinatario.

Example:

"ment_4829301923847"

amount

integer

Monto en CLP, sin decimales. Requerido en modo emisión. No permitido si envías document_ids — el monto se calcula sumando los amount_with_iva de los documentos.

Example:

50000

currency

enum<string>

default:CLP

Moneda. Siempre CLP. Si se omite, se usa CLP por defecto.

Available options:

CLP

redirect_url

string<uri>

URL a la que Tupana redirige al usuario después del pago. Si se omite, el usuario permanece en el portal de pago.

Example:

"https://tuapp.com/confirmation"

target_dte_type

enum<integer>

Tipo de DTE a emitir al confirmarse el pago. 39 = boleta afecta, 41 = boleta exenta, 33 = factura afecta. Requerido en modo emisión. No permitido si envías document_ids.

Available options:

33,

39,

41

Example:

39

dte_recipient

object

Show child attributes

items

object[]

Ítems del DTE. La suma de quantity × unit_price debe coincidir con amount. Requerido en modo emisión. No permitido si envías document_ids.

Show child attributes

document_ids

string[]

IDs de documentos existentes a cobrar (modo cobro directo). Todos deben pertenecer al recipient_id, compartir el mismo receptor (pagador), ser de tipo cobrable (33, 34, 39, 41, 80, 110) y no estar pagados. Si envías este campo, omite amount, target_dte_type, dte_recipient e items.

Cuando uses una API key de sandbox, cada documento debe tener un folio que comience con SANDBOX (de lo contrario el endpoint retorna DOCUMENT_NOT_SANDBOX).

Minimum array length: 1

Example:

["docu_9182736455123", "docu_9182736455124"]

expires_in_minutes

integer

default:30

Minutos hasta que vence la sesión. Por defecto: 30.

Example:

30

skip_portal

boolean

default:false

Si true, redirige directo a Transbank sin mostrar la pantalla de Tupana. Por defecto: false.

auto_issue

boolean

default:true

Si true (default), Tupana emite el DTE automáticamente al confirmarse el pago. Si false, debes emitirlo manualmente con PATCH /v2/payment-requests/{id}/ enviando {"status": "issued"}. Solo aplica en modo emisión; ignorado en modo cobro directo (no hay DTE que emitir).

external_id

string

ID propio para idempotencia. Si ya existe una sesión con ese external_id para tu API key, se retorna la sesión original con HTTP 200.

Example:

"booking_abc123"

metadata

object

Datos adicionales de libre formato. Tupana los guarda y devuelve en webhooks y en el GET.

Response

Sesión existente retornada (idempotencia por external_id)

payment_request_id

string

ID único de la sesión de cobro (pare_…).

Example:

"pare_4829301923847"

status

enum<string>

Available options:

pending,

paid,

issued,

failed,

expired,

refunded

Example:

"pending"

payment_url

string<uri>

URL a la que debes redirigir al usuario para que complete el pago.

Example:

"https://www.tupana.ai/pagos/tok_xyz"

expires_at

string<date-time>

Fecha y hora en que vence la sesión (UTC).

Example:

"2026-04-06T12:30:00Z"

created_at

string<date-time>

Fecha y hora de creación de la sesión (UTC).

Example:

"2026-04-06T12:00:00Z"

amount

number

Monto del cobro en CLP.

Example:

50000

target_dte_type

string | null

Tipo de DTE que se emitirá al pagarse. null en modo cobro directo (no hay DTE a emitir).

Example:

"39"

auto_issue

boolean | null

Si el DTE se emite automáticamente al confirmarse el pago. null en modo cobro directo.

Example:

true

external_id

string | null

Tu ID propio para esta sesión.

Example:

"booking_abc123"

metadata

object

Datos adicionales que enviaste al crear la sesión.

issued_document_id

string | null

ID del DTE emitido. null mientras la sesión no haya emitido el DTE. Siempre null en modo cobro directo.

Example:

"docu_9182736455123"

document_ids

string[]

IDs de los documentos que esta sesión cobra. Lista vacía en modo emisión (donde el DTE se emite al pagarse).

Example:

["docu_9182736455123", "docu_9182736455124"]

Introducción

Cuenta Bancaria

Medios de pago

Liquidaciones

Cobros

Webhooks

Referencia

Errores

Crear un link de pago (API Recaudación)

¿Para qué se usa?

Qué hace

Modos de uso

Ejemplo: modo cobro directo

Ejemplos de uso

Consideraciones importantes

Idempotencia con `external_id`

Checkout con o sin portal

Redirect post-pago

Emisión automática de DTE (`auto_issue`)

Tipos de DTE soportados

Authorizations

Body

Response

​¿Para qué se usa?

​Qué hace

​Modos de uso

​Ejemplo: modo cobro directo

​Ejemplos de uso

​Consideraciones importantes

​Idempotencia con external_id

​Checkout con o sin portal

​Redirect post-pago

​Emisión automática de DTE (auto_issue)

​Tipos de DTE soportados

Authorizations

Body

Response

¿Para qué se usa?

Qué hace

Modos de uso

Ejemplo: modo cobro directo

Ejemplos de uso

Consideraciones importantes

Idempotencia con `external_id`

Checkout con o sin portal

Redirect post-pago

Emisión automática de DTE (`auto_issue`)

Tipos de DTE soportados