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 for the external entity sending the funds and have it approved.
2. Create a Payment using counterparty from step 1.
3. Accept the Payment 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 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.

Scenario 2 - Payment Lifecycle - Up Front RFI

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

Scenario 3 - Payment Lifecycle - Post-Accept RFI

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