{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/smart_collections_brazil/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial","admonition"]},"type":"markdown"},"seo":{"title":"Phase 2: Payment Creation (Direct API)","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":"phase-2-payment-creation-direct-api","__idx":0},"children":["Phase 2: Payment Creation (Direct API)"]},{"$$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":["In Phase 2 of Smart Collections, you collect the funds with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Smart Transfers"]},", Belvo's Payments product for moving money between accounts held by the same user. You create a Smart Transfers ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment Authorization"]}," once, and then trigger a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Charge"]}," each time Phase 1 tells you there are enough funds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The full step-by-step integration, with every field, response, and status, is in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments_brazil/payments-brazil-smart-transfers-api-guide","target":"_blank"},"children":["Direct API (Smart Transfers)"]}," guide. This page only covers what's specific to using Smart Transfers together with ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/smart_collections_brazil/smart-collections-balance-checking","target":"_blank"},"children":["Phase 1: Balance Checking"]},"."]},{"$$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 Client->>Payments: POST /payments/br/payment-authorizations/\n Note over Client, Payments: Your user approves it at their bank\n Payments->>Client: Webhook: PAYMENT_AUTHORIZATION\n Client->>Payments: GET /payments/br/payment-authorizations/{id}/\n Payments-->>Client: 200 OK (status: AUTHORIZED)\n\n Aggregation->>Client: Webhook: item_ready_to_charge (data.amount)\n Client->>Payments: POST /payments/br/payment-authorizations/{id}/charges/\n Payments-->>Client: 201 Created\n Payments->>Client: Webhook: CHARGE\n Client->>Payments: GET /payments/br/payment-authorizations/{id}/charges/{charge_id}/\n Payments-->>Client: 200 OK (status: SETTLED or FAILED)\n","diagramHtml":"
Belvo Payments APIBelvo Aggregation APIYour applicationBelvo Payments APIBelvo Aggregation APIYour applicationYour user approves it at their bankPOST /payments/br/payment-authorizations/Webhook: PAYMENT_AUTHORIZATIONGET /payments/br/payment-authorizations/{id}/200 OK (status: AUTHORIZED)Webhook: item_ready_to_charge (data.amount)POST /payments/br/payment-authorizations/{id}/charges/201 CreatedWebhook: CHARGEGET /payments/br/payment-authorizations/{id}/charges/{charge_id}/200 OK (status: SETTLED or FAILED)
"},"children":["sequenceDiagram\n participant Client as Your application\n participant Aggregation as Belvo Aggregation API\n participant Payments as Belvo Payments API\n\n Client->>Payments: POST /payments/br/payment-authorizations/\n Note over Client, Payments: Your user approves it at their bank\n Payments->>Client: Webhook: PAYMENT_AUTHORIZATION\n Client->>Payments: GET /payments/br/payment-authorizations/{id}/\n Payments-->>Client: 200 OK (status: AUTHORIZED)\n\n Aggregation->>Client: Webhook: item_ready_to_charge (data.amount)\n Client->>Payments: POST /payments/br/payment-authorizations/{id}/charges/\n Payments-->>Client: 201 Created\n Payments->>Client: Webhook: CHARGE\n Client->>Payments: GET /payments/br/payment-authorizations/{id}/charges/{charge_id}/\n Payments-->>Client: 200 OK (status: SETTLED or FAILED)\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-create-the-payment-authorization-early","__idx":1},"children":["1. Create the Payment Authorization early"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the Smart Transfers Payment Authorization ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["in parallel"]}," with your Phase 1 Collection Instruction, so that it's already ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZED"]}," when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item_ready_to_charge"]}," arrives. Follow ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments_brazil/payments-brazil-smart-transfers-api-guide#create-a-payment-authorization","target":"_blank"},"children":["Create a Payment Authorization"]},", and keep these points in mind:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["One authorization, many Charges."]}," Create one authorization per user and reuse it for every Charge. Size ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_allowed_amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_transaction_limit"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["periodic_limits"]}," to cover the items you expect to collect."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The beneficiary must be held by the user."]}," Smart Transfers only moves funds between accounts held by the same person (same CPF) or company (same CNPJ root)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use the same bank as the Link."]}," Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payer.institution"]}," to the payments institution that matches the bank of the Link you monitor in Phase 1. Belvo can't check this for you, because the authorization doesn't reference the Link."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"charge-the-account-you-monitor","__idx":2},"children":["Charge the account you monitor"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Phase 1, Belvo checks the balance of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["every"]}," account the user shared in their data consent, and sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item_ready_to_charge"]}," as soon as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["any one"]}," of them has enough funds. The webhook doesn't say which account it was."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To make sure Charges debit the account you monitor, create the authorization with that account's details in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payer.account_details"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_type"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ispb"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issuer"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]},"). You can take ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issuer"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]}," from the account's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agency"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]}," in Banking Aggregation. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments_brazil/payments-brazil-smart-transfers-api-guide#debit-a-specific-account","target":"_blank"},"children":["Debit a specific account"]},". Otherwise, your user chooses the account at their bank, and it may not be the one whose balance was checked."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-charge-when-item_ready_to_charge-arrives","__idx":3},"children":["2. Charge when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item_ready_to_charge"]}," arrives"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you receive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item_ready_to_charge"]},", check that the authorization is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZED"]},", and then ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments_brazil/payments-brazil-smart-transfers-api-guide#create-a-charge","target":"_blank"},"children":["create a Charge"]}," against it:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," to the webhook's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.amount"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]}," to today, so the funds are collected while they're available."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_id"]}," to a UUID you store alongside the item. Belvo doesn't link Collection Instructions, authorizations, and Charges to each other, and a Charge's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_id"]}," must be a UUID, so the item's own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_id"]}," can only be reused if it's a UUID too."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Phase 1 is optional"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You don't need a Collection Instruction to charge. With an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZED"]}," Payment Authorization you can create a Charge at any time. Phase 1 is only needed when you want Belvo to tell you when the account has enough funds."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-follow-the-charge","__idx":4},"children":["3. Follow the Charge"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Belvo sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHARGE"]}," webhook each time the Charge's status changes. Fetch the Charge to read it: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SETTLED"]}," means the funds left the user's account; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," means they didn't, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_reason_code"]}," tells you why (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INSUFFICIENT_FUNDS"]}," if the balance dropped after Phase 1 checked it)."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"A failed Charge doesn't restart Phase 1"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once an item reaches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item_ready_to_charge"]},", Belvo stops monitoring it, even if the Charge you create later fails. To try again, create a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["new"]}," Collection Instruction for that amount. Reusing the same item ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_id"]}," is fine."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":5},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Correlate everything with your own IDs."]}," Store the item ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", the authorization ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", and the Charge ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (and your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_id"]},"s) together, so you can reconstruct which item each Charge settled."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2XX"]}," from your webhook endpoints quickly."]}," Process business logic asynchronously so you don't time out and trigger retries."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reconcile items that never produce a Charge."]}," Phase 1 sends no webhook when an item's windows end without enough funds. Track your items and follow up on any that go stale. You can ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/smart_collections_brazil/smart-collections-balance-checking#check-the-status-of-your-items","target":"_blank"},"children":["check each item's status"]}," to see how it ended."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Avoid duplicate Charges."]}," Smart Transfers doesn't support idempotency keys yet. If a Charge request times out, list the authorization's Charges and look for your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_id"]}," before you retry."]}]},"headings":[{"value":"Phase 2: Payment Creation (Direct API)","id":"phase-2-payment-creation-direct-api","depth":1},{"value":"1. Create the Payment Authorization early","id":"1-create-the-payment-authorization-early","depth":2},{"value":"Charge the account you monitor","id":"charge-the-account-you-monitor","depth":3},{"value":"2. Charge when item_ready_to_charge arrives","id":"2-charge-when-item_ready_to_charge-arrives","depth":2},{"value":"3. Follow the Charge","id":"3-follow-the-charge","depth":2},{"value":"Best practices","id":"best-practices","depth":2}],"frontmatter":{"seo":{"title":"Phase 2: Payment Creation (Direct API)"}},"lastModified":"2026-10-20T20:55:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/smart_collections_brazil/smart-collections-payments","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}