The product described here is considered early-access and only available on request. Please get in touch (api@gocardless.com) if you're interested in trying it out. You don't need to contact us if you're interested in trying it out in our sandbox, follow the instructions below for setup.

The GoCardless Drop-in is an upcoming feature that allows you to embed the customer set-up process without the need for a redirect. The whole customer journey happens inside a modal that is initialised using our client script.

Document revisions

  • 2020-08-03:
    • Updated instructions to obtain a Drop-in key via the API for sandbox users
  • 2020-07-21:
    • Added instructions to obtain a Drop-in key via the API
  • 2020-07-16:
    • Added instructions to obtain a Drop-in key
    • Updated the JavaScript code snippet
  • 2020-06-01:
    • Clarified support for client libraries
    • Clarified description of GoCardless buttons
    • Added more API usage details
  • 2020-05-26: initial revision.

In order to use the Drop-in:

While the Drop-in is in early-access, GoCardless client libraries won't be updated with support for the API endpoints described in this document.
  1. You need to create a “Drop-in Key” in order to initialise the Drop-In. It is a unique identifier to the domain of your organisation. In fact, the Drop-in can be only be used within the specified domain name. All resources created using this Drop-in Key will be linked to your organisation.

    You can contact the Support team by emailing api@gocardless.com with subject line “Please whitelist us for using drop-in payment page solution” and in the body of the email specify your “Creditor ID” and/or the email address of an admin user on your account (only for the live environment).

    Alternatively, to create a Drop-in Key via the API (for live environment contact support team first to be whitelisted), you need to make a POST request to the payer_authorisation_public_tokens endpoint. The access token for this request must be obtained through the dashboard.

    The base URLs for the GoCardless API are - https://api.gocardless.com/ for live - https://api-sandbox.gocardless.com/ for sandbox
    POST https://api.gocardless.com/payer_authorisation_public_tokens HTTP/1.1
    {
       "payer_authorisation_public_tokens": {
          "domain": "host-domain.com"
       }
    }
    
    HTTP/1.1 201
    {
       "payer_authorisation_public_tokens": {
          "id": "PAPT000123",
          "token": "live_token_abc123"
       }
    }
    

    The token string returned is the Drop-in Key uniquely generated for your organisation and domain. The Drop-in can be only be used within the domain name (FQDN) specified within the domain field. You can’t use wildcards in the domain name parameter: if you intend to run the Drop-in across different domains you’ll need to setup different Drop-in keys.

  2. Copy the snippet of code below into your website to setup the Drop-in and bind the modal opening to an html element in your page. You’ll need to replace the placeholder key with the Drop-in Key generated at step 1.

    <html>
       <head>
          <!-- Load the client script. -->
          <script type="application/javascript" src="https://dropin-sandbox.gocardless.com/script.js"></script>
          <!-- Url for live environment is https://dropin.gocardless.com/script.js -->
       </head>
    
       <body>
          <!-- Add a button to your page HTML -->
          <button id="pay-with-gocardless-button">Pay with GoCardless</button>
       </body>
    
       <script type="application/javascript">
          var gocardlessHandler = function() {
             var gocardlessClient = GoCardlessClient({
                token: "[dropin-key]",
             });
    
             gocardlessClient.create({
                onSave: function(payerAuthorisationId, confirmCallback, metadata) {
                   // 1. Optional: store the payerAuthorisationId server-side
                   // 2. Mandatory: call confirmCallback to let the Drop-in flow continue
                   confirmCallback();
                },
                onComplete: function(metadata) {
                   // The customer completed successfully
                   alert("Drop-in flow completed!");
                },
                onExit: function(error, metadata) {
                   if (error === undefined) {
                      // The customer left intentionally the Drop-in flow
                      // (for example they closed the modal interface).
                   } else {
                      // The customer left due to unrecoverable error.
                   }
                }
             });
          };
    
          document.addEventListener("DOMContentLoaded", function() {
             document
                .getElementById("pay-with-gocardless-button")
                .addEventListener("click", gocardlessHandler);
          });
       </script>
    </html>
    
  3. New customers should now appear in your GoCardless dashboard or App.

In order to track the status of the customer creation, save in your servers the payerAuthorisationId passed to the onSave callback and then listen to the payer_authorisation_completed webhook or make a GET request to the PayerAuthorisation resource using the access_token obtained through the dashboard. More information about webhooks available here.

   GET https://api.gocardless.com/payer_authorisations/PAU00001079R3KW HTTP/1.1

   HTTP/1.1 201
   {
    "payer_authorisations": {
        "id": "PAU00001079R3KW",
        "submitted_at": "2020-08-07T08:55:44.799Z",
        "confirmed_at": "2020-08-07T08:55:55.722Z",
        "customer": {...},
        "bank_account": {...},
        "mandate": {...},
        "errors": [],
        "next_actions": [],
        "links": {
            "customer": "CU00001078N0FX",
            "bank_account": "BA0000107849A8",
            "mandate": "MD00001078E47Q"
        }
      }
   }

What your customers will see:

  1. The customer clicks on a button to start the Direct Debit setup process

    Pay with GoCardless button

    NOTE: You can find images for the “Pay with GoCardless” button here.

  2. The Drop-in opens with an introduction screen

    Drop-in intro screen

  3. The customer fills their information and clicks “continue”

    Drop-in enter details screen

  4. They go to a confirmation page to review their information

    Drop-in confirm details screen

  5. We show them a success screen inside the Drop-in

    Drop-in success screen

  6. The customer closes the Drop-in and you decide what they should see next

    Drop-in close button