Web
This page details how to add the ReadyRemit iframe to your Web app
Step 1. Add iframe and Integrate ReadyRemit Helper Instance
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<!-- ReadyRemit Helper Instance -->
<script>
((w,d)=>{w.rremit||(w.rremit={sdkUrl:void 0,prevListener:void 0,getIFrame:function(){return d.getElementById("readyremit-iframe")},postMessage:function(m){w.rremit.getIFrame().contentWindow.postMessage(m,w.rremit.sdkUrl)},init:function(payload,onCreateCallback,onUnloadCallback){var iframe=w.rremit.getIFrame(),originAllowed=(w.rremit.sdkUrl=iframe.src,new URL(w.rremit.sdkUrl).origin),initSent=(w.rremit.prevListener&&w.removeEventListener("message",w.rremit.prevListener),!1);w.rremit.prevListener=function(e){if(e.origin===originAllowed){var _a=null==(_a=null==e?void 0:e.data)?void 0:_a.type;switch(_a){case"readyremit-unload-iframe":onUnloadCallback&&onUnloadCallback();break;case"readyremit-create-transfer":onCreateCallback&&onCreateCallback(e.data.payload);break;case"readyremit-ready":initSent||(iframe.style="",w.rremit.postMessage({type:"readyremit-initiate",payload:payload}),initSent=!0)}}},w.addEventListener("message",w.rremit.prevListener)},failed:function(e){w.rremit.postMessage({type:"readyremit-transfer-failed",payload:{error:e.response.data}})},completed:function(transferId){w.rremit.postMessage({type:"readyremit-transfer-completed",payload:{transferId:transferId}})}})})(window,document);
</script>
<!-- End ReadyRemit Helper Instance -->
<title>ReadyRemit Example</title>
</head>
<body>
<!-- Content of your website -->
<!-- It's require that the id of the iframe is set to be "readyremit-iframe" -->
<iframe
id="readyremit-iframe"
src="https://sandbox-sdk.readyremit.com"
allow="clipboard-read; clipboard-write; camera"
width="100%"
height="100%"
style="display: none;"
title="International & Domestic Transfers"
></iframe>
<script>
const customerId = "<this will be provided by ReadyRemit>";
const resources = "<encrypted resources, this should be generated in the customer backend>";
window.rremit.init(
{
sdkCore: {
customerId,
resources,
},
sdkColors: {
brandPrimary: "#934ae0"
},
sdkFeatures: {
darkMode: true // DEFAULT false
}
},
async (eventPayload) => {
try {
// eventPayload: {
// language: string; // en-US | es-MX
// transfer: {
// quoteBy: string;
// quoteHistoryId: string;
// recipientId: string;
// recipientAccountId: string;
// fields: [{
// id: "VIRTUAL_SENDER_ACCOUNT_ID",
// type: "TEXT",
// value: string;
// }]
// };
// }
// TODO:
// 1. Post the transfer (eventPayload) to your server
// 2. In your backend, retrieve the quote details using the quoteHistoryId from the eventPayload
// 3. Post the transfer using the readyremit api with the data from eventPayload + the quote details from step 2
// The completed TransferId should be returned
// For more information, see Step 6 in the C2C via SDK guide
// https://developer.readyremit.com/docs/c2c-via-sdk#step-6-submit-the-transfer
//
// Example:
// let transferResponse = postTransferToServer(event.data.payload, resources)
// let transferId = transferResponse.transferId;
// This message back to the iframe with the TransferId will render the confirmation screen
window.rremit.completed(transferId);
} catch (error) {
// the error object should match this structure
//{
// "response": {
// "data": {
// "code": 400,
// "message": "Insufficient funds"
// },
// }
//}
window.rremit.failed(error);
}
}
);
</script>
</body>
</html>
Let's see what's happening in the code sample above (JavaScript Tab):
-
Line 6: ReadyRemit code snippet, it mostly works as a helper to communicate back and forth with the ReadyRemit SDK loaded in the iframe
-
Line 15: Iframe to load the ReadyRemit SDK. The iframe must have an id attribute with the value "readyremit-iframe".
-
Line 17: The ReadyRemit iframe URL is defined based on the environment (Sandbox or Production) and is the same as the one that was replaced earlier in the provided script.
-
Lines 25: This value will be provided by ReadyRemit tech support when onboarding.
-
Lines 26: This is a string containing encrypted resources. These should be encrypted in the customer backend and provided to the frontend to initialize the iframe. Tech support will provide examples as to how to encrypt this and which resources to include.
-
Lines 27: Initialize the ReadyRemit iframe. Parameter descriptions can be found in the spec below.
-
Line 40: This is your custom callback function. This callback is fired from the iframe when the user completes the transfer flow and wants to submit the transfer. For security purposes, the iframe does not complete the transfer but relies on your server to make the final API call to the ReadyRemit API. For more information, see Step 6 in the C2C via SDK guide. Here you'll receive an
eventPayload
that containstransfer
andlanguage
. -
Line 48: When you call your backend to complete the transfer on your side, you will also need to send the encrypted resources (Line 26) so that you can call the ReadyRemit Api from your backend.
-
Line 52: Once your server has completed the transfer with the ReadyRemit API, it will receive a Transfer ID in response. Here, we will post a message back to the iframe with the ID of the completed transfer.
-
Line 52: In the event of an error while attempting to post the transfer, your server should return an error (do not modify or alter it; we'll take care of that on our end).
Here, a message is sent back to the iframe with the error object, allowing it to be handled appropriately.
Resources/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 encrypt the token on your backend and only after that send it to the frontend for the iframe configuration.
Step 2: Configuration & Styling
To initialize the ReadyRemit SDK, a message containing a payload is posted to the iframe. The specification for that payload is as follows:
FORM_SUBMISSION Payload
Property | Description | Type | Required |
---|---|---|---|
sdkCore | SDKCoreOptions | Yes | |
sdkColors | SDKColorsOptions | No | |
sdkFeatures | SDKFeaturesOptions | No | |
virtualSenderAccounts | VirtualSenderAccounts | No |
SDKCoreOptions
Property | Description | Type | Required | Supported |
---|---|---|---|---|
resources | An encrypted string that includes the auth token to connect to the ReadyRemit Api. This token should be scoped to the current Sender. For more information, see the Authentication guide. | string | Yes | |
idleTimeout | Timeout in milliseconds before the remittance session is canceled | int | No | |
language | Language of the remittance transfer flow. | string | No | en-US | es-MX |
SDKColorsOptions
Property | Description | Type | Required | Default |
---|---|---|---|---|
background | The background color of the entire remittance flow | hex | No | #F3F4F6 |
darkBackground | Dark version of the background | hex | No | #111111 |
foreground | The foreground color of the entire remittance flow | hex | No | #FFFFFF |
darkForeground | A dark version of the foreground | hex | No | #1F1F1F |
buttonBackground | Represents the main background color for all buttons | hex | No | #934AE0 |
darkButtonBackground | Dark version of buttonBackground | hex | No | #A26FD8 |
buttonFontColor | Represents the font color for buttons | hex | No | #FFFFFF |
darkButtonFontColor | Dark version of the button font color | hex | No | #FFFFFF |
danger | Visible when there's an API error on a fetch call | hex | No | #AA220F |
darkDanger | Dark version of danger | hex | No | #ED7083 |
divider | Horizontal rule that separates certain sections | hex | No | #E2E2E2 |
darkDivider | Dark version of Divider | hex | No | #313131 |
icon | Fill and stroke colors for SVG icons | hex | No | #444444 |
darkIcon | A dark version of the icon | hex | No | #7E7E7E |
inputLine | Represents the border color of input fields | hex | No | #858585 |
darkInputLine | Dark version of inputLine | hex | No | #505050 |
brandPrimary | Primary brand color applied to primary buttons and links | hex | No | #934AE0 |
darkBrandPrimary | Dark version of brandPrimary | hex | No | #A26FD8 |
textPrimary | Primary font color of the entire sdk | hex | No | #0E0F0C |
darkTextPrimary | Dark version of textPrimary | hex | No | #E3E3E3 |
textSecondary | Secondary font color for the entire sdk | hex | No | #454545 |
darkTextSecondary | Dark version of textSecondary | hex | No | #B0B0B0 |
success | hex | No | #008761 | |
darkSuccess | hex | No | #008761 |
SDKFeaturesOptions
Property | Description | Type | Required |
---|---|---|---|
darkMode | Forces the iframe into dark mode regardless of browser settings | bool | No |
confetti | Enables a confetti animation when a transaction is submitted | bool | No |
useUnloadEvent | Enables the 'unloadEvent' when pressing the back button from the Home screen, causing the iframe to trigger an unload of itself through the parent application. In the scenario where the Web SDK is loaded within a parent application, you may want to use the built-in navigation of the Web SDK to have a user exit the SDK and return to the host application. | bool | No |
defaultCountry | When a valid ISO3 code is provided, and the sender has missing fields, then the initial "Start a Transfer" screen is auto-filled with that code's country. A quote is automatically fetched, resulting in a filled transfer screen upon load. | string | No |
VirtualSenderAccounts
Virtual Sender Accounts provide the web SDK with a list of accounts from which funds will be debited. The web SDK will not initiate any fund transfers or money movement on its own.
When enabled, the SDK will display a dropdown menu showing the accounts and their balances. After a user selects an account, the SDK sends back a reference to that account. This allows you to identify which account to deduct funds from in your system.
Expected Payload for virtualSenderAccounts
The virtualSenderAccounts property expects an array of objects. Each object must match the following schema:
Property | Description | Type | Required |
---|---|---|---|
alias | A user-friendly name for the account (e.g., "Main Checking"). | string | Yes |
last4 | The last four digits of the account number are used to distinguish between accounts with the same alias. | number | Yes |
balance | The current balance of the account. The SDK uses this to check if there are sufficient funds for a transfer. | number | Yes |
srcProviderId | Your internal reference for the account, which you'll use to perform any necessary money movement. | string | Yes |
Handling Money Movement
Since the web SDK doesn't handle the money movement, it will include a new field inside fields
array, VIRTUAL_SENDER_ACCOUNT_ID
, in the eventPayload
. This field provides the srcProviderId of the selected account, telling you which account needs to be updated or debited on your end.
Updated 9 days ago