# 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:

```html
<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):

```typescript
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:

```typescript
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.

```typescript
// 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