Skip to content

docs(withdrawal): clarify beneficiary vs payment-instruction lifecycle #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
diegopereira90 wants to merge 1 commit into
base: main
Choose a base branch
from
+3 −3
Open

docs(withdrawal): clarify beneficiary vs payment-instruction lifecycle #23

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions journeys/withdrawal.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

## Overview

Withdrawals move funds out of an account to an external destination — a bank account (PIX, TED) or a crypto wallet. Every withdrawal references a quote that locks the FX rate (or a 1:1 spot for same-asset) and a previously approved beneficiary with at least one payment instruction.

Check warning on line 8 in journeys/withdrawal.mdx

View check run for this annotation

Mintlify / Mintlify Validation (tracefinance) - vale-spellcheck

journeys/withdrawal.mdx#L8 

Did you really mean 'crypto'?

## Prerequisites

Expand All @@ -15,8 +15,8 @@
## Steps

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

Check warning on line 19 in journeys/withdrawal.mdx

View check run for this annotation

Mintlify / Mintlify Validation (tracefinance) - vale-spellcheck

journeys/withdrawal.mdx#L19 

Did you really mean 'crypto'?

```bash
curl --request POST \
Expand Down Expand Up @@ -45,7 +45,7 @@
}'
```

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.
</Step>

<Step title="Create a quote">
Expand Down
Loading