Debt) is a one-time charge to a known debtor: a fixed amount charged to an identified person or entity, with a due date and configurable payment methods. It is the most common use case of the API.
You specify who pays, how much, and when it is due. TapiPay resolves all of the complexity internally (your organization, the modalities, and the internal data of the collections system) and returns a clean contract that always includes the payment URL.
When to use a debt
Debt
A single charge to someone you know: an invoice, an installment, a one-time service.
Subscription
If the charge repeats over time (monthly payments, installments).
Payment link
If you do not know the debtor in advance (donations, one-off sales).
Create a debt
To create a debt you need, at a minimum, to identify the debtor, the amount, and the due date.Identify the debtor
You must send one of these two fields (not both, not neither):
See Contacts for details on the reusable debtor.
Main fields
number
required
Amount in pesos, with up to 2 decimal places (minimum
0.01). For example, 1500.50 equals $1,500.50 MXN.string
required
Due date in
YYYY-MM-DD format.string
Currency code. Allowed values:
MXN, ARS, PEN, COP, CLP, USD. If you do not send it, your organization’s default is used (falling back to MXN).string
Name of a product to categorize the charge. If it does not exist, it is created inline; if it already exists, it is reused. See Products.
boolean
default:"true"
Enables partial payments. With
true, the debt moves to PARTIALLY_PAID until it is settled.boolean
default:"true"
If
false, the debt cannot be paid after the dueDate.boolean
default:"false"
Direct debit. It cannot coexist with
paymentMethods. See Payment methods.array
Methods enabled for this debt:
CASH, CARD, TRANSFER, WALLET, BANK_TRANSFER. Only valid when autopay is false.You never send or receive internal system data (organization, modalities,
generationData). You work only with business concepts.The response
The creation and query response always includespaymentUrl (the URL ready to share with your debtor) and amountPaid (the accumulated amount paid).
Payment deep link
ThepaymentUrl is a deep link: it includes the debt’s externalRequestId as a query param (?externalRequestId=...), so it points directly to that specific debt. Share it as-is with your debtor; you don’t need to build the URL by hand. Debts generated by a subscription also carry their own deep link (you see it in GET /subscriptions/{id}/debts).
Lifecycle
Update and cancel
Update (PATCH /debts/{id})
Update (PATCH /debts/{id})
You can only update a debt in
PENDING status. Attempting it in another status returns 422 BUSINESS_RULE_VIOLATION.Editable fields: amount, dueDate. Sending any other field returns 400 INVALID_REQUEST.Cancel (POST /debts/{id}/cancel)
Cancel (POST /debts/{id}/cancel)
You can cancel a debt in
PENDING, PARTIALLY_PAID, or OVERDUE status. You cannot cancel a debt that is already PAID or CANCELLED (returns 422 BUSINESS_RULE_VIOLATION).Endpoints
Try it in the API Reference
Explore each endpoint with its interactive playground.