Zum Inhalt springen
DebtFlow

Payments

Incoming payments and instalment plans for debts.

List instalment plans

GET/api/v1/installment-plans

Permission: payments:read

Query parameters

  • debtIdstring
    max. 128 characters
  • status"active" | "completed" | "canceled"
  • limitinteger
    Number of entries (1–100)
    1–100 · Default: 25
  • cursorstring
    `nextCursor` of the previous page
    max. 500 characters

Response 200

  • object"list"required
  • dataArray<InstallmentPlan>required
    • idstringrequired
    • object"installment_plan"required
    • debtIdstringrequired
    • status"active" | "completed" | "canceled"required
    • amountCentsintegerrequired
      Agreed total amount
      -100000000000–100000000000
    • numberOfPaymentsintegerrequired
      -9007199254740991–9007199254740991
    • installmentCentsintegerrequired
      Monthly instalment
      -100000000000–100000000000
    • startDatestring (date) | nullrequired
      Date (YYYY-MM-DD)
    • paymentsMadeintegerrequired
      -9007199254740991–9007199254740991
    • paidCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • remainingCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • nextDueDatestring (date) | nullrequired
      Date (YYYY-MM-DD)
    • lastPaymentDatestring (date) | nullrequired
      Date (YYYY-MM-DD)
    • scheduleArray<object>required
      Due dates (monthly)
      • numberintegerrequired
        -9007199254740991–9007199254740991
      • dueDatestring (date)required
        Date (YYYY-MM-DD)
      • amountCentsintegerrequired
        Amount in cents
        -100000000000–100000000000
    • notesstringrequired
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
    • updatedAtstring (date-time)required
      Timestamp (ISO 8601)
  • hasMorebooleanrequired
  • nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/installment-plans' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "installment_plan",
      "debtId": "string",
      "status": "active",
      "amountCents": 0,
      "numberOfPayments": 0,
      "installmentCents": 0,
      "startDate": "2026-11-01",
      "paymentsMade": 0,
      "paidCents": 0,
      "remainingCents": 0,
      "nextDueDate": "2026-11-01",
      "lastPaymentDate": "2026-11-01",
      "schedule": [
        {
          "number": 0,
          "dueDate": "2026-11-01",
          "amountCents": 0
        }
      ],
      "notes": "string",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Create instalment plan

POST/api/v1/installment-plans

Monthly instalments from startDate; rounding cents are added to the first instalments. Event installment_plan.created.

Permission: payments:write

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · InstallmentPlanCreate

  • debtIdstringrequired
    max. 128 characters
  • amountCentsintegerrequired
    Amount in cents
    0–100000000000
  • numberOfPaymentsintegerrequired
    1–120
  • startDatestring (date)required
    Due date of the first instalment
  • notesstring
    max. 2000 characters

Response 201 · InstallmentPlan

  • idstringrequired
  • object"installment_plan"required
  • debtIdstringrequired
  • status"active" | "completed" | "canceled"required
  • amountCentsintegerrequired
    Agreed total amount
    -100000000000–100000000000
  • numberOfPaymentsintegerrequired
    -9007199254740991–9007199254740991
  • installmentCentsintegerrequired
    Monthly instalment
    -100000000000–100000000000
  • startDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paymentsMadeintegerrequired
    -9007199254740991–9007199254740991
  • paidCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • remainingCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • nextDueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • lastPaymentDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • scheduleArray<object>required
    Due dates (monthly)
    • numberintegerrequired
      -9007199254740991–9007199254740991
    • dueDatestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • notesstringrequired
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/installment-plans' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "debtId": "string",
  "amountCents": 0,
  "numberOfPayments": 1,
  "startDate": "2026-11-01",
  "notes": "string"
}'
Response 201
{
  "id": "string",
  "object": "installment_plan",
  "debtId": "string",
  "status": "active",
  "amountCents": 0,
  "numberOfPayments": 0,
  "installmentCents": 0,
  "startDate": "2026-11-01",
  "paymentsMade": 0,
  "paidCents": 0,
  "remainingCents": 0,
  "nextDueDate": "2026-11-01",
  "lastPaymentDate": "2026-11-01",
  "schedule": [
    {
      "number": 0,
      "dueDate": "2026-11-01",
      "amountCents": 0
    }
  ],
  "notes": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve instalment plan

GET/api/v1/installment-plans/{id}

With payment schedule (schedule), paid and outstanding amounts.

Permission: payments:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · InstallmentPlan

  • idstringrequired
  • object"installment_plan"required
  • debtIdstringrequired
  • status"active" | "completed" | "canceled"required
  • amountCentsintegerrequired
    Agreed total amount
    -100000000000–100000000000
  • numberOfPaymentsintegerrequired
    -9007199254740991–9007199254740991
  • installmentCentsintegerrequired
    Monthly instalment
    -100000000000–100000000000
  • startDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paymentsMadeintegerrequired
    -9007199254740991–9007199254740991
  • paidCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • remainingCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • nextDueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • lastPaymentDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • scheduleArray<object>required
    Due dates (monthly)
    • numberintegerrequired
      -9007199254740991–9007199254740991
    • dueDatestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • notesstringrequired
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/installment-plans/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "id": "string",
  "object": "installment_plan",
  "debtId": "string",
  "status": "active",
  "amountCents": 0,
  "numberOfPayments": 0,
  "installmentCents": 0,
  "startDate": "2026-11-01",
  "paymentsMade": 0,
  "paidCents": 0,
  "remainingCents": 0,
  "nextDueDate": "2026-11-01",
  "lastPaymentDate": "2026-11-01",
  "schedule": [
    {
      "number": 0,
      "dueDate": "2026-11-01",
      "amountCents": 0
    }
  ],
  "notes": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update instalment plan

PATCH/api/v1/installment-plans/{id}

Permission: payments:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Body (JSON) · InstallmentPlanUpdate

  • amountCentsinteger
    Amount in cents
    0–100000000000
  • numberOfPaymentsinteger
    1–120
  • startDatestring (date)
    Date (YYYY-MM-DD)
  • status"active" | "completed" | "canceled"
  • notesstring
    max. 2000 characters

Response 200 · InstallmentPlan

  • idstringrequired
  • object"installment_plan"required
  • debtIdstringrequired
  • status"active" | "completed" | "canceled"required
  • amountCentsintegerrequired
    Agreed total amount
    -100000000000–100000000000
  • numberOfPaymentsintegerrequired
    -9007199254740991–9007199254740991
  • installmentCentsintegerrequired
    Monthly instalment
    -100000000000–100000000000
  • startDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paymentsMadeintegerrequired
    -9007199254740991–9007199254740991
  • paidCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • remainingCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • nextDueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • lastPaymentDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • scheduleArray<object>required
    Due dates (monthly)
    • numberintegerrequired
      -9007199254740991–9007199254740991
    • dueDatestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • notesstringrequired
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/installment-plans/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "amountCents": 0,
  "numberOfPayments": 1,
  "startDate": "2026-11-01",
  "status": "active",
  "notes": "string"
}'
Response 200
{
  "id": "string",
  "object": "installment_plan",
  "debtId": "string",
  "status": "active",
  "amountCents": 0,
  "numberOfPayments": 0,
  "installmentCents": 0,
  "startDate": "2026-11-01",
  "paymentsMade": 0,
  "paidCents": 0,
  "remainingCents": 0,
  "nextDueDate": "2026-11-01",
  "lastPaymentDate": "2026-11-01",
  "schedule": [
    {
      "number": 0,
      "dueDate": "2026-11-01",
      "amountCents": 0
    }
  ],
  "notes": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Delete instalment plan

DELETE/api/v1/installment-plans/{id}

Also deletes the instalments recorded against it.

Permission: payments:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/installment-plans/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Instalments of an instalment plan

GET/api/v1/installment-plans/{id}/payments

Permission: payments:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200

  • object"list"required
  • dataArray<Payment>required
    • idstringrequired
    • object"payment"required
    • type"single" | "installment"required
      Single payment or instalment of an instalment plan
    • debtIdstringrequired
    • contactIdstring | nullrequired
    • installmentPlanIdstring | nullrequired
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • datestring (date)required
      Date (YYYY-MM-DD)
    • methodstringrequired
    • referencestringrequired
    • notesstringrequired
    • verifiedbooleanrequired
      Payment receipt verified (single payments only)
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/installment-plans/ID/payments' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "payment",
      "type": "single",
      "debtId": "string",
      "contactId": "string",
      "installmentPlanId": "string",
      "amountCents": 0,
      "date": "2026-11-01",
      "method": "string",
      "reference": "string",
      "notes": "string",
      "verified": false,
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ]
}

Record instalment

POST/api/v1/installment-plans/{id}/payments

Increases the number of instalments paid; once paid in full, the plan becomes completed. Event payment.received.

Permission: payments:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · InstallmentPaymentCreate

  • amountCentsintegerrequired
    Amount in cents
    0–100000000000
  • datestring (date)required
    Date (YYYY-MM-DD)
  • method"bank" | "cash" | "paypal" | "card" | "direct_debit" | "other"
    Default: "bank"
  • notesstring
    max. 2000 characters

Response 201 · Payment

  • idstringrequired
  • object"payment"required
  • type"single" | "installment"required
    Single payment or instalment of an instalment plan
  • debtIdstringrequired
  • contactIdstring | nullrequired
  • installmentPlanIdstring | nullrequired
  • amountCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • datestring (date)required
    Date (YYYY-MM-DD)
  • methodstringrequired
  • referencestringrequired
  • notesstringrequired
  • verifiedbooleanrequired
    Payment receipt verified (single payments only)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/installment-plans/ID/payments' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "amountCents": 0,
  "date": "2026-11-01",
  "method": "bank",
  "notes": "string"
}'
Response 201
{
  "id": "string",
  "object": "payment",
  "type": "single",
  "debtId": "string",
  "contactId": "string",
  "installmentPlanId": "string",
  "amountCents": 0,
  "date": "2026-11-01",
  "method": "string",
  "reference": "string",
  "notes": "string",
  "verified": false,
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Delete instalment

DELETE/api/v1/installment-plans/{id}/payments/{paymentId}

Permission: payments:write

Path parameters

  • idstringrequired
    max. 128 characters
  • paymentIdstringrequired
    max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/installment-plans/ID/payments/PAYMENTID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

List payments

GET/api/v1/payments

Individual payments and instalments from instalment plans (type), sorted by payment date in descending order.

Permission: payments:read

Query parameters

  • debtIdstring
    max. 128 characters
  • contactIdstring
    max. 128 characters
  • type"single" | "installment" | "all"
    Default: "all"
  • fromstring (date)
    Date (YYYY-MM-DD)
  • tostring (date)
    Date (YYYY-MM-DD)
  • limitinteger
    Number of entries (1–100)
    1–100 · Default: 25
  • cursorstring
    `nextCursor` of the previous page
    max. 500 characters

Response 200

  • object"list"required
  • dataArray<Payment>required
    • idstringrequired
    • object"payment"required
    • type"single" | "installment"required
      Single payment or instalment of an instalment plan
    • debtIdstringrequired
    • contactIdstring | nullrequired
    • installmentPlanIdstring | nullrequired
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • datestring (date)required
      Date (YYYY-MM-DD)
    • methodstringrequired
    • referencestringrequired
    • notesstringrequired
    • verifiedbooleanrequired
      Payment receipt verified (single payments only)
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
  • hasMorebooleanrequired
  • nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/payments' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "payment",
      "type": "single",
      "debtId": "string",
      "contactId": "string",
      "installmentPlanId": "string",
      "amountCents": 0,
      "date": "2026-11-01",
      "method": "string",
      "reference": "string",
      "notes": "string",
      "verified": false,
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Record payment

POST/api/v1/payments

Incoming payment for a debt. With installmentPlanId, it is posted as an instalment. markDebtPaid closes the debt. If “Payment confirmations” is enabled in the settings, the debtor receives an email. Event payment.received.

Permission: payments:write

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · PaymentCreate

  • debtIdstringrequired
    max. 128 characters
  • amountCentsintegerrequired
    Amount in cents
    0–100000000000
  • datestring (date)required
    Payment date, not in the future
  • method"bank" | "cash" | "paypal" | "card" | "direct_debit" | "other"
    Default: "bank"
  • referencestring
    max. 140 characters
  • notesstring
    max. 2000 characters
  • installmentPlanIdstring
    Record as an instalment of this instalment plan
    max. 128 characters
  • verifiedboolean
    Payment receipt verified (single payments only)
  • markDebtPaidboolean
    Then mark the debt as paid

Response 201 · Payment

  • idstringrequired
  • object"payment"required
  • type"single" | "installment"required
    Single payment or instalment of an instalment plan
  • debtIdstringrequired
  • contactIdstring | nullrequired
  • installmentPlanIdstring | nullrequired
  • amountCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • datestring (date)required
    Date (YYYY-MM-DD)
  • methodstringrequired
  • referencestringrequired
  • notesstringrequired
  • verifiedbooleanrequired
    Payment receipt verified (single payments only)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/payments' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "debtId": "string",
  "amountCents": 0,
  "date": "2026-11-01",
  "method": "bank",
  "reference": "string",
  "notes": "string",
  "installmentPlanId": "string",
  "verified": false,
  "markDebtPaid": false
}'
Response 201
{
  "id": "string",
  "object": "payment",
  "type": "single",
  "debtId": "string",
  "contactId": "string",
  "installmentPlanId": "string",
  "amountCents": 0,
  "date": "2026-11-01",
  "method": "string",
  "reference": "string",
  "notes": "string",
  "verified": false,
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Retrieve individual payment

GET/api/v1/payments/{id}

Instalments of an instalment plan: /installment-plans/{id}/payments.

Permission: payments:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · Payment

  • idstringrequired
  • object"payment"required
  • type"single" | "installment"required
    Single payment or instalment of an instalment plan
  • debtIdstringrequired
  • contactIdstring | nullrequired
  • installmentPlanIdstring | nullrequired
  • amountCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • datestring (date)required
    Date (YYYY-MM-DD)
  • methodstringrequired
  • referencestringrequired
  • notesstringrequired
  • verifiedbooleanrequired
    Payment receipt verified (single payments only)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/payments/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "id": "string",
  "object": "payment",
  "type": "single",
  "debtId": "string",
  "contactId": "string",
  "installmentPlanId": "string",
  "amountCents": 0,
  "date": "2026-11-01",
  "method": "string",
  "reference": "string",
  "notes": "string",
  "verified": false,
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Update individual payment

PATCH/api/v1/payments/{id}

Notes, reference, payment method and the verified flag are changed directly. Amount or date of a booked payment (booking engine) are corrected by a reversal and a new booking: the response contains the new payment with a new id, the old one remains with its reversal (events payment.reversed and payment.received).

Permission: payments:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Body (JSON) · PaymentUpdate

  • amountCentsinteger
    Amount in cents
    0–100000000000
  • datestring (date)
    Date (YYYY-MM-DD)
  • method"bank" | "cash" | "paypal" | "card" | "direct_debit" | "other"
  • referencestring
    max. 140 characters
  • notesstring
    max. 2000 characters
  • verifiedboolean
    Payment receipt verified

Response 200 · Payment

  • idstringrequired
  • object"payment"required
  • type"single" | "installment"required
    Single payment or instalment of an instalment plan
  • debtIdstringrequired
  • contactIdstring | nullrequired
  • installmentPlanIdstring | nullrequired
  • amountCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • datestring (date)required
    Date (YYYY-MM-DD)
  • methodstringrequired
  • referencestringrequired
  • notesstringrequired
  • verifiedbooleanrequired
    Payment receipt verified (single payments only)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/payments/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "amountCents": 0,
  "date": "2026-11-01",
  "method": "bank",
  "reference": "string",
  "notes": "string",
  "verified": false
}'
Response 200
{
  "id": "string",
  "object": "payment",
  "type": "single",
  "debtId": "string",
  "contactId": "string",
  "installmentPlanId": "string",
  "amountCents": 0,
  "date": "2026-11-01",
  "method": "string",
  "reference": "string",
  "notes": "string",
  "verified": false,
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Delete individual payment

DELETE/api/v1/payments/{id}

Booked payments (booking engine) are not deleted but reversed (payment.reversed); 409 payment_already_reversed on a repeated call, 409 payment_not_reversible for reversals. Older payments without a booking are deleted (payment.deleted).

Permission: payments:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/payments/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"