Skip to content

Commit 450638e

Browse files
docs(withdrawal): clarify beneficiary vs payment-instruction lifecycle (#23)
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) <noreply@anthropic.com>
1 parent 8b5a7ed commit 450638e

1 file changed

Lines changed: 3 additions & 3 deletions

File tree

journeys/withdrawal.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ Withdrawals move funds out of an account to an external destination — a bank a
1515
## Steps
1616

1717
<Steps>
18-
<Step title="Register a beneficiary (one time per destination)">
19-
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.
18+
<Step title="Register a beneficiary and add a payment instruction">
19+
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.
2020

2121
```bash
2222
curl --request POST \
@@ -45,7 +45,7 @@ Withdrawals move funds out of an account to an external destination — a bank a
4545
}'
4646
```
4747

48-
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.
48+
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.
4949
</Step>
5050

5151
<Step title="Create a quote">

0 commit comments

Comments
 (0)