HomeDocumentationAPI Reference
Documentation

Drop-In rch.js guide

Learn how to implement the Drop-In JavaScript library (rch.js)

Suggest Edits

The Drop-in JavaScript library (rch.js) makes adding payment processing to web apps easy. This guide shows you how to use it. Follow the steps to integrate the library into your projects. Thoroughly test your implementation, especially handling a robust application's success and failure callbacks.

Step-by-step implementation

Step 1. Load the JavaScript Library

Include the Drop-In app by loading the JavaScript library. You can add the <script> tag to your HTML. If you are working in a sandbox environment, use the sandbox script URL; otherwise, use the production URL.

<script defer src="https://asset.withreach.com/dist/rch.js" onload="init()"></script>

<script defer src="https://asset.sandbox.withreach.com/dist/rch.js" onload="init()"></script>

Step 2. Initialize the library

Once the library is loaded, you can initialize it by calling the RCH_CC.rchInit method within your init function. Pass an object containing various parameters as defined below.

Required and optional parameters

The following table lists the parameters required for initializing the library, and the optional parameters, which provide additional customization.

ParameterTypeRequired/optionaldescription
idstringRequiredThis is the session ID your API generates.
targetstring or HTMLElementRequiredThis specifies the element or selector where you want to place the Drop-In app.
onSuccessfunctionRequiredA callback was triggered when the card payment was successful. When you use a payment option that does not redirect, you will use this method to manipulate the DOM or redirect to a success page when the Drop-In triggers it on session completion.
onFailurefunctionRequiredA callback is triggered when a payment fails. A JSON object containing an errorCode and errorMessage will be passed into the callback function.
hideSubmitButtonbooleanOptionalSet this to true if you want to hide the submit button.
onSubmitEnabledChangefunctionOptionalA callback that receives a boolean value indicating whether submitting is allowed.
customizationOptions{[key: string]: string}OptionalKey-value pairs for custom style properties.
text{[key: string]: string}OptionalKey-value pairs for custom text.
localestringOptionalSpecify the locale code. Accepted value formats include two letters, like en, or five characters with a hyphen, such as en-US. The value is case-insensitive.

Drop-In example code

Here are two Drop-In implementation examples for the production and sandbox environments:

📘

Note

If you're using the sandbox, the script URL is: http://asset.sandbox.withreach.com/dist/rch.js

<script defer src="https://asset.withreach.com/dist/rch.js" onload="init()"></script>

<script>
  function init() {
    // provide session id
    const id = "26de814e-137d-4233-b8f5-c7b80fc8055f";

    // define target element
    const target = document.querySelector("#rch-cc");
    // - or - pass the document selector only
    const target = "#rch-cc";

    // define callback method that will be executed on payment success
    const onSuccess = () => {
      console.log("great success 👍");
    };

    // define callback method that will be executed on payment failure
    const onFailure = error => {
        console.log("failure occurred ❌ Error code: " + 
                     error.errorCode + ", Error message: " +
                     error.errorMessage + " ❌");
    };
    
    // define object of style parameters 
    const customizationOptions = {
      '--color-app': '#f3f3f3',
      '--color-primary': '#6158fb',
      '--color-focus': '#5047ff',
      '--color-hover': '#5047ff',
      '--font': 'Inter',
    };

    // initialize library
    RCH_CC.rchInit({ target, id, onSuccess, onFailure, customizationOptions });
  }
</script>

<style>
  .cc {
    max-width: 540px;
    min-width: 320px;
    margin: 0 auto;
  }
</style>

<div id="rch-cc"></div>

<script defer src="https://asset.sandbox.withreach.com/dist/rch.js" onload="init()"></script>

<script>
  function init() {
    // provide session id
    const id = "26de814e-137d-4233-b8f5-c7b80fc8055f";

    // define target element
    const target = document.querySelector("#rch-cc");
    // - or - pass the document selector only
    const target = "#rch-cc";

    // define callback method that will be executed on payment success
    const onSuccess = () => {
      console.log("great success 👍");
    };

  	// define callback method that will be executed on payment failure
    const onFailure = error => {
        console.log("failure occurred ❌ Error code: " + 
                     error.errorCode + ", Error message: " +
                     error.errorMessage + " ❌");
    };

    // define object of style parameters 
    const customizationOptions = {
      '--color-app': '#f3f3f3',
      '--color-primary': '#6158fb',
      '--color-focus': '#5047ff',
      '--color-hover': '#5047ff',
      '--font': 'Inter',
    };

    // initialize library
    RCH_CC.rchInit({ target, id, onSuccess, onFailure, customizationOptions });
  }
  }
</script>

<style>
  .cc {
    max-width: 540px;
    min-width: 320px;
    margin: 0 auto;
  }
</style>

<div id="rch-cc"></div>

Housing the app

As shown in the example above, you can render the Drop-In app as the container within a div element. It will automatically adjust its width based on its parent container. While setting a max-width of 540px for the container is optimal, avoid using full-screen width on larger displays, as this can cause layout issues with components like buttons and form inputs.

Updated 1 day ago