Dropin API

README-tokenless.md

Dropin (tokenless)

The Dropin is a Javascript modal that allows integrators to initialise Billing Request Flows all from within their own websites.

Include the GoCardless Dropin initialise script on each page of your site:

<script src="https://pay.gocardless.com/billing/static/dropin/v2/initialise.js"></script>

You are discouraged from bundling the initialisation script or vendoring it, as GoCardless reserves the right to make non-breaking changes to the underlying implementation, which you will want your sites to pickup automatically.

We guarantee backward compatibility between major versions of the initialise script, as denoted by the script source URL.

Open the Dropin

A typical pattern is to create the Billing Request in your sites backend server, along with a Billing Request Flow, then pass the ID of that flow to the client to open the modal.

This ensures your backend can store a reference to the Billing Request, often against an internal customer record.

Provide the Billing Request Flow ID to the client to open the Dropin modal:

const handler = GoCardlessDropin.open({
  // Billing Request Flow ID, generated by your backend
  billingRequestFlowID,

  // onSuccess receives the Billing Request that has been worked.
  //
  // This is called when the flow exits successfully. Depending on how the flow
  // was configured, it may have completed successfully but not fulfilled the
  // Billing Request- it is incumbent on the integrator to check the status of
  // the request before assuming it has been fulfilled.
  onSuccess: (billingRequest, billingRequestFlow) => {},

  // onExit should take two arguments: an error object and a metadata object.
  //
  // The onExit callback is called when the customer left the flow before
  // completion. This can happen because either they have voluntarily abandoned
  // the flow, or because an unrecoverable error occurred.
  //
  // The error object is null if no error was encountered. At the time of
  // writing no additional object property is documented.
  //
  // The metadata object is always not null. At the time of writing no
  // additional object properties are documented.
  onExit: (error, metadata) => {},
})

You should register callback handlers that allow your site to respond to payer activity in the Dropin, such as successful completion or exit.

If you wish to close the modal, you may do so programmatically with:

handler.exit()

README.md

Dropin

The Dropin is a Javascript modal that allows integrators to initialise Billing Request Flows all from within their own websites.

Include the GoCardless Dropin initialise script on each page of your site:

<script src="https://pay.gocardless.com/billing/static/dropin/v2/initialise.js"></script>

You are discouraged from bundling the initialisation script or vendoring it, as GoCardless reserves the right to make non-breaking changes to the underlying implementation, which you will want your sites to pickup automatically.

We guarantee backward compatibility between major versions of the initialise script, as denoted by the script source URL.

Public Tokens

To use the Dropin, you must first create a Public Access Token. You can do this in the GoCardless dashboard:

Environment	URL
live	https://manage.gocardless.com/developers
sandbox	https://manage-sandbox.gocardless.com/developers

For security purposes, public tokens have to specify the domain you will be using them from. This prevents someone other than the integrator who owns the token using it in their site, potentially tricking customers into thinking the fraudulent site is affiliated with the integrator's organisation.

This in mind, if you intend to use the Dropin on https://cool-stuff.com/, make sure you create a public token with:

• The dropin scope
• And a domain of https://cool-stuff.com

Using this token on any site other than https://cool-stuff.com/ will return an error.

Creating a client

All Dropin functions are provided by a client, which must be created with your public token (and optionally, the domain it should target):

const client = GoCardlessDropin.configure({
  publicToken,
  domain, // pick which environment to use
})

Open the Dropin

A typical pattern is to create the Billing Request in your sites backend server, along with a Billing Request Flow, then pass the ID of that flow to the client to open the modal.

This ensures your backend can store a reference to the Billing Request, often against an internal customer record.

Provide the Billing Request Flow ID to the client to open the Dropin modal:

const handler = client.open({
  // Billing Request Flow ID, generated by your backend
  billingRequestFlowID,

  // onSuccess receives the Billing Request that has been worked.
  //
  // This is called when the flow exits successfully. Depending on how the flow
  // was configured, it may have completed successfully but not fulfilled the
  // Billing Request- it is incumbent on the integrator to check the status of
  // the request before assuming it has been fulfilled.
  onSuccess: (billingRequest, billingRequestFlow) => {},

  // onExit should take two arguments: an error object and a metadata object.
  //
  // The onExit callback is called when the customer left the flow before
  // completion. This can happen because either they have voluntarily abandoned
  // the flow, or because an unrecoverable error occurred.
  //
  // The error object is null if no error was encountered. At the time of
  // writing no additional object property is documented.
  //
  // The metadata object is always not null. At the time of writing no
  // additional object properties are documented.
  onExit: (error, metadata) => {},
})

You should register callback handlers that allow your site to respond to payer activity in the Dropin, such as successful completion or exit.

If you wish to close the modal, you may do so programmatically with:

handler.exit()

Creating a flow

It's possible to create a Billing Request and Flow directly from the frontend, which can then be used to open the Dropin.

// Create both Billing Request and Flow
const {billingRequest, billingRequestFlow} = client.create({
  payment_request: {
    currency: 'GBP',
    amount: 0.99,
  }
})

// Open the Dropin using the flow ID
const handler = client.open({
  billingRequestFlow.id,
  onSuccess: (billingRequest, billingRequestFlow) => {},
  onExit: (error, metadata) => {},
})

React

TODO