# Payments

There are 2 types of payments at Rail

- Collections
- Payouts (Coming soon)


# Payments - Collections

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

1. Create a [Counterparty](/guides/counterparties) for the external entity sending the funds and have it approved.
2. Create a [Payment](/api-docs/openapi/rail-spec#operation/createPayments) using counterparty from step 1.
3. Accept the [Payment](/api-docs/openapi/rail-spec#operation/acceptPayments) to received the paymnt deposit instructions.
4. (If required) Upload documents to payment object if RFI occurs.


# Payment Status

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

# RFIs - Requests for Information

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

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

Failure to satisfy the RFI will result in delays in payment processing times or payments 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 payment it will request a document to be uploaded to the payment.

### Step 2 - RFI Notification (Webhook)

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

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

Clients can use the Retrive Payment Status endpoint to understand what is required to satisfy the RFI. The response of Retrieve Payment Status will show that the status of the payment is `CHANGES_REQUESTED`. The response will also list the 'errors' that need to be satisfied before the payment can continue processing. For payments, the request will usually require clients to upload a proof of payment (invoice) to the payment 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 Payment)

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

### Step 5 - Finish Processing the Payment

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

# Payment Lifecycle

## Scenario 1 - Payment Lifecycle - Happy Path

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

| Action | Payment Status | Webhook Event |
|  --- | --- | --- |
| Request payment. | `REQUESTED` |  |
| (Optional) Client uploads document to payment. | `REQUESTED` |  |
| Accept payment. Deposit instructions are in the response. | `ACCEPTED` |  |
| (External) Share payment instructions with counterparty. | `ACCEPTED` |  |
| (External) Counterparty makes payment to unique instructions. | `ACCEPTED` |  |
| Funds are received into customer account with instructions. AML and processing begin. | `ACCEPTED` |  |
| Funds credited to destination account. Total funds < payment amount | `IN_PROGRESS` | `PAYMENT_IN_PROGRESS` |
| Funds credited to destination account. Toal funds >= payment amount | `EXECUTED` | `PAYMENT_EXECUTED` |


## Scenario 2 - Payment Lifecycle - Up Front RFI

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

| Action | Payment Status | Webhook Event |
|  --- | --- | --- |
| Request payment | `REQUESTED` |  |
| RFI is required for payment. | `CHANGES_REQUESTED` | `PAYMENT_CHANGES_REQUESTED` |
| Client uploads document to payment. Payment can now be Accepted. | `REQUESTED` |  |
| Accept payment. Deposit instructions are in the response. | `ACCEPTED` |  |
| (External) Share payment instructions with counterparty. | `ACCEPTED` |  |
| (External) Counterparty makes payment to unique instructions. | `ACCEPTED` |  |
| Funds are received into customer account with instructions. AML and processing begin. | `ACCEPTED` |  |
| Funds credited to destination account. Total funds < payment amount | `IN_PROGRESS` | `PAYMENT_IN_PROGRESS` |
| Funds credited to destination account. Toal funds >= payment amount | `EXECUTED` | `PAYMENT_EXECUTED` |


## Scenario 3 - Payment Lifecycle - Post-Accept RFI

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

| Action | Payment Status | Webhook Event |
|  --- | --- | --- |
| Request payment. | `REQUESTED` |  |
| Accept payment. Deposit instructions are in the response. | `ACCEPTED` |  |
| (External) Share payment instructions with counterparty. | `ACCEPTED` |  |
| (External) Counterparty makes payment to unique instructions. | `ACCEPTED` |  |
| Funds are received into customer account with instructions. AML checks happen. | `IN_PROGRESS` | `PAYMENT_IN_PROGRESS` |
| RFI is required for payment | `CHANGES_REQUESTED` | `PAYMENT_CHANGES_REQUESTED` |
| Client uploads all documents. RFI review begins. | `IN_REVIEW` | `PAYMENT_IN_REVIEW` |
| RFI response is accepted. Payment begins processing. | `IN_PROGRESS` | `PAYMENT_IN_PROGRESS` |
| Funds credited to destination account. Total funds < payment amount | `IN_PROGRESS` | `PAYMENT_IN_PROGRESS` |
| Funds credited to destination account. Toal funds >= payment amount | `EXECUTED` | `PAYMENT_EXECUTED` |