Withdrawing Funds

Withdrawing refers to sending fiat or crypto to external entities.

In general, there are 4 steps to performing a withdrawal from an account:

1. Create a Counterparty for the external entity receiving the funds.
2. Create a Withdrawal using counterparty id from step 1.
3. Accept the Withdrawal with id from step 2.
4. (If required) Upload documents to withdrawal object if RFI occurs.

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

Sometimes, Rail may request additional information or context related to a withdrawal. Often these RFIs relate to having to provide a proof of payment (e.g. invoice) related to the withdrawal. In order to satisfy an RFI, clients will 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. Failture to satisfy the RFI will result in delays in withdrawal processing times or withdrawals being rejected.

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

Withdrawal Lifecycle

Scenario 1 - Withdrawal Lifecycle - Happy Path

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

Scenario 2 - Withdrawal Lifecycle - RFI

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