Merge branch 'main' into docs/payment-instruction-event-state

Author: diegopereira90

journeys/withdrawal.mdx

@@ -15,8 +15,8 @@ Withdrawals move funds out of an account to an external destination — a bank a
 ## 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.
 
     ```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.
   </Step>
 
   <Step title="Create a quote">