# Withdrawing Funds

Withdrawing refers to sending fiat or crypto to external entities.

There are 4 steps to performing a withdrawal from an account:

1. Create a [Counterparty](/guides/counterparties) for the external entity receiving the funds and have it approved.
2. Create a [Withdrawal](/api-docs/openapi/rail-spec#operation/createWithdrawal) using counterparty
3. Accept the [Withdrawal](/api-docs/openapi/rail-spec#operation/acceptWithdrawal)
4. (If required) Upload documents to withdrawal object if RFI occurs.


# Validation

- The purpose `PERSONAL_ACCOUNT` is only valid with [counterparties](/api-docs/openapi/rail-spec#operation/createCounterparty#tag/Counterparty/operation/createCounterparty) that have the `profile.relationship_to_customer` field set as `SELF`. `PERSONAL_ACCOUNT` is not a valid purpose for payments to 3rd parties.


# Withdrawal Status

The Retrieve Withdrawal Status endpoint is used to understand the current state of a withdrawal and to manage RFIs.

# RFIs - Requests for Information

Rail may request additional information or context related to a withdrawal. Often RFIs are to provide a proof of payment (e.g. invoice) related to the withdrawal.

Once trigger, **ALL RFIs MUST** be responded to. In order to satisfy an RFI, clients must upload a document (invoice) to the withdrawals. Once the document is uploaded and accepted, the withdrawal will be processed and funds sent to ultimate beneficiary.

Failure to satisfy the RFI will result in delays in withdrawal processing times or withdrawals being rejected. Consistent refusal to complete RFIs may result in offboarding at the customer level, and extreme cases, full offboarding at the client level.

## Managing RFIs

### Step 1 - RFI Requested

If Rail requires more information on a withdrawal it will request a document to be uploaded to the withdrawal.

### Step 2 - RFI Notification (Webhook)

Client can subscribe to the `WITHDRAWAL_CHANGES_REQUESTED` webhook event to receive realtime notifcations when an RFI occurs. This webhook contains the withdrawal id the RFI is related to.

### Step 3 - Understanding RFI Requirement (Retrieve Withdrawal Status)

Clients can use the Retrive Withdrawal Status endpoint to understand what is required to satisfy the RFI. The response of Retrieve Withdrawal Status will show that the status of the withdrawal is `CHANGES_REQUESTED`. The response will also list the 'errors' that need to be satisfied before the withdrawal can continue processing. For withdrawals, the request will usually require clients to upload a proof of payment (invoice) to the withdrawal in question.

The `document_errors` block of the response will contain a `document_id` for clients to upload the invoice to.

### Step 4 -  Repond to RFI (Upload Document to Withdrawal)

To upload a document to a withdrawal, use the [Upload Document API](/api-docs/openapi/rail-spec#operation/uploadDocument) passing in the `document_id` from the Retrieve Withdrawal Status response, along with the document file.

### Step 5 - Finish Processing the Withdrawal

Once the document is uploaded, and Rail is satisfied with the information provided, the status of the withdrawal will be updated to `IN_PROGRESS` and the withdrawal will be processed. Once the withdrawal is processed the withdrawal status will change to `EXECUTED`.

## Sandbox RFI testing

In the sandbox, all FIAT withdrawals with an amount above 100 USD will trigger the Pre-Accept RFI scenario.

# Withdrawal Lifecycle

## Scenario 1 - Withdrawal Lifecycle - Happy Path

Scenario where the withdrawal lifecycle executes without any RFI being required.

| Action | Withdrawal Status |
|  --- | --- |
| Request withdrawal | `REQUESTED` |
| (Optional) Client uploads document to withdrawal. | `REQUESTED` |
| Accept withdrawal | `ACCEPTED` |
| Withdrawal waiting for approval | `AUTHORIZED` |
| Withdrawal is approved | `APPROVED` |
| Withdrawal begins processing | `IN_PROGRESS` |
| Withdrawal successfully sent | `EXECUTED` |


Withdrawal Lifecycle - Happy Path
## Scenario 2 - Withdrawal Lifecycle - Pre-Accept RFI

Scenario where the Rail requires additional information to be provided on the withdrawal.

| Action | Withdrawal Status |
|  --- | --- |
| Request withdrawal | `REQUESTED` |
| RFI is required for withdrawal | `CHANGES_REQUESTED` |
| Client uploads document to withdrawal. Withdrawal can now be Accepted. | `REQUESTED` |
| Accept withdrawal | `ACCEPTED` |
| Withdrawal waiting for approval | `AUTHORIZED` |
| Withdrawal is approved | `APPROVED` |
| Withdrawal begins processing | `IN_PROGRESS` |
| Withdrawal successfully sent | `EXECUTED` |


Withdrawal Lifecycle - Pre-Accept RFI
## Scenario 3 - Withdrawal Lifecycle - Post-Accept RFI

Scenario where the Rail requires additional information to be provided on the withdrawal.

| Action | Withdrawal Status |
|  --- | --- |
| Request withdrawal | `REQUESTED` |
| Accept withdrawal | `ACCEPTED` |
| Withdrawal waiting for approval | `AUTHORIZED` |
| Withdrawal is approved | `APPROVED` |
| Withdrawal begins processing | `IN_PROGRESS` |
| RFI is required for withdrawal | `CHANGES_REQUESTED` |
| Client uploads all documents. that is accepted. RFI review begins. | `IN_REVIEW` |
| RFI response is accepted. Withdrawal begins processing again. | `IN_PROGRESS` |
| Withdrawal successfully sent | `EXECUTED` |


Withdrawal Lifecycle - Post-Accept RFI