iFrame
This page details how to add the ReadyRemit iFrame to your Web app
1. Add the iFrame to your UI
<iframe
id="readyremit-iframe"
src="https://sandbox-sdk.readyremit.com"
width="100%"
height="1000px"
style="border:none"
title="International & Domestic Transfers">
</iframe>
2. Integrate iFrame on the front-end
// TODO: Set ReadyRemit SDK URL based on environment
// Sandbox: https://sandbox-sdk.readyremit.com
// Production: https://sdk.readyremit.com
const readyRemitSdkUrl = "https://sandbox-sdk.readyremit.com";
// The associated Sender record for this user should should have been created in the ReadyRemit system server side
// See Step 3 in the SDK guide
// https://developer.readyremit.com/docs/c2c-via-sdk#step-3-create-sender-records-to-associate-with-your-user
const senderId = "[SENDER ID]";
const iframe = document.getElementById("readyremit-iframe");
window.addEventListener(
"message",
async (event) => {
// We only want to handle events from the ReadyRemit iFrame
if (event.origin != readyRemitSdkUrl) {
return;
}
if (event.data?.type === "readyremit-unload-iframe") {
// TODO: Handle user timeout
// This can be a notification message and refreshing the auth token / screen
}
if (event.data?.type === "readyremit-create-transfer") {
try {
// TODO: Post the transfer to your server, to be sent to ReadyRemit for completion
// 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)
// let transferId = transferResponse.transferId;
// This message back to the iFrame with the TransferID will render the confirmation screen
iframe.contentWindow.postMessage({
type: "readyremit-transfer-completed",
payload: {
transferId: transferId,
},
}, event.origin);
} catch (error) {
// TODO: Log the error
// This message back to the iFrame will render the error message or handle the exception gracefully
iframe.contentWindow.postMessage({
type: "readyremit-transfer-failed",
payload: {
error: error.response.data,
}
}, event.origin);
}
}
},
false
);
// TODO: Fetch ReadyRemit auth token from your server.
// See steps 1 & 2 in the SDK integration guide
// https://developer.readyremit.com/docs/c2c-via-sdk#step-1-securely-store-api-credentials
//
// Example:
// let authTokenResponse = fetchAuthTokenFromServer();
const authToken = "[AUTH_TOKEN]";
// Initialize SDK settings and styles
// TODO: Wire this up to some action
const initializeReadyRemitIFrame = () => {
// Initialize iFrame settings and styles
iframe.contentWindow.postMessage({
type: "readyremit-form-submission",
payload: {
formCore: {
baseURL: "https://sandbox-api.readyremit.com/v1",
sdkURL: readyRemitSdkUrl,
senderId: senderId,
token: authToken
},
formColors: {
brandPrimary: "#934ae0"
},
formFeatures: {
darkMode: false
}
}
}, readyRemitSdkUrl);
}
Let's see what's happening in the code sample above:
- Line 4: The ReadyRemit SDK URL is defined based on the environment (Sandbox, or Production)
- Line 9: The Sender ID is declared. This value should come from your server, and be associated with the currently logged in user. This ID uniquely identifies a sender record in the ReadyRemit system.
- Line 11: The ReadyRemit iFrame is declared, referencing the ID used in your Step #1
- Line 13: An event listener is wired up to the
window
object. This event listener will perform the following tasks when an event is fired- Line 17: Ignore all events that didn't come from the ReadyRemit iFrame. If you need to listen to other window events, you can wire up a separate event listener.
- Line21: Handle the
UNLOAD_IFRAME
event. This event is fired if the user times out, or chooses to close the ReadyRemit SDK - Line 26 Handle the
CREATE_TRANSFER
. This event 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. - Line 38: 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 48: In the event of an error while attempting to post the transfer, your server should return an error with the following properties:
code
,message
, anddescription
(for examples of error formats, see the HTTP Status codes reference page).
Here, a message is sent back to the iFrame with the error object so it can be handled appropriately.
- Line 66: Fetch a ReadyRemit Authorization Token to be used when initializing the iFrame. This token must be fetched from the ReadyRemit API by your server, not the front-end.
Chronologically, this line of code is run first. - Line 67: Initialize the ReadyRemit iFrame. Parameter descriptions can be found in the spec below.
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: Configuration & Styling
To initialize the ReadyRemit SDK, a message is posted to the iFrame containing a payload. The specification for that payload is as follows:
FORM_SUBMISSION Payload
Property | Description | Type | Required |
---|---|---|---|
formCore | FormCoreOptions | Yes | |
formColors | FormColorsOptions | Yes | |
formFeatures | FormFeaturesOptions | Yes |
FormCoreOptions
Property | Description | Type | Required |
---|---|---|---|
baseURL | The URL of the ReadyRemit API that the SDK will connect to | string | Yes |
sdkURL | The URL of the ReadyRemit SDK (Sandbox or Production) | string | Yes |
token | Authorization token acquired by your server. This token should be scoped to the current Sender. For more information see the Authentication guide. | string | Yes |
senderId | The ID of the current sender | string | Yes |
idleTimeout | Timeout in milliseconds before the remittance session is canceled | int | No |
language | Language of the remittance transfer flow. | string | No |
FormColorsOptions
Property | Description | Type | Required |
---|---|---|---|
background | Background color of the the entire remittance flow | string | Yes |
darkBackground | Dark version of background | string | Yes |
foreground | Foreground color of the the entire remittance flow | string | Yes |
darkForeground | Dark version of foreground | string | Yes |
buttonBackground | Represents the main background color for all buttons | string | Yes |
darkButtonBackground | Dark version of buttonBackground | string | Yes |
buttonFontColor | Represents the font color for buttons | string | Yes |
darkButtonFontColor | Dark version of button font color | string | Yes |
danger | Visible when there's an API error on a fetch call | string | Yes |
darkDanger | Dark version of danger | string | Yes |
divider | Horizontal rule that separates certain sections | string | Yes |
darkDivider | Dark version of divider | string | Yes |
icon | Fill and stroke colors for svg icons | string | Yes |
darkIcon | Dark version of icon | string | Yes |
inputLine | Represents the border color of input fields | string | Yes |
darkInputLine | Dark version of inputLine | string | Yes |
brandPrimary | Primary brand color applied to primary buttons and links | string | Yes |
darkBrandPrimary | Dark version of brandPrimary | string | Yes |
textPrimary | Primary font color of the entire sdk | string | Yes |
darkTextPrimary | Dark version of textPrimary | string | Yes |
textSecondary | Secondary font color for the entire sdk | string | Yes |
darkTextSecondary | Dark version of textSecondary | string | Yes |
FormFeaturesOptions
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 |
Updated 19 days ago