For the ReadyRemit C2C API flow, integration with ReadyRemit must take place on your server to avoid exposure of unique IDs, personal information, or access tokens.

Step 1: Securely store API credentials

ReadyRemit API credentials will be provided to you by the ReadyRemit Integrations Team when your integration starts. For more information, please see our documentation on Storing API credentials.

Step 2: Authenticate

An access token can be retrieved from the ReadyRemit API using the Client ID and Client Secret provided to you by the ReadyRemit Integrations Team when access to a new Environment was granted. It is recommended to get a new OAuth Access Token for each unique intention.

Please see the documentation on Authentication for more information.

🚧

Access Token Expiration

Be aware that the OAuth Access Token will expire after 24 hours. It is unlikely that a standard remittance flow will require a refreshed token but if that does happen, a new token can be retrieved.

❗️

Token Security

In the wrong hands, the ReadyRemit API Access Token generated for the C2C use case can be used to see personal information about your users or create fraudulent transfers. Be sure to only store the access token on your secure server and never expose it in the front-end.

Step 3: Create Sender records to associate with your user

Sender records represent the entity that owns the funds for the transfer. In the C2C use case, the sender is the individual initiating the Transfer and whose account or value store will be debited when the Transfer is executed.

It is recommended to create a Sender record with the ReadyRemit API using the Create Sender endpoint when your user attempts to launch the remittance flow for the first time.

📘

Required fields

The fields required to create a Sender with ReadyRemit are identical across all corridors. Use the Get Sender Fields endpoint to see the full list of required fields. Most information required to create a Sender should already have been collected by your system during user onboarding. The user might need to be prompted for any additional fields (see the guide on Building Senders, Recipients, and Accounts for tips on this process)

When a Sender record is created successfully, you will be provided a unique senderId. This ID should be saved in your system and associated with the user who initiated the remittance.

🚧

Sender authentication

The access token created in Step 2 is a "Client level" access token, meaning it can be used to view, update, and delete data belonging to any Sender under your customer account. Once a sender exists in the system, it is highly recommended that a "Sender level" access token be used for all other remittance operations through the ReadyRemit API. For more information on obtaining a Sender level access token, see the guide on Authentication.

Step 4 (Optional): Select a Recipient

If your user has already gone through the remittance flow and created a Recipient record, they should be allowed select this existing Recipient for their Transfer. You can use the Get Recipient API in conjunction with the Get Recipient Accounts endpoint to present this list to your user.

Note: this step is marked optional because technically the end-user could re-create the recipient each time but for best user experience this is not a recommended approach.

Step 5: Build a Quote

Our research shows that users are more likely to complete a cross-border remittance flow once they've seen and committed to a final rate and receive amount. For this reason, we encourage building and showing the user a Quote at the beginning of the flow.

Please see the documentation on Building a quote for a detailed walkthrough of the process.

Step 6: Create or Select a Recipient

A Recipient record represents the person receiving the funds of a transfer. This should be information about the person that doesn't change from one account to the next. In the ReadyRemit system, a Recipient can have multiple accounts. To create a Recipient, follow the steps in the Building Senders, Recipients, and Accounts documentation using the following two endpoints:

• Get Recipient Fields
• Create Recipient

When a Recipient is created a Recipient ID will be returned. You should store this ID in your system and associate it with your user. Be aware that a user might want to create more than one recipient so Recipient ID should be stored in a one-to-many format.

Step 7: Select or Create a Recipient Account

🚧

Cash Pickup

This step is not required if the Corridor selected in Step 2 has a "Transfer Method" of type CASH_PICKUP. The API to fetch Recipient Account Fields for Cash Pickup transfers will return an empty list.

Recipient Accounts in ReadyRemit represent the final destination of the funds in a transfer. Examples of Recipient Accounts include bank accounts, cards, or digital wallets (note: cash pickups do not require a Recipient Account). Multiple Recipient Account records can be created for a single Recipient.

To create a Recipient, follow the steps in the Building Senders, Recipients, and Accounts documentation using the following two endpoints:

• Get Recipient Account Fields
• Create Recipient Account

If you are presenting your users with a list of previously created Recipients, you can include their recipient accounts by calling the Get Recipient Accounts endpoint and passing in the Recipient ID collected in Step 3.

Step 8: Collect additional Transfer information

Some transfers require additional fields submitted with the transfer. To get a list of required fields for your transfer, call the Get Transfer Fields endpoint. For more information on rendering dynamic forms, see the documentation on Building Senders, Recipients, and Accounts and the reference material on Dynamic Fields.

📘

Not always required

If the result from the Get Transfer Fields call returns no fields, this step can be skipped.

Step 9: Transfer review and acceptance

Once these steps have all been completed you should have collected enough information from your user to complete the transfer. Before completing the transfer though it is very important to allow the user to review the details of the transfer in order to satisfy the requirements of the Remittance Transfer Rule. The following elements must be confirmed by the end user before the transfer can be sent:

• Total cost
• Exchange rate
• Receive amount

Below is a recommended design for the review screen:

Step 10: Secure funds

Once the user reviews and accepts the Transfer details you are ready to complete the transfer. Before sending the API call to ReadyRemit though, you must take any necessary action to ensure that funds are available for the Transfer and these funds are made unavailable to the Sender.

The amount to secure can be found in the response from the Get Quote endpoint in the totalCost field.

Step 11: Submit the Transfer

Once funds have been secured you can call the Create Transfer API to create the final Transfer.

🚧

Handling rate changes

It's possible that the exchange rate changes between the time the user reviewed it and the time the transfer is submitted. If this happens, the ReadyRemit API will return an error with a specific code indicating the rate changed.

When this happens it is required that you request a new Quote from the Get Quote API and display the new rate, receive amount, and total cost with the user.

The result of the Transfer creation includes a "Transfer ID" that can be saved and used later to show transfer details to your user.

Important: If there is any failure returned from the Create Transfer API call, the funds should be credited back to the Sender.

Step 12: Provide a receipt

It is a compliance requirement that a transfer receipt be made available to users in such a way that it can be retrieved at any time. The ReadyRemit Integrations Team recommends providing a PDF receipt that your users can download in order to meet this requirement. All of the details needed to render the receipt are present in the response from the Create Transfer endpoint.

Please see the documentation on API ReadyRemit Requirement of Receipt Compliance Documentation For a detailed description of exactly what needs to be on the receipt.

Step 13: Certification

Due to the highly regulated nature of moving money cross-borders, your integration with ReadyRemit will need to be certified by the ReadyRemit Integrations Team before access to the Production environment can be granted. To begin the certification process, please provide a certification ready environment with login credentials to the ReadyRemit Integrations Team.

🚧

Security Warning

The certification environment you provide should include test data only.

The following things will be tested during certification:

• Screens and UI flows meet compliance requirements
• API requests include expected information
• Information shown to the user matches what was returned in the API
• All expected disclaimers and disclosures are displayed in the appropriate places.

Step 14: IP Whitelisting

No IP whitelisting is required in the Sandbox environment, but IP whitelisting is required for production environment access. Whitelisting needs to happen on both your server and on ReadyRemit's server. When you are ready for this step, please provide your full set of production server IP addresses to the ReadyRemit Integration Team in a secure email and you will receive an email back with ReadyRemit IP production IP addresses.