Debts API

This API allows managing debts in the system. It provides endpoints to list, create, get details, and perform various operations related to debts.

The CMS Base URL is used (see introduction).

The Debt Object

The Debt object represents a debt in the system.

{
  "debtId": "89480edc-d0e2-4e59-96ce-e705a3b6e1c4",
  "flowId": "a3a424c6-e34c-4519-933a-7e44fb016c40",
  "client": {
    "clientId": "e732bc5f-5b84-4a0a-81b4-5354d4625a8b",
    "partnerId": "6457c3ce-3887-45d6-92ca-299219ea96db",
    "externalId": "cli:32321",
    "legalName": "Frodo Baggins",
    "email": "mcgiber@irepair.com"
  },
  "disbursedAt": "2023-01-08",
  "referenceId": "PO-1234",
  "status": "active",
  "subStatus": "overdue",
  "terms": {
    "principal": {
      "amount": "100000.00",
      "currency": "ARS"
    },
    "repayEvery": 15,
    "interestRate": {
      "rate": "12.50",
      "period": 30
    },
    "installments": 2,
    "amortizationType": "equal_total",
    "disbursementDate": "2023-01-08",
    "interestTax": 12.5,
    "timezone": "America/Argentina/Buenos_Aires",
    "calendarType": "BusinessDays",
    "loanTermDuration": 30
  },
  "schedule": [
    {
      "number": 1,
      "dueDate": "2023-11-29",
      "originalAmounts": {
        "principal": {
          "amount": "25000.00",
          "currency": "ARS"
        },
        "interest": {
          "amount": "1250.00",
          "currency": "ARS"
        },
        "fees": {
          "amount": "0.00",
          "currency": "ARS"
        },
        "taxes": {
          "amount": "0.00",
          "currency": "ARS"
        },
        "total": {
          "amount": "26250.00",
          "currency": "ARS"
        }
      },
      "status": "overdue",
      "balance": {
        "principal": {
          "amount": "25000.00",
          "currency": "ARS"
        },
        "interest": {
          "amount": "1250.00",
          "currency": "ARS"
        },
        "fees": {
          "amount": "0.00",
          "currency": "ARS"
        },
        "taxes": {
          "amount": "0.00",
          "currency": "ARS"
        },
        "total": {
          "amount": "26250.00",
          "currency": "ARS"
        }
      },
      "daysPastDue": 10
    }
  ],
  "balance": {
    "principal": {
      "amount": "25000.00",
      "currency": "ARS"
    },
    "interest": {
      "amount": "1250.00",
      "currency": "ARS"
    },
    "fees": {
      "amount": "0.00",
      "currency": "ARS"
    },
    "taxes": {
      "amount": "0.00",
      "currency": "ARS"
    },
    "total": {
      "amount": "26250.00",
      "currency": "ARS"
    }
  },
  "daysPastDue": 10,
  "maxDaysPastDue": 30,
  "oldestDueDate": "2023-12-18",
  "source": "simple_credit",
  "totalDebtAmount": {
    "amount": "26250.00",
    "currency": "ARS"
  },
  "totalPaymentsAmount": {
    "amount": "0.00",
    "currency": "ARS"
  },
  "createdAt": "2021-01-01T00:00:00Z",
  "updatedAt": "2021-01-01T00:00:00Z"
}

Attributes

Attribute	Description	Type
`debtId`	Unique identifier of the debt	String (UUID)
`flowId`	Identifier of the associated flow	String (UUID)
`client`	Client information	Object
`disbursedAt`	Disbursement date	String (Date)
`referenceId`	Reference identifier	String
`status`	Debt status	String
`subStatus`	Debt sub-status	String
`terms`	Debt terms	Object
`schedule`	Payment schedule	Array of Object
`balance`	Current debt balance	Object
`daysPastDue`	Days past due	Integer
`maxDaysPastDue`	Maximum days past due	Integer
`oldestDueDate`	Oldest due date	String (Date)
`source`	Debt source	String
`totalDebtAmount`	Total debt amount	Object
`totalPaymentsAmount`	Total amount of payments made	Object
`createdAt`	Creation date	String (DateTime)
`updatedAt`	Last update date	String (DateTime)

Debt Status

Status	Key	Description
Unknown	`""`	The debt is in an unknown state, possibly not started.
Pending	`"pending"`	The debt is pending approval.
Approved	`"approved"`	The debt has been approved and is ready to be disbursed.
Active	`"active"`	The debt has been disbursed, and payments can be received.
Closed	`"closed"`	The debt has been closed, and all payments have been fulfilled.
Canceled	`"canceled"`	The debt was canceled, and no further payments are expected.

Debt Sub-Statuses

Sub-Status	Key	Associated Status	Description
Active	`"active"`	Active	The debt is active and payments can be received.
Due	`"due"`	Active	The debt is active with a payment due today (in UTC time)
Overdue	`"overdue"`	Active	The debt is active and at least one payment is overdue.
Paid	`"paid"`	Closed	The debt was fully paid and is now closed.
Overpaid	`"overpaid"`	Closed	The debt was fully paid and closed, but the last payment was greater than the remaining debt balance.
InRefinancing	`"refinancing"`	Active	The debt is in the process of refinancing, indicating that terms are being renegotiated.
Refinanced	`"refinanced"`	Closed	The debt has been successfully refinanced with new terms, and the previous debt has been settled under the new terms.

Debt Terms

The terms object contains the terms and conditions under which the debt was created.

Attribute	Description	Type	Allowed Values
`principal`	Principal amount of the debt	Object
`repayEvery`	Payment frequency in days	Integer
`interestRate`	Interest rate of the debt	Object
`installments`	Number of installments	Integer
`amortizationType`	Type of amortization	String
`disbursementDate`	Disbursement date	String (Date)
`interestTax`	Interest tax	Number
`timezone`	Timezone for calculations	String
`calendarType`	Calendar type for date calculations	String	`Custom`, `BusinessDays`, `NaturalDays`
`loanTermDuration`	Total loan duration in days	Integer

Endpoints

List Debts

Retrieves a paginated list of debts with filtering and sorting options.

GET /v1/debts

Query Parameters:

Parameter	Description	Type
`client-id`	Comma-separated list of client IDs	Array of UUID
`flow-id`	ID of the associated flow	UUID
`external-id`	Client's external ID	String
`tax-id`	Client's tax ID	String
`status`	Status of debts to return	Array of String
`disbursed-from`	Initial disbursement date	Date
`disbursed-to`	Final disbursement date	Date
`sort-by`	Sorting field and direction	String
`sub-status`	Sub-status of debts to return	Array of String
`oldest-due-date-from`	Initial oldest due date	Date
`oldest-due-date-to`	Final oldest due date	Date
`offset`	Number of items to skip	Integer
`limit`	Maximum number of items to return	Integer
`page`	Page number	Integer
`per-page`	Items per page	Integer
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response:

The response will be a paginated list of Debt objects.

Create a Debt

Creates a new debt from a flow, using the terms and schedule extracted from the flow.

POST /v1/debts

Input Parameters:

Parameter	Description	Type	Required
`flowId`	ID of the flow associated with the debt	UUID	Yes
`disbursedAt`	Debt disbursement date	Date	No
`amount`	Amount and currency of the debt	Object	Yes

Request Example:

{
  "flowId": "a3a424c6-e34c-4519-933a-7e44fb016c40",
  "disbursedAt": "2023-01-08",
  "amount": {
    "amount": "100000.00",
    "currency": "ARS"
  }
}

Successful Response:

Status code 201 (Created) if the debt was successfully created.

Get a Debt

Retrieves detailed information of a specific debt.

GET /v1/debts/:debt_id

Path Parameters:

Parameter	Description
`debt_id`	ID of the debt to retrieve

Query Parameters:

Parameter	Description
`dateToAnalyze`	Date to analyze the balance and transactions

Successful Response:

The response will be a complete Debt object.

Add a Credit Note to a Debt

Adds a credit note to a specific debt.

POST /v1/debts/:debt_id/credit-notes

Path Parameters:

Parameter	Description
`debt_id`	ID of the debt

Input Parameters:

Parameter	Description	Type	Required
`referenceId`	Unique reference ID of the credit note	String	Yes
`amount`	Amount and currency of the credit note	Object	Yes
`creditNoteDate`	Date of the credit note	Date	Yes
`breakdown`	Breakdown of the credit note components	Object	No
`notes`	Additional notes	String	No

Request Example:

{
  "referenceId": "CN-1234",
  "amount": {
    "amount": "5000.00",
    "currency": "ARS"
  },
  "creditNoteDate": "2023-05-15",
  "breakdown": {
    "principal": {
      "amount": "4000.00",
      "currency": "ARS"
    },
    "interest": {
      "amount": "1000.00",
      "currency": "ARS"
    }
  },
  "notes": "Partial refund for defective product"
}

Successful Response:

Status code 204 (No Content) if the credit note was successfully added.

Get Events of a Debt

Retrieves the list of events in the history of a specific debt.

GET /v1/debts/:debt_id/events

Path Parameters:

Parameter	Description
`debt_id`	ID of the debt

Successful Response:

The response will be a list of Event objects related to the debt.

List Payments of a Debt

Retrieves the list of payments received for a specific debt.

GET /v1/debts/:debt_id/payments

Path Parameters:

Parameter	Description
`debt_id`	ID of the debt

Successful Response:

The response will be a list of Payment objects related to the debt.

Add a Payment to a Debt

Adds a new payment to a specific debt.

POST /v1/debts/:debt_id/payments

Path Parameters:

Parameter	Description
`debt_id`	ID of the debt

Input Parameters:

Parameter	Description	Type	Required
`referenceId`	Unique reference ID of the payment	String	Yes
`paymentDate`	Payment date	Date	Yes
`amount`	Amount and currency of the payment	Object	Yes
`notes`	Additional notes	String	No

Request Example:

{
  "referenceId": "PAY-1234",
  "paymentDate": "2023-05-20",
  "amount": {
    "amount": "26250.00",
    "currency": "ARS"
  },
  "notes": "Payment of the first installment"
}

Successful Response:

Status code 204 (No Content) if the payment was successfully added.

Adds a payment to a debt identified by your referenceId (the invoice/PO number you supplied when creating the debt). Equivalent to the previous endpoint, but avoids having to resolve the debtId UUID first.

POST /v1/debts/payments/:reference_id

Path Parameters:

Parameter	Description
`reference_id`	Your `referenceId` for the debt

Input Parameters:

Same as POST /v1/debts/:debt_id/payments.

Successful Response:

Status code 204 (No Content) if the payment was successfully added.

Reverse a Payment on a Debt

Reverses a previously-reported payment, identified by its referenceId.

POST /v1/debts/:debt_id/payments/reversal

Path Parameters:

Parameter	Description
`debt_id`	ID of the debt

Input Parameters:

Parameter	Description	Type	Required
`referenceId`	`referenceId` of the payment to reverse	String	Yes
`notes`	Reason for the reversal	String	No

Request Example:

{
  "referenceId": "PAY-1234",
  "notes": "Payment bounced at bank"
}

Successful Response:

Status code 204 (No Content) if the reversal was successfully applied.

List Penalties of a Debt

Retrieves the list of penalties applied to a specific debt.

GET /v1/debts/:debt_id/penalties

Path Parameters:

Parameter	Description
`debt_id`	ID of the debt

Successful Response:

The response will be a list of Transaction objects representing the debt penalties.

Add a Waiver to a Debt

Adds a waiver to a specific debt.

POST /v1/debts/:debt_id/waivers

Path Parameters:

Parameter	Description
`debt_id`	ID of the debt

Input Parameters:

Parameter	Description	Type	Required
`referenceId`	Unique reference ID of the waiver	String	Yes
`amount`	Amount and currency of the waiver	Object	Yes
`waiverDate`	Waiver date	Date	Yes
`breakdown`	Breakdown of the waiver components	Object	Yes
`notes`	Additional notes	String	No

Request Example:

{
  "referenceId": "WV-1234",
  "amount": {
    "amount": "500.00",
    "currency": "ARS"
  },
  "waiverDate": "2023-05-25",
  "breakdown": {
    "penalties": {
      "amount": "500.00",
      "currency": "ARS"
    }
  },
  "notes": "Waiver of penalties as a goodwill gesture for the client"
}

Successful Response:

Status code 204 (No Content) if the waiver was successfully added.

Query Transactions Across Debts

Cross-debt transaction query, filtered by type and date range. Handy for reconciliation (e.g., pulling all penalties posted in the last month).

GET /v1/debts/transactions

Query Parameters:

Parameter	Description	Type
`type`	Transaction type (`payment`, `penalty`, `credit-note`, ...)	String
`transaction-date-from`	Inclusive start date	Date
`transaction-date-to`	Inclusive end date	Date
`external-id`	Client's external ID	String
`client-id`	Client ID	UUID
`offset`	Number of items to skip	Integer
`limit`	Maximum items to return	Integer

Successful Response:

A list of Transaction objects.

Export Debts

Schedules a batch export of debts matching the filters. Returns an exportId you can poll.

POST /v1/exports/debts
GET  /v1/exports/debts
GET  /v1/exports/debts/:export_id

See the /v1/exports subresource for the full export lifecycle (create, list, download).

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
500	Internal Server Error

Errors will include a descriptive message in the response body.

Debts API

The Debt Object

Attributes

Debt Status

Debt Sub-Statuses

Debt Terms

Endpoints

List Debts

Create a Debt

Get a Debt

Add a Credit Note to a Debt

Get Events of a Debt

List Payments of a Debt

Add a Payment to a Debt

Add a Payment by Reference ID

Reverse a Payment on a Debt

List Penalties of a Debt

Add a Waiver to a Debt

Query Transactions Across Debts

Export Debts

Error Handling

On this page