{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/smart_collections_brazil/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial","admonition"]},"type":"markdown"},"seo":{"title":"Smart Collections","description":"Belvo provides open finance products for Latin America that allow you to securely access and aggregate financial data as well as accept and issue bank-to-bank payments","siteUrl":"https://developers.belvo.com/","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"smart-collections","__idx":0},"children":["Smart Collections"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Beta"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Smart Collections is currently in Beta. Some contracts on this page are still being confirmed with our engineering team, so treat them as provisional and expect refinements before general availability, including:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhook payloads and event codes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["API reference updates for the Collection Instructions, Payment Authorization, and Charge endpoints"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Field names and documentation improvements (terminology, diagrams)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact your Belvo account manager to join the Beta program."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With Belvo's Smart Collections you can delegate balance monitoring to Belvo and trigger a Pix Charge when your user's account has sufficient funds. Instead of polling your user's balance yourself, you tell Belvo the amounts you want to collect as well as the balance conditions to wait for and Belvo watches the account in the background, notifying you when it's time to collect."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Regulatory Disclosure"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In accordance with BACEN ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resolução Conjunta nº 17"]},", Belvo operates as a regulated ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Iniciador de Transação de Pagamento (ITP)"]},". To ensure compliance with transparency and branding requirements:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Belvo Responsibility:"]}," Belvo ensures that all elements and disclosures within the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Belvo Widget"]}," are fully compliant with BACEN regulations and communicates any required changes to partners."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partner Responsibility:"]}," Partners must clearly state in their UI/service that their company is not the regulated payment entity and identify ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Belvo"]}," as the provider responsible for the payment initiation."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Smart Collections combines two Belvo products across two phases. The diagram below shows the three main steps of a complete integration."]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n participant Client as Your application\n participant Aggregation as Belvo Aggregation API\n participant Payments as Belvo Payments API\n\n rect rgba(0, 100, 255, .05)\n Note over Client, Payments: 1. Collection Instruction setup\n\n Client->>Aggregation: POST /api/collection-instructions/\n Aggregation-->>Client: 201 Created\n\n loop Background balance monitoring\n Note right of Aggregation: Belvo checks the linked account balance. Once your criteria are met, you'll receive a webhook you can act on. See step 3.\n end\n end\n\n rect rgba(0, 200, 100, .05)\n Note over Client, Payments: 2. Payment Authorization setup\n\n Client->>Payments: POST /payments/br/payment-authorizations/\n Payments-->>Client: 201 Created (authorization_url)\n\n Note right of Payments: User approves the authorization at their bank\n\n Payments->>Client: Webhook: PAYMENT_AUTHORIZATION\n Client->>Payments: GET /payments/br/payment-authorizations/{id}/\n Payments-->>Client: 200 OK (status: AUTHORIZED)\n end\n\n rect rgba(255, 150, 0, .05)\n Note over Client, Payments: 3. Charge creation\n\n Aggregation->>Client: Webhook: item_ready_to_charge\n Note over Client, Payments: Also requires an AUTHORIZED Payment Authorization from step 2\n\n Client->>Payments: POST /payments/br/payment-authorizations/{id}/charges/\n Payments-->>Client: 201 Created\n\n Payments->>Client: Webhook: CHARGE\n Client->>Payments: GET /payments/br/payment-authorizations/{id}/charges/{charge_id}/\n Payments-->>Client: 200 OK\n end\n","diagramHtml":"
Belvo Payments APIBelvo Aggregation APIYour applicationBelvo Payments APIBelvo Aggregation APIYour application1. Collection Instruction setupBelvo checks the linked account balance. Once your criteria are met, you'll receive a webhook you can act on. See step 3.loop[Background balance monitoring]2. Payment Authorization setupUser approves the authorization at their bank3. Charge creationAlso requires an AUTHORIZED Payment Authorization from step 2POST /api/collection-instructions/201 CreatedPOST /payments/br/payment-authorizations/201 Created (authorization_url)Webhook: PAYMENT_AUTHORIZATIONGET /payments/br/payment-authorizations/{id}/200 OK (status: AUTHORIZED)Webhook: item_ready_to_chargePOST /payments/br/payment-authorizations/{id}/charges/201 CreatedWebhook: CHARGEGET /payments/br/payment-authorizations/{id}/charges/{charge_id}/200 OK
"},"children":["sequenceDiagram\n participant Client as Your application\n participant Aggregation as Belvo Aggregation API\n participant Payments as Belvo Payments API\n\n rect rgba(0, 100, 255, .05)\n Note over Client, Payments: 1. Collection Instruction setup\n\n Client->>Aggregation: POST /api/collection-instructions/\n Aggregation-->>Client: 201 Created\n\n loop Background balance monitoring\n Note right of Aggregation: Belvo checks the linked account balance. Once your criteria are met, you'll receive a webhook you can act on. See step 3.\n end\n end\n\n rect rgba(0, 200, 100, .05)\n Note over Client, Payments: 2. Payment Authorization setup\n\n Client->>Payments: POST /payments/br/payment-authorizations/\n Payments-->>Client: 201 Created (authorization_url)\n\n Note right of Payments: User approves the authorization at their bank\n\n Payments->>Client: Webhook: PAYMENT_AUTHORIZATION\n Client->>Payments: GET /payments/br/payment-authorizations/{id}/\n Payments-->>Client: 200 OK (status: AUTHORIZED)\n end\n\n rect rgba(255, 150, 0, .05)\n Note over Client, Payments: 3. Charge creation\n\n Aggregation->>Client: Webhook: item_ready_to_charge\n Note over Client, Payments: Also requires an AUTHORIZED Payment Authorization from step 2\n\n Client->>Payments: POST /payments/br/payment-authorizations/{id}/charges/\n Payments-->>Client: 201 Created\n\n Payments->>Client: Webhook: CHARGE\n Client->>Payments: GET /payments/br/payment-authorizations/{id}/charges/{charge_id}/\n Payments-->>Client: 200 OK\n end\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 1: Collection Instruction setup."]}," You create a Collection Instruction describing the amount you want to collect and the balance conditions to wait for. Belvo then monitors the linked account in the background, so you don't have to poll anything yourself. Once the balance meets your criteria, Belvo sends an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item_ready_to_charge"]}," webhook, which is what triggers step 3. ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/smart_collections_brazil/smart-collections-balance-checking","target":"_blank"},"children":["Phase 1: Balance Checking"]}," covers Step 1."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 2: Payment Authorization setup."]}," Independently of step 1, and at any point before you need to charge, you create a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments_brazil/payments-brazil-smart-transfers-overview","target":"_blank"},"children":["Smart Transfers"]}," Payment Authorization for the payer. Smart Transfers moves funds between accounts held by the same person or company, so the account that receives the funds must be held by the payer. Belvo notifies you when its status changes with a webhook, but because these are Payments-BR.V2 webhooks, the notification itself doesn't carry the status. You fetch the authorization with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," request to confirm it's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZED"]}," and ready to use."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 3: Charge creation."]}," When you collect through a Collection Instruction, you wait until you've received ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item_ready_to_charge"]}," and confirmed the authorization is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZED"]},", and then you trigger a Charge. (A one-off Charge without a Collection Instruction only needs the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZED"]}," authorization, see below.) Belvo processes the Pix payment and sends another webhook when the Charge's status changes. As with the authorization, you fetch the Charge with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," request to see whether it succeeded or failed. ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/smart_collections_brazil/smart-collections-payments","target":"_blank"},"children":["Phase 2: Payment Creation"]}," covers Steps 2 and 3."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"The two phases are independent"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Phase 1 and Phase 2 are loosely coupled. Belvo does not link the two together, so store the IDs of your items, authorizations, and Charges together to correlate them in your own system."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In fact, Phase 1 is optional. With an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZED"]}," Payment Authorization you can trigger a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/smart_collections_brazil/smart-collections-payments","target":"_blank"},"children":["Charge"]}," directly, a one-off collection, without creating a Collection Instruction at all."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-options","__idx":2},"children":["Integration options"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Setting up Smart Collections combines two integration paths. Use the OFDA Widget to onboard users and create a Link for balance monitoring, and the Payments API (",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments_brazil/payments-brazil-smart-transfers-api-guide","target":"_blank"},"children":["Direct API (Smart Transfers)"]},") to create Payment Authorizations and Charges."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To manage Collection Instructions, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/smart_collections_brazil/smart-collections-balance-checking","target":"_blank"},"children":["Phase 1: Balance Checking"]}," and the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/belvoopenapispec/collection-instructions-(brazil)/createcollectioninstructionbrazil","target":"_blank"},"children":["Collection Instructions API reference"]},"."]}]},"headings":[{"value":"Smart Collections","id":"smart-collections","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Integration options","id":"integration-options","depth":2}],"frontmatter":{"seo":{"title":"Smart Collections"}},"lastModified":"2026-10-20T20:55:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/smart_collections_brazil/smart-collections-overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}