From 6389f408a4efb3185ee49f551e43310aa6592bf0 Mon Sep 17 00:00:00 2001 From: Diego Pereira Date: Fri, 8 May 2026 10:12:19 -0300 Subject: [PATCH] docs(withdrawal): clarify beneficiary vs payment-instruction lifecycle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two corrections to the "Register a beneficiary" step in the withdrawal journey, addressing the open item from Leone's docs review: 1. The beneficiary record itself has no status. Status, review, and webhook events are tracked at the payment-instruction level. Re-word to make that explicit and to frame the beneficiary as a reusable record across destinations — the first instruction on a new beneficiary triggers the full compliance review, subsequent instructions on the same beneficiary go through a reduced check (without exposing the internal rules in detail). 2. List the webhook events emitted at this step: BENEFICIARY_PAYMENT_INSTRUCTION_CREATED, _APPROVED, _REJECTED — so integrators know what to subscribe to for the review outcome. Mirrors what the "Submit the operation" step already does for OPERATION_REQUESTED / _COMPLETED / _FAILED. Step title also adjusted from "Register a beneficiary (one time per destination)" — that subtitle was misleading since one beneficiary can carry multiple payment instructions over time. New title: "Register a beneficiary and add a payment instruction". Co-Authored-By: Claude Opus 4.7 (1M context) --- journeys/withdrawal.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/journeys/withdrawal.mdx b/journeys/withdrawal.mdx index 5645eb5..aa3e16b 100644 --- a/journeys/withdrawal.mdx +++ b/journeys/withdrawal.mdx @@ -15,8 +15,8 @@ Withdrawals move funds out of an account to an external destination — a bank a ## Steps - - Submit the holder details and the payment instruction (PIX, bank account, or crypto wallet). The beneficiary starts in `PENDING_REVIEW` status and transitions asynchronously to `APPROVED` or `REJECTED` after compliance review. + + Submit the holder details and the payment instruction (PIX, bank account, or crypto wallet). The beneficiary record itself has no status — it is created once and reused across destinations. Each payment instruction is reviewed individually: it starts in `PENDING_REVIEW` on creation and transitions asynchronously to `APPROVED` or `REJECTED`. The first instruction on a new beneficiary triggers the full compliance review; instructions added later to the same beneficiary go through a reduced check. ```bash curl --request POST \ @@ -45,7 +45,7 @@ Withdrawals move funds out of an account to an external destination — a bank a }' ``` - The response returns the beneficiary with its `id` and the created `paymentInstruction.id`. Wait until status is `APPROVED` before continuing — only approved instructions can be used in a withdrawal. + The response returns the beneficiary with its `id` and the created `paymentInstruction.id`. A `BENEFICIARY_PAYMENT_INSTRUCTION_CREATED` webhook fires immediately, then either `BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED` or `BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED` once the review completes — subscribe to track the outcome. Only `APPROVED` instructions can be used in a withdrawal.