Deudas

Una deuda (Debt) es un cargo puntual a un deudor conocido: un importe fijo que se cobra a una persona o entidad identificada, con una fecha de vencimiento y medios de pago configurables. Es el caso de uso más común de la API. Tú indicas quién paga, cuánto y cuándo vence. TapiPay resuelve internamente toda la complejidad (tu organización, las modalidades y los datos internos del sistema de cobranzas) y te devuelve un contrato limpio que siempre incluye la URL de pago.

Cuándo usar una deuda

Deuda

Un cobro único a alguien que conoces: una factura, una cuota, un servicio puntual.

Suscripción

Si el cobro se repite en el tiempo (mensualidades, cuotas).

Liga de pago

Si no conoces al deudor de antemano (donaciones, ventas sueltas).

Crear una deuda

Para crear una deuda necesitas, como mínimo, identificar al deudor, el monto y la fecha de vencimiento.

curl --request POST \
  --url 'https://tapipay-facade.dev.tapila.cloud/debts' \
  --header 'x-api-key: TU_API_KEY' \
  --header 'x-authorization-token: TU_TOKEN_TAPI' \
  --header 'Idempotency-Key: INV-2026-001' \
  --header 'Content-Type: application/json' \
  --data '{
    "contactData": {
      "externalClientId": "CLI-00042",
      "name": "Cliente Ejemplo",
      "email": "cliente@example.com"
    },
    "amount": 1500.00,
    "currency": "MXN",
    "dueDate": "2026-07-01",
    "description": "Factura junio 2026",
    "paymentMethods": ["CASH", "CARD"]
  }'

Identificar al deudor

Debes enviar uno de estos dos campos (no ambos, no ninguno):

Campo	Cuándo usarlo
`externalClientId`	El deudor ya existe en tu padrón. Si no existe, la API responde `422 BUSINESS_RULE_VIOLATION`.
`contactData`	Datos del deudor en línea. Si el `externalClientId` no existe, se crea el contacto; si ya existe, se actualiza.

Ver Contactos para el detalle del deudor reutilizable.

Campos principales

number

requerido

Monto en pesos, con hasta 2 decimales (mínimo 0.01). Por ejemplo, 1500.50 equivale a $1,500.50 MXN.

string

requerido

Fecha de vencimiento en formato YYYY-MM-DD.

string

Código de moneda. Valores permitidos: MXN, ARS, PEN, COP, CLP, USD. Si no lo envías, se usa el default de tu organización (con respaldo en MXN).

string

Nombre de un producto para categorizar el cobro. Si no existe, se crea en línea; si ya existe, se reutiliza. Ver Productos.

boolean

predeterminado:"true"

Habilita pagos parciales. Con true, la deuda pasa a PARTIALLY_PAID hasta saldarse.

boolean

predeterminado:"true"

Si es false, la deuda no puede pagarse después del dueDate.

boolean

predeterminado:"false"

Domiciliación. No puede coexistir con paymentMethods. Ver Medios de pago.

array

Medios habilitados para esta deuda: CASH, CARD, TRANSFER, WALLET, BANK_TRANSFER. Solo válido cuando autopay es false.

Nunca envías ni recibes datos internos del sistema (organización, modalidades, generationData). Trabajas solo con conceptos de negocio.

La respuesta

La respuesta de creación y de consulta siempre incluye paymentUrl (la URL lista para compartir con tu deudor) y amountPaid (el acumulado pagado).

{
  "data": {
    "debtId": "debt_1xY7zR4p",
    "externalRequestId": "INV-2026-001",
    "status": "PENDING",
    "amount": 1500.00,
    "amountPaid": 0,
    "currency": "MXN",
    "dueDate": "2026-07-01",
    "description": "Factura junio 2026",
    "allowOverduePayment": true,
    "allowPartialPayments": true,
    "autopay": false,
    "paymentMethods": ["CASH", "CARD"],
    "paymentUrl": "https://app.tapipay.la/s/acme-corp/portal/CLI-00042/?externalRequestId=INV-2026-001",
    "contact": {
      "contactId": "con_9aL3kP2m",
      "externalClientId": "CLI-00042",
      "createdInline": true
    },
    "createdAt": "2026-06-03T18:10:00Z"
  },
  "requestId": "req_a1b2c3d4"
}

Deep link de pago

El paymentUrl es un deep link: incluye el externalRequestId de la deuda como query param (?externalRequestId=...), así apunta directo a esa deuda puntual. Compártelo tal cual con tu deudor; no necesitas construir la URL a mano. Las deudas generadas por una suscripción también traen su propio deep link (lo ves en GET /subscriptions/{id}/debts).

Ciclo de vida

Estado	Significado
`PENDING`	Creada, sin pagos.
`PARTIALLY_PAID`	Recibió al menos un pago, pero `amountPaid < amount`.
`PAID`	Saldada por completo. Estado final.
`OVERDUE`	Superó el `dueDate`. Si `allowOverduePayment` es `false`, ya no puede pagarse.
`CANCELLED`	Cancelada manualmente. Estado final.

Actualizar y cancelar

Actualizar (PATCH /debts/{id})

Solo se puede actualizar una deuda en estado PENDING. Intentarlo en otro estado devuelve 422 BUSINESS_RULE_VIOLATION.Campos editables: amount, dueDate. Enviar cualquier otro campo devuelve 400 INVALID_REQUEST.

Cancelar (POST /debts/{id}/cancel)

Se puede cancelar una deuda en estado PENDING, PARTIALLY_PAID u OVERDUE. No se puede cancelar una deuda ya PAID o CANCELLED (devuelve 422 BUSINESS_RULE_VIOLATION).

Endpoints

Método	Ruta	Descripción
`POST`	`/debts`	Crear una deuda.
`GET`	`/debts/{id}`	Consultar una deuda por su `debtId`.
`GET`	`/debts`	Listar deudas con filtros y paginación.
`PATCH`	`/debts/{id}`	Actualizar una deuda en estado `PENDING`.
`POST`	`/debts/{id}/cancel`	Cancelar una deuda.

Pruébalo en el API Reference

Explora cada endpoint con su playground interactivo.

Empieza aquí

Conceptos

Recursos

Portal de pagos

Webhooks

Cuándo usar una deuda

Deuda

Suscripción

Liga de pago

Crear una deuda

Identificar al deudor

Campos principales

La respuesta

Deep link de pago

Ciclo de vida

Actualizar y cancelar

Endpoints

Pruébalo en el API Reference

​Cuándo usar una deuda

Deuda

Suscripción

Liga de pago

​Crear una deuda

​Identificar al deudor

​Campos principales

​La respuesta

​Deep link de pago

​Ciclo de vida

​Actualizar y cancelar

​Endpoints

Pruébalo en el API Reference

Cuándo usar una deuda

Crear una deuda

Identificar al deudor

Campos principales

La respuesta

Deep link de pago

Ciclo de vida

Actualizar y cancelar

Endpoints