Skip to main content
POST
Crear link de pago

Autorizaciones

x-api-key
string
header
requerido

API key del API Gateway de Tapi. Requerida en todas las operaciones. Distinta por ambiente (desarrollo, homologación, producción).

x-authorization-token
string
header
requerido

Token TAPI JWT. Requerido en todas las operaciones. Se envía sin prefijo "Bearer". Ej: x-authorization-token: eyJhbGci...

Encabezados

Idempotency-Key
string

Clave de idempotencia (opcional). Si no se envía externalPaymentLinkId en el body, el valor del header se usa como externalPaymentLinkId; si se envían los dos, el header se ignora. Repetir un externalPaymentLinkId devuelve 409 RESOURCE_CONFLICT y no se crea ninguna deuda. Sin ninguno de los dos, el link no tiene llave externa (externalPaymentLinkId es null en la respuesta).

Cuerpo

application/json

Los campos no declarados se ignoran.

amount
number
requerido

Monto en pesos (hasta 2 decimales, mínimo 0.01)

Rango requerido: x >= 0.01Debe ser un múltiplo de 0.01
description
string
requerido

Descripción visible en la página de pago. Debe ser string (si no, 400).

expiresAt
string<date-time>
requerido

Fecha/hora de expiración, obligatoria. Debe ser un date-time RFC 3339 (con Z u offset) y estar en el futuro; 2026-12-31 23:59 o solo fecha devuelven 400. Se convierte y guarda en UTC. El vencimiento de la deuda asociada es la fecha UTC de expiresAt.

Ejemplo:

"2026-12-31T23:59:59Z"

currency
enum<string>
predeterminado:MXN

Código de moneda ISO 4217 (MXN, ARS, PEN, COP, CLP, USD). Default MXN.

Opciones disponibles:
MXN,
ARS,
PEN,
COP,
CLP,
USD

Llave natural del link. Única por organización. Usada para idempotencia y matching externo. Si no se envía, se usa el header Idempotency-Key. Si no hay ninguno de los dos, el link no tiene llave externa: en la respuesta externalPaymentLinkId es null y el debtId usa el UUID del link (debt_pl-debt-<uuid>). Repetirla devuelve 409 RESOURCE_CONFLICT y no se crea ninguna deuda.

successUrl
string<uri>

URL de redirección al completar el pago (opcional)

singleUse
boolean
predeterminado:true

Si true, el link se desactiva tras el primer pago. Si false, acepta múltiples pagos (reutilizable). Default true.

metadata
object

Metadatos arbitrarios del cliente (opcional). Objeto plano.

externalClientId
string

Identificador del deudor (cliente conocido). Mutuamente excluyente con contactData. Si se proporciona, la API resuelve el contacto existente por externalClientId en la organización. Si no corresponde a un contacto existente, la API responde 422 BUSINESS_RULE_VIOLATION y no se crea nada; para crear el contacto en el mismo request usa contactData.

contactData
object

Datos del deudor inline. Mutuamente excluyente con externalClientId. Si se proporciona, se crea un nuevo contacto (o se reutiliza si externalClientId ya existe).

productName
string

Nombre del producto a asociar (opcional). Se resuelve por name o se crea inline si no existe. Identificado por name único por companyCode.

identifierValue
string

Identificador explícito del link de pago (opcional). Si se proporciona, se sanitiza a URL-safe (alfanumérico + guiones, lowercase, máx 64 chars). Si tras sanear queda vacío, retorna 400 INVALID_REQUEST. Precedencia de resolución: identifierValue explícito > externalClientId (deudor) > sintético. Si se envía identifierValue: se usa ese valor (saneado). Si NO se envía y hay deudor conocido (externalClientId/contactData): se usa el identificador del deudor. Si NO se envía y NO hay deudor: se genera sintético {3letras}-{random}. Exposición en respuesta (PII-safe): SIN deudor conocido (anónimo/reutilizable) se expone identifierValue en respuesta. CON deudor conocido: se devuelve null, incluso si el cliente mandó identifierValue explícito.

Maximum string length: 64
additionalData
object

Objeto plano con las mismas claves reservadas que en deudas. Se guarda en la deuda asociada al link; no se devuelve en el link.

Ejemplo:

Respuesta

Link de pago creado

data
object

externalPaymentLinkId, expiresAt, successUrl, metadata, identifierValue, contact y product siempre vienen, con null cuando no hay valor.

Ejemplo:
requestId
string