Ligas de pago

Una liga de pago (PaymentLink) es una URL pública de pago que puedes compartir sin conocer al deudor de antemano. Al crear la liga, TapiPay genera una deuda asociada, que es la que recibe el pago; su ID viene en el campo debtId de la respuesta. Cuándo usarla: cobros sin padrón de deudores (donaciones, ventas sueltas, links de checkout por WhatsApp o email), donde conoces al pagador en el momento del pago, no antes. Si ya conoces al deudor, una deuda suele ser mejor.

Dos modos de uso

Un solo uso

singleUse: true (default). Se desactiva tras el primer pago. Ideal para una factura o venta puntual.

Reutilizable

singleUse: false. Se crea sin deudor y acepta múltiples pagos mientras siga activa. Modo donaciones o pasarela de pagos.

Crear una liga

Lo mínimo es el monto, una descripción visible en la página de pago y la fecha de expiración.

curl --request POST \
  --url 'https://tapipay-facade.homo.tapila.cloud/payment-links' \
  --header 'x-api-key: TU_API_KEY' \
  --header 'x-authorization-token: TU_TOKEN_TAPI' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalPaymentLinkId": "LINK-DONACION-01",
    "amount": 500.00,
    "currency": "MXN",
    "description": "Donación campaña 2026",
    "expiresAt": "2026-12-31T23:59:59Z",
    "singleUse": false
  }'

Campos principales

number

requerido

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

string

requerido

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

string

requerido

Fecha y hora de expiración, obligatoria y en el futuro. Debe ser un date-time RFC 3339, con Z o con offset (2026-12-31T23:59:59Z, 2026-12-31T17:59:59-06:00). Un valor como 2026-12-31 23:59 o una fecha sola devuelven 400 INVALID_REQUEST. Se guarda en UTC (ver Fechas de la liga).

string

Llave natural de la liga. Opcional, pero si la envías debe ser única por organización: un duplicado devuelve 409 RESOURCE_CONFLICT y no se crea ninguna deuda. Ver Idempotencia.

boolean

predeterminado:"true"

true se desactiva tras el primer pago; false acepta múltiples pagos.

string

Identificador propio para la liga (opcional). Se sanea a un formato seguro para URL (minúsculas, alfanuméricos y guiones, máximo 64 caracteres). Si tras sanear queda vacío, devuelve 400 INVALID_REQUEST.

string

Identificador de un deudor que ya existe como contacto. Excluyente con contactData. 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.

object

Datos del deudor inline (alternativa a externalClientId).

string

URL de redirección al completar el pago. Si no la envías, se usa la página de Tapi.

object

Datos propios de tu sistema. Debe ser un objeto plano, con las mismas claves reservadas que en las deudas (ver Convenciones de la API). Se guarda en la deuda asociada a la liga y no se devuelve en la liga.

También acepta currency (default MXN), productName y metadata (objeto plano). Los campos que no están declarados se ignoran.

Idempotencia

La llave de idempotencia de una liga es su externalPaymentLinkId:

Si lo envías en el body, se usa ese valor.
Si no lo envías, pero mandas el header Idempotency-Key, el valor del header se usa como externalPaymentLinkId. Si envías los dos, el header se ignora.
Si no envías ninguno de los dos, la liga no tiene llave propia y cada request crea una liga nueva. En la respuesta, externalPaymentLinkId viene en null.

Repetir un externalPaymentLinkId que ya existe devuelve 409 RESOURCE_CONFLICT y no se crea ninguna deuda. Para recuperar la liga original, búscala con GET /payment-links?externalPaymentLinkId=....

La respuesta

La liga siempre trae externalPaymentLinkId, expiresAt, successUrl, metadata, identifierValue, contact y product, con null cuando no hay valor. contact es siempre null en esta versión.

{
  "data": {
    "paymentLinkId": "plk_61a837f5-3c67-423a-ade7-94b78e0007cb",
    "status": "ACTIVE",
    "amount": 4500.00,
    "currency": "MXN",
    "description": "Factura única #777",
    "singleUse": true,
    "paymentUrl": "https://app.tapipay.la/s/acme-corp/portal/McXmbnKaju/debts/payment-methods?externalRequestId=pl-debt-FAC-777",
    "createdAt": "2026-06-03T19:20:00.000Z",
    "debtId": "debt_pl-debt-FAC-777",
    "externalPaymentLinkId": "FAC-777",
    "expiresAt": "2026-06-30T23:59:59.000Z",
    "successUrl": null,
    "metadata": null,
    "identifierValue": "acm-x3kM9pQr",
    "contact": null,
    "product": null
  },
  "requestId": "req_a1b2c3d4e5f6"
}

Campo	Formato
`paymentLinkId`	`plk_` + UUID. En el path de los endpoints también se acepta sin el prefijo.
`debtId`	`debt_pl-debt-` + `externalPaymentLinkId`. Si la liga no tiene `externalPaymentLinkId`, `debt_pl-debt-` + el UUID de su `paymentLinkId` (sin `plk_`). Sirve para leer la deuda con `GET /debts/{id}` y para filtrar `GET /payment-links`.
`product`	Producto asociado vía `productName`, o `null`. Su `createdInline` se conserva en las lecturas.

El `identifierValue` y la URL de pago

El paymentUrl es una URL opaca: úsala tal como viene, sin parsearla ni armarla a mano. Con Private Links habilitado lleva un código corto y no contiene el identifierValue. Sin Private Links, o si no se puede generar el código corto, es la URL con el formato de liga de pago del portal. Si la integración con el portal falla, viene en null y la liga se crea igual. Las ligas creadas antes de este cambio conservan su URL anterior. Cómo se arma el identifierValue depende de si la liga tiene un deudor conocido:

Sin deudor conocido
Con deudor conocido

Es el caso típico de una liga. El identifierValue se expone en la respuesta, así que puedes usarlo para correlacionar la liga con tu sistema.

Si enviaste identifierValue, se usa tu valor saneado.
Si no, TapiPay genera uno sintético con el formato {3letras}-{aleatorio} (las 3 letras salen del nombre de tu organización; por ejemplo, “Acme Corp” produce acm-x3kM9pQr).

Si creas la liga con externalClientId o contactData, el identificador interno es el del deudor y el identifierValue viene en null para no exponer datos personales (PII-safe), aunque hayas enviado uno explícito.

Fechas de la liga

expiresAt se devuelve siempre en UTC con milisegundos y Z (YYYY-MM-DDTHH:mm:ss.sssZ), aunque la hayas enviado con offset:

Enviado	Devuelto
`2027-02-10T23:30:00-06:00`	`2027-02-11T05:30:00.000Z`
`2026-12-31T23:59:59Z`	`2026-12-31T23:59:59.000Z`

Las ligas antiguas guardadas con fecha sola (2026-12-01) se devuelven como el inicio de ese día UTC (2026-12-01T00:00:00.000Z). La deuda asociada vence en la fecha UTC de expiresAt: en el primer ejemplo, el 2027-02-11.

Ciclo de vida

Estado	Significado
`ACTIVE`	Disponible para recibir pagos.
`PAID`	Pagada. Aplica a ligas `singleUse: true` tras el primer pago.
`EXPIRED`	Superó `expiresAt`. Ya no acepta pagos.
`CANCELLED`	Cancelada manualmente. Estado final.

Actualizar sin invalidar la URL

PATCH /payment-links/{id} permite cambiar tres campos sin cambiar el paymentUrl: la liga sigue accesible desde la misma URL.

string

Nueva descripción. Debe ser un string no vacío.

string

Nuevo vencimiento, date-time RFC 3339 en el futuro. null devuelve 400: las ligas siempre vencen. Se guarda en UTC y actualiza también el vencimiento de la deuda asociada a la fecha UTC del nuevo valor (por ejemplo, 2027-02-10T23:30:00-06:00 hace que la deuda venza el 2027-02-11).

object

Nuevos metadatos, objeto plano. Reemplaza por completo los anteriores. null o un valor que no es objeto devuelven 400.

Si la deuda asociada ya fue cancelada, el PATCH actualiza solo la liga. description y metadata solo cambian la liga, no su deuda. Un body vacío o cualquier otro campo (amount, currency, singleUse, etc.) devuelven 400 INVALID_REQUEST. Una liga en estado PAID, EXPIRED o CANCELLED no se puede editar: devuelve 422 BUSINESS_RULE_VIOLATION, y ese estado se valida antes que el body.

Cancelar

POST /payment-links/{id}/cancel pasa la liga a CANCELLED y cancela también su deuda asociada. Si la cancelación de la deuda falla, la liga queda cancelada igual. Cancelar una liga que ya está cancelada devuelve 200 sin cambios; una liga PAID o EXPIRED no se puede cancelar (422 BUSINESS_RULE_VIOLATION). La respuesta mantiene el paymentUrl.

Listar ligas

GET /payment-links devuelve tus ligas paginadas, ordenadas por externalPaymentLinkId descendente (no por fecha de creación).

Filtro	Descripción
`status`	`ACTIVE`, `PAID`, `EXPIRED` o `CANCELLED`. Distingue mayúsculas: otro valor devuelve `400`.
`externalPaymentLinkId`	Match exacto.
`debtId`	`debtId` de la deuda asociada, match exacto.
`createdAtFrom` / `createdAtTo`	Rango de creación. Aceptan fecha (`YYYY-MM-DD`) o date-time RFC 3339; otro formato devuelve `400`. Una fecha sola cubre el día UTC completo, incluido en los dos extremos. A diferencia de `GET /debts`, un date-time se compara de forma exacta, no por día.
`page` / `limit`	Paginación (ver Convenciones de la API).

Este es el único listado cuyo meta trae capped: vale true cuando meta.total es aproximado porque se alcanzó el máximo de ítems que el servicio recorre.

Pagos de una liga

GET /payment-links/{id}/payments devuelve las deudas asociadas a la liga, con su estado y amountPaid. Una liga recién creada devuelve su deuda PENDING con amountPaid: 0. El paymentId es el identificador interno de esa deuda (debt_ + un número): no es el debtId de la liga, así que para leer la deuda con GET /debts/{id} usa el debtId. Las deudas canceladas no se listan.

{
  "data": [
    {
      "paymentId": "debt_13700695",
      "amount": 4500.00,
      "amountPaid": 0,
      "currency": "MXN",
      "status": "PENDING",
      "createdAt": "2026-06-03T19:20:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 1, "hasMore": false },
  "requestId": "req_a1b2c3d4e5f6"
}

Acepta los mismos filtros que GET /debts: status, createdAtFrom / createdAtTo (con la misma regla de fechas por día UTC), minAmount, maxAmount, externalClientId, batchId, page y limit. Su meta no trae capped.

Endpoints

Método	Ruta	Descripción
`POST`	`/payment-links`	Crear una liga.
`GET`	`/payment-links/{id}`	Consultar una liga.
`GET`	`/payment-links`	Listar ligas.
`PATCH`	`/payment-links/{id}`	Actualizar `description`, `expiresAt`, `metadata`.
`POST`	`/payment-links/{id}/cancel`	Cancelar la liga y su deuda.
`GET`	`/payment-links/{id}/payments`	Listar las deudas asociadas a la liga.

Pruébalo en el API Reference

Explora cada endpoint con su playground interactivo.

Empieza aquí

Novedades

Conceptos

Recursos

Portal de pagos

Webhooks

Dos modos de uso

Un solo uso

Reutilizable

Crear una liga

Campos principales

Idempotencia

La respuesta

El `identifierValue` y la URL de pago

Fechas de la liga

Ciclo de vida

Actualizar sin invalidar la URL

Cancelar

Listar ligas

Pagos de una liga

Endpoints

Pruébalo en el API Reference

​Dos modos de uso

Un solo uso

Reutilizable

​Crear una liga

​Campos principales

​Idempotencia

​La respuesta

​El identifierValue y la URL de pago

​Fechas de la liga

​Ciclo de vida

​Actualizar sin invalidar la URL

​Cancelar

​Listar ligas

​Pagos de una liga

​Endpoints

Pruébalo en el API Reference

Dos modos de uso

Crear una liga

Campos principales

Idempotencia

La respuesta

El `identifierValue` y la URL de pago

Fechas de la liga

Ciclo de vida

Actualizar sin invalidar la URL

Cancelar

Listar ligas

Pagos de una liga

Endpoints