📘
Legacy Web SDK
For customers using Web SDK versions prior to 4.0, see the Legacy Web SDK Integration Guide.

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 -->
    <!-- use sandbox-sdk.readyremit.com for Sandbox and sdk.readyremit.com for Prod. -->
    <script src="https://sandbox-sdk.readyremit.com/scripts/snippet.min.js"></script>
    <!-- End ReadyRemit Helper Instance  -->

    <title>ReadyRemit Example</title>
  </head>
  <body>
    <!-- Content of your website -->
    <!-- It's required 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,
            language: "en-US",
          },
          sdkFeatures: {
            darkMode: false,
            confetti: true,
            customStyles: {
              foundations: {
                colorPrimary: { light: "#934ae0", dark: "#A26FD8" }
              }
            }
          },
          virtualSenderAccounts: [
            {
              alias: "Main Checking",
              last4: "1234",
              balance: 100000,
              srcProviderId: "your-internal-account-id"
            }
          ]
        },
        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 7: ReadyRemit code snippet, it mostly works as a helper to communicate back and forth with the ReadyRemit SDK loaded in the iframe
Line 16: Iframe to load the ReadyRemit SDK. The iframe must have an id attribute with the value "readyremit-iframe".
Line 18: 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.
Line 26: This value will be provided by ReadyRemit tech support when onboarding.
Line 27: 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.
Line 28: Initialize the ReadyRemit iframe. Parameter descriptions can be found in the spec below.
Lines 30-39: Core and features configuration. Theming is now handled via customStyles within sdkFeatures. See the SDK Theme Configuration guide for the full theming schema.
Lines 41-48: Virtual Sender Accounts. Provides the SDK with a list of accounts the user can select to fund the transfer. See VirtualSenderAccounts for the full specification.
Line 50: 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 contains transfer and language.
Line 61: When you call your backend to complete the transfer on your side, you will also need to send the encrypted resources (Line 27) so that you can call the ReadyRemit Api from your backend.
Line 64: 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 65: 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:

Initialization Payload

Property	Description	Type	Required
sdkCore	Core configuration for the SDK session	SDKCoreOptions	Yes
sdkFeatures	Feature flags and theme customization	SDKFeaturesOptions	No
sdkRtaf	RTAF (Real Time Account Funding) mode configuration	SDKRtafOptions	No
virtualSenderAccounts	Accounts from which funds will be debited	VirtualSenderAccounts	No

SDKCoreOptions

Property	Description	Type	Required	Supported
customerId	Customer ID provided during onboarding.	string	Yes
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
language	Language of the remittance transfer flow.	string	No	en-US \| es-MX
idleTimeout	Timeout in milliseconds before the remittance session is canceled	int	No
defaultQuoteAmount	Default amount of a transfer. Can include decimal places for cents.	number	No

Theming

Visual customization is configured via the customStyles property within sdkFeatures. For the full theming schema including foundations (colors, fonts) and component-level styling (buttons, inputs, loading screens), see the SDK Theme Configuration guide.

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
customStyles	Theme configuration object. See the SDK Theme Configuration guide for the full schema.	object	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.

eventPayload

When the user completes the transfer flow and clicks submit, the SDK fires the onCreateCallback with an eventPayload. This payload contains the transfer details your backend needs to call the ReadyRemit API.

📘
RTAF Mode
If you are using RTAF mode, the eventPayload has a different structure. See the RTAF Integration Guide for details.

{
  language: string;      // e.g. "en-US"
  transfer: {
    quoteBy: string;
    quoteHistoryId: string;
    recipientId: string;
    recipientAccountId: string;
    fields: [{
      id: "VIRTUAL_SENDER_ACCOUNT_ID",
      type: "TEXT",
      value: string;
    }]
  };
}

transfer Properties

Property	Description	Type
quoteBy	Indicates how the quote was generated (e.g., by send amount or receive amount)	string
quoteHistoryId	The ID of the quote generated during the transfer flow. Use this to retrieve quote details on your backend.	string
recipientId	The ID of the recipient selected by the user	string
recipientAccountId	The ID of the recipient's account selected for the transfer	string
fields	Additional fields returned by the SDK. When Virtual Sender Accounts are enabled, includes `VIRTUAL_SENDER_ACCOUNT_ID`.	array

Your backend should:

Retrieve the quote details using quoteHistoryId
Call POST /transfers with the transfer data and quote details
Return the transferId to the frontend
Call rremit.completed(transferId) to show the confirmation screen, or rremit.failed(error) on failure

Snippet API Reference

The ReadyRemit snippet (snippet.min.js) exposes the window.rremit object with the following methods for communicating with the SDK iframe.

init

window.rremit.init(payload, onCreateCallback, onUnloadCallback)

Initializes the SDK iframe with the provided configuration payload.

Parameter	Type	Required	Description
payload	object	Yes	The initialization payload containing `sdkCore`, `sdkFeatures`, `sdkRtaf`, and/or `virtualSenderAccounts`
onCreateCallback	function	No	Called when the user submits a transfer. Receives `eventPayload` as the argument.
onUnloadCallback	function	No	Called when the SDK requests the iframe to be unloaded (e.g., user navigates back from home).

completed

window.rremit.completed(transferId)

Posts the completed transfer ID back to the SDK iframe to render the confirmation screen.

Parameter	Type	Required	Description
transferId	string	Yes	The transfer ID returned by your backend

failed

window.rremit.failed(error)

Posts an error back to the SDK iframe so it can display the error to the user.

Parameter	Type	Required	Description
error	object	Yes	Error object with `response.data` containing `code` and `message` fields

Expected error structure:

{
  response: {
    data: {
      code: 400,
      message: "Insufficient funds"
    }
  }
}

postMessage

window.rremit.postMessage(message)

Sends a raw message directly to the SDK iframe. This is used for advanced integrations where you need to communicate custom messages beyond the standard API.

Parameter	Type	Required	Description
message	object	Yes	The message object to send to the SDK iframe