Skip to main content
POST
/
api
/
payment-requests
Crear sesión de cobro
curl --request POST \
  --url https://api.tupana.ai/api/payment-requests/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 50000,
  "currency": "CLP",
  "recipient_id": "me_xyz789",
  "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,
  "external_id": "booking_abc123",
  "metadata": {
    "patient_name": "Juan Soto",
    "appointment_start_time": "2026-04-15T10:00:00-04:00"
  }
}
'
{
  "payment_request_id": "pr_abc123",
  "status": "pending",
  "payment_url": "https://pay.tupana.com/pay/tok_xyz",
  "expires_at": "2026-04-06T12:30:00Z"
}

​
¿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. Tu Pana se encarga de procesar el pago, emitir el DTE 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, Tu Pana emite automáticamente el DTE del tipo indicado en target_dte_type.

​
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, Tu Pana 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:
ValorComportamiento
false (default)El usuario ve una pantalla de Tu Pana con el detalle del cobro antes de pagar.
trueEl usuario es redirigido directo a Transbank. Útil cuando el contexto del cobro ya es claro en tu interfaz.

​
Redirect post-pago

Después del pago (exitoso, fallido o expirado), Tu Pana redirige al usuario a tu redirect_url con parámetros de estado: 
# Pago exitoso
https://tuapp.com/confirmation?payment_request_id=pr_abc123&status=paid

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

# Sesión vencida
https://tuapp.com/confirmation?payment_request_id=pr_abc123&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 /api/payment-requests/{id}/.

​
Tipos de DTE soportados

target_dte_typeDocumento emitido
39Boleta afecta electrónica
41Boleta exenta electrónica
33Factura afecta electrónica
El destinatario debe estar habilitado para emitir ese tipo de documento en Tu Pana. 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
​
amount
integer
required

Monto en CLP, sin decimales.

Example:

50000

​
currency
enum<string>
required

Moneda. Siempre CLP.

Available options:
CLP
​
recipient_id
string
required

ID del destinatario en Tu Pana. Debe tener cuenta bancaria verificada.

Example:

"me_xyz789"

​
redirect_url
string<uri>
required

URL a la que Tu Pana redirige al usuario después del pago.

Example:

"https://tuapp.com/confirmation"

​
target_dte_type
enum<integer>
required

Tipo de DTE a emitir al confirmarse el pago. 39 = boleta afecta, 41 = boleta exenta, 33 = factura afecta.

Available options:
33,
39,
41
Example:

39

​
dte_recipient
object
required
​
items
object[]
required

Ítems del DTE. La suma de quantity × unit_price debe coincidir con amount.

​
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 Tu Pana. Por defecto: false.

​
external_id
string

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

Example:

"booking_abc123"

​
metadata
object

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

Response

Sesión de cobro creada exitosamente

​
payment_request_id
string

ID único de la sesión de cobro.

Example:

"pr_abc123"

​
status
enum<string>
Available options:
pending
Example:

"pending"

​
payment_url
string<uri>

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

Example:

"https://pay.tupana.com/pay/tok_xyz"

​
expires_at
string<date-time>

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

Example:

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