Error

A valid request URL is required to generate request examples

{
  "collected": "150.00",
  "transactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Collect a balance's open fee debts

Settles the balance’s open fee debts oldest first from its available funds, up to maxAmount and never more than it owes, in one transaction. It charges no new fee. Without an error, it collects nothing when the balance has no available funds or is blocked, cannot send, is closing or closed, deleted, debit-direction or external, and it stops at the first debt whose fee account is blocked, cannot receive, is closing or closed, deleted, debit-direction, external, in overdraft or of another asset. When nothing is settled the response is collected 0 and no transaction is created. With X-Idempotency a retry returns the first collection; an answer that settled nothing is not kept. Without it every call is a new collection. A collection transaction cannot be reverted.

POST

/

v2

/

organizations

/

{organization_id}

/

ledgers

/

{ledger_id}

/

fee-debts

/

collect

Error

A valid request URL is required to generate request examples

{
  "collected": "150.00",
  "transactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

Idempotency key to safely retry the collection; a retry returns the first collection (an answer that settled nothing is not kept), another request under the same key answers 409 (0084). Without it every call is a new collection.

X-TTL

string

Idempotency slot TTL in seconds (default 300)

Path Parameters

organization_id

string

required

Organization ID (UUID)

ledger_id

string

required

Ledger ID (UUID)

Body

application/json

accountAlias

string

required

Alias of the debtor account.

Maximum string length: 100

Example:

"@customer"

balanceKey

string

Key of the debtor balance; absent means the default balance.

Maximum string length: 100

Example:

"default"

maxAmount

string

Most the collection may settle, greater than zero; absent means everything the balance owes.

Example:

"150.00"

Response

OK

collected

string

required

Amount settled, oldest debt first; 0 when the balance had no open debt, no available funds, or cannot pay a debt's fee account.

Example:

"150.00"

transactionId

string<uuid>

Transaction recording the settlement, absent when nothing was collected.