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, and description (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

PropertyDescriptionTypeRequired
formCoreFormCoreOptionsYes
formColorsFormColorsOptionsYes
formFeaturesFormFeaturesOptionsYes

FormCoreOptions

PropertyDescriptionTypeRequired
baseURLThe URL of the ReadyRemit API that the SDK will connect tostringYes
sdkURLThe URL of the ReadyRemit SDK (Sandbox or Production)stringYes
tokenAuthorization token acquired by your server. This token should be scoped to the current Sender. For more information see the Authentication guide.stringYes
senderIdThe ID of the current senderstringYes
idleTimeoutTimeout in milliseconds before the remittance session is canceledintNo
languageLanguage of the remittance transfer flow.stringNo

FormColorsOptions

PropertyDescriptionTypeRequired
backgroundBackground color of the the entire remittance flowstringYes
darkBackgroundDark version of backgroundstringYes
foregroundForeground color of the the entire remittance flowstringYes
darkForegroundDark version of foregroundstringYes
buttonBackgroundRepresents the main background color for all buttonsstringYes
darkButtonBackgroundDark version of buttonBackgroundstringYes
buttonFontColorRepresents the font color for buttonsstringYes
darkButtonFontColorDark version of button font colorstringYes
dangerVisible when there's an API error on a fetch callstringYes
darkDangerDark version of dangerstringYes
dividerHorizontal rule that separates certain sectionsstringYes
darkDividerDark version of dividerstringYes
iconFill and stroke colors for svg iconsstringYes
darkIconDark version of iconstringYes
inputLineRepresents the border color of input fieldsstringYes
darkInputLineDark version of inputLinestringYes
brandPrimaryPrimary brand color applied to primary buttons and linksstringYes
darkBrandPrimaryDark version of brandPrimarystringYes
textPrimaryPrimary font color of the entire sdkstringYes
darkTextPrimaryDark version of textPrimarystringYes
textSecondarySecondary font color for the entire sdkstringYes
darkTextSecondaryDark version of textSecondarystringYes

FormFeaturesOptions

PropertyDescriptionTypeRequired
darkModeForces the iFrame into dark mode regardless of browser settingsboolNo
confettiEnables a confetti animation when a transaction is submittedboolNo