Ligas de pago

Una liga de pago (PaymentLink) es una URL pública de pago que puedes compartir sin conocer al deudor de antemano. Cuando alguien paga, TapiPay genera internamente una deuda por ese pago. 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). Genera una deuda con el primer pago y se desactiva. 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 y una descripción visible en la página de pago.

curl --request POST \
  --url 'https://tapipay-facade.dev.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.

string

Llave natural de la liga. Opcional, pero si la envías debe ser única por organización (un duplicado devuelve 409 RESOURCE_CONFLICT).

boolean

predeterminado:"true"

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

string

Identificador propio para la URL (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

requerido

Fecha y hora de expiración (ISO 8601). Debe ser futura. Es obligatoria.

string

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

También acepta currency, productName y metadata.

El `identifierValue` y la URL de pago

El paymentUrl siempre viene en la respuesta. 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 y es el segmento final de la paymentUrl, así que puedes correlacionarlo sin parsear la URL.

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).

{
  "data": {
    "paymentLinkId": "plk_7nS9uV3d",
    "status": "ACTIVE",
    "amount": 4500.00,
    "currency": "MXN",
    "description": "Factura única #777",
    "singleUse": true,
    "identifierValue": "acm-x3kM9pQr",
    "paymentUrl": "https://app.tapipay.la/s/acme-corp/portal/acm-x3kM9pQr/",
    "createdAt": "2026-06-03T19:20:00Z"
  },
  "requestId": "req_a1b2c3d4"
}

Si creas la liga con externalClientId o contactData, el identificador interno es el del deudor y se omite de la respuesta para no exponer datos personales (PII-safe). El paymentUrl puede venir resuelto o null si no puede generarse de forma segura.

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.

Una liga reutilizable (singleUse: false) permanece ACTIVE y acumula pagos. Cada pago genera una deuda interna; los consultas con GET /payment-links/{id}/payments.

Actualizar sin invalidar la URL

PATCH /payment-links/{id} permite cambiar description, expiresAt y metadata sin cambiar el paymentUrl: la liga sigue accesible desde la misma URL. El amount, la currency y singleUse no son modificables (intentarlo devuelve 400 INVALID_REQUEST).

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.
`GET`	`/payment-links/{id}/payments`	Listar los pagos recibidos.

Pruébalo en el API Reference

Explora cada endpoint con su playground interactivo.

Empieza aquí

Conceptos

Recursos

Portal de pagos

Webhooks

Dos modos de uso

Un solo uso

Reutilizable

Crear una liga

Campos principales

El `identifierValue` y la URL de pago

Ciclo de vida

Actualizar sin invalidar la URL

Endpoints

Pruébalo en el API Reference

​Dos modos de uso

Un solo uso

Reutilizable

​Crear una liga

​Campos principales

​El identifierValue y la URL de pago

​Ciclo de vida

​Actualizar sin invalidar la URL

​Endpoints

Pruébalo en el API Reference

Dos modos de uso

Crear una liga

Campos principales

El `identifierValue` y la URL de pago

Ciclo de vida

Actualizar sin invalidar la URL

Endpoints