> ## Documentation Index
> Fetch the complete documentation index at: https://devs.tapipay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Debts

> Charge a one-time amount to a known debtor with the TapiPay Facade API.

A **debt** (`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

<CardGroup cols={3}>
  <Card title="Debt" icon="file-invoice-dollar">
    A single charge to someone you know: an invoice, an installment, a one-time service.
  </Card>

  <Card title="Subscription" icon="arrows-rotate" href="/en/resources/subscriptions">
    If the charge repeats over time (monthly payments, installments).
  </Card>

  <Card title="Payment link" icon="link" href="/en/resources/payment-links">
    If you do not know the debtor in advance (donations, one-off sales).
  </Card>
</CardGroup>

## Create a debt

To create a debt you need, at a minimum, to identify the debtor, the amount, and the due date.

```bash theme={null}
curl --request POST \
  --url 'https://tapipay-facade.dev.tapila.cloud/debts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Idempotency-Key: INV-2026-001' \
  --header 'Content-Type: application/json' \
  --data '{
    "contactData": {
      "externalClientId": "CLI-00042",
      "name": "Sample Customer",
      "email": "cliente@example.com"
    },
    "amount": 1500.00,
    "currency": "MXN",
    "dueDate": "2026-07-01",
    "description": "June 2026 invoice",
    "paymentMethods": ["CASH", "CARD"]
  }'
```

### Identify the debtor

You must send **one** of these two fields (not both, not neither):

| Field              | When to use it                                                                                                             |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `externalClientId` | The debtor already exists in your records. If it does not exist, the API responds `422 BUSINESS_RULE_VIOLATION`.           |
| `contactData`      | Debtor data inline. If the `externalClientId` does not exist, the contact is created; if it already exists, it is updated. |

See [Contacts](/en/resources/contacts) for details on the reusable debtor.

### Main fields

<ResponseField name="amount" type="number" required>
  Amount in **pesos**, with up to 2 decimal places (minimum `0.01`). For example, `1500.50` equals \$1,500.50 MXN.
</ResponseField>

<ResponseField name="dueDate" type="string" required>
  Due date in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="currency" type="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`).
</ResponseField>

<ResponseField name="productName" type="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](/en/resources/products).
</ResponseField>

<ResponseField name="allowPartialPayments" type="boolean" default="true">
  Enables partial payments. With `true`, the debt moves to `PARTIALLY_PAID` until it is settled.
</ResponseField>

<ResponseField name="allowOverduePayment" type="boolean" default="true">
  If `false`, the debt cannot be paid after the `dueDate`.
</ResponseField>

<ResponseField name="autopay" type="boolean" default="false">
  Direct debit. It cannot coexist with `paymentMethods`. See [Payment methods](/en/concepts/payment-methods).
</ResponseField>

<ResponseField name="paymentMethods" type="array">
  Methods enabled for this debt: `CASH`, `CARD`, `TRANSFER`, `WALLET`, `BANK_TRANSFER`. Only valid when `autopay` is `false`.
</ResponseField>

<Note>
  You never send or receive internal system data (organization, modalities, `generationData`). You work only with business concepts.
</Note>

## The response

The creation and query response **always** includes `paymentUrl` (the URL ready to share with your debtor) and `amountPaid` (the accumulated amount paid).

```json theme={null}
{
  "data": {
    "debtId": "debt_1xY7zR4p",
    "externalRequestId": "INV-2026-001",
    "status": "PENDING",
    "amount": 1500.00,
    "amountPaid": 0,
    "currency": "MXN",
    "dueDate": "2026-07-01",
    "description": "June 2026 invoice",
    "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"
}
```

### Payment deep link

The `paymentUrl` 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](/en/resources/subscriptions) also carry their own deep link (you see it in `GET /subscriptions/{id}/debts`).

## Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING
    PENDING --> PARTIALLY_PAID: partial payment
    PENDING --> PAID: full payment
    PENDING --> OVERDUE: dueDate passes
    PENDING --> CANCELLED: cancellation
    PARTIALLY_PAID --> PAID: total completed
    PARTIALLY_PAID --> CANCELLED: cancellation
    OVERDUE --> PAID: late payment (if allowOverduePayment)
    OVERDUE --> CANCELLED: cancellation
    PAID --> [*]
    CANCELLED --> [*]
```

| Status           | Meaning                                                                            |
| ---------------- | ---------------------------------------------------------------------------------- |
| `PENDING`        | Created, with no payments.                                                         |
| `PARTIALLY_PAID` | Received at least one payment, but `amountPaid < amount`.                          |
| `PAID`           | Fully settled. Final state.                                                        |
| `OVERDUE`        | Past the `dueDate`. If `allowOverduePayment` is `false`, it can no longer be paid. |
| `CANCELLED`      | Manually cancelled. Final state.                                                   |

## Update and cancel

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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`).
  </Accordion>
</AccordionGroup>

## Endpoints

| Method  | Path                 | Description                             |
| ------- | -------------------- | --------------------------------------- |
| `POST`  | `/debts`             | Create a debt.                          |
| `GET`   | `/debts/{id}`        | Retrieve a debt by its `debtId`.        |
| `GET`   | `/debts`             | List debts with filters and pagination. |
| `PATCH` | `/debts/{id}`        | Update a debt in `PENDING` status.      |
| `POST`  | `/debts/{id}/cancel` | Cancel a debt.                          |

<Card title="Try it in the API Reference" icon="play" href="/api-reference">
  Explore each endpoint with its interactive playground.
</Card>