BEbelvo
Collection Instructions (Brazil)

Create a collection instruction

Changed on

Create a collection instruction for a user's Link. While an item's collection window is open, Belvo checks the balances of the user's accounts several times a day. When one account has at least the item's amount plus BRL 0.01, Belvo sets the item to CHARGE_SETTLED and sends you the item_ready_to_charge webhook. You then create the Charge yourself, using Payments (Brazil). For every item status and the webhook payload, see the <a href="https://developers.belvo.com/products/smart_collections_brazil/smart-collections-statuses-and-webhooks" target="_blank">Smart Collections statuses and webhooks</a> article.

Before you send the request, check that:

  • The link_id is an active, confirmed Link of your organization, with exactly one data consent.
  • Every item has at least one collection window that ends in the future. If one item doesn't, Belvo rejects the whole request.
  • Each policy amount is the same as its item's amount. Belvo doesn't use the policy amount yet.

This request is not idempotent, and external_id is not checked for uniqueness. If you retry after a timeout, first list your collection instructions to check whether the first request created one.

Errors: Belvo returns a 400 error only for problems with link_id or a body that is not valid JSON. Any other problem returns a 500 error, including a body that doesn't match the schema, an item with no window that ends in the future, a Link that doesn't have exactly one data consent, and a failure to read the Link's accounts.

post/api/collection-instructions/

Request

Request body

link_idstring uuid required

The link.id of the user's Open Finance Data Aggregation Link. Belvo reads the balances of the accounts shared through this Link.

The Link must belong to your organization, be active, and be confirmed. It must also have exactly one data consent.

Example request

{
  "link_id": "3b979abb-fd60-4d15-a655-8f462ca4ea8f",
  "items": [
    {
      "amount": "150.00",
      "external_id": "invoice-2026-11-0042",
      "collection_policies": [
        {
          "start_date": "2026-11-05",
          "end_date": "2026-11-10",
          "amount": "150.00"
        }
      ]
    }
  ]
}

Response

Created

idstring uuid required

The unique identifier of the collection instruction. Use it to get or cancel the instruction.

link_idstring uuid required

The link.id whose accounts Belvo monitors for this instruction.

status'PROCESSING' | 'COMPLETED' | 'CANCELLED' required

The status of the collection instruction. Can be one of:

  • PROCESSING: The instruction was created. It stays in this status until you cancel it, even after every item has reached a final status. Check each item's status to see how monitoring ended.
  • COMPLETED: Reserved for future use. Belvo does not currently set this status.
  • CANCELLED: You cancelled the instruction. Any items that were still PENDING or PROCESSING were cancelled too.
created_atstring date-time required

The date and time, in ISO-8601 format (UTC), when Belvo created the instruction.

updated_atstring date-time required

The date and time, in ISO-8601 format (UTC), when the instruction's status last changed.

Example response

{
  "id": "c2a6f1d4-7b3e-4f5a-9c8d-1e2f3a4b5c6d",
  "link_id": "3b979abb-fd60-4d15-a655-8f462ca4ea8f",
  "status": "PROCESSING",
  "created_at": "2026-11-04T14:30:12.418230Z",
  "updated_at": "2026-11-04T14:30:12.418230Z",
  "items": [
    {
      "id": "8f14e45f-ceea-4e67-a3f2-2a1b9c3d7e10",
      "amount": "150.00",
      "external_id": "invoice-2026-11-0042",
      "status": "PENDING",
      "created_at": "2026-11-04T14:30:12.418230Z",
      "updated_at": "2026-11-04T14:30:12.418230Z",
      "collection_policies": [
        {
          "id": "5d41402a-bc4b-4a76-b971-9d911017c592",
          "start_date": "2026-11-05",
          "end_date": "2026-11-10",
          "amount": "150.00",
          "created_at": "2026-11-04T14:30:12.418230Z"
        }
      ]
    }
  ]
}

Changes