# Express Checkout options

> These are the options you pass to Shuttle.authenticate, or set as window.shuttleauthenticateoptions, and what the callbacks receive. How to put them on a page i

These are the options you pass to `Shuttle.authenticate`, or set as `window.shuttle_authenticate_options`, and what the callbacks receive. How to put them on a page is in the [Express Checkout integration guide](/platforms/embedded-payments/express-checkout-integration-guide/).

```javascript
{
  element: "shuttle-express-checkout",
  on_start: function (event) {},
  on_success: function (result) {},
  on_error: function (error) {},
  options: {
    action: "AUTHORISE",
    payment_token: true,
    capture_shipping: false,
    currency: "USD",
    amount: "54.97",
    shipping: {},
    line_items: []
  }
}
```

## Component options

| Option | Description |
| --- | --- |
| `element` | Required. The `id` of the element to render the buttons in (a leading `#` is accepted). shuttle.js empties the element before rendering. |
| `options` | Required. What to ask the customer for: see [Payment options](#payment-options). |
| `on_start` | Function called when the customer starts using a provider's buttons. |
| `on_success` | Function called when the customer has finished with the provider. |
| `on_error` | Function called when the customer cancels, or an error occurs. |
| `debug` | `true` to log what shuttle.js is doing to the browser console while you build. |

## Payment options

The fields of `options`:

| Option | Description |
| --- | --- |
| `action` | `AUTHORISE` asks the customer to approve a payment of `amount`. `TOKENISE` asks them to approve a payment method, with no amount. Set it explicitly. |
| `payment_token` | `true` to receive `gateway_data`, which is what you pay with. Every use of Express Checkout that takes or saves a payment needs `true`. |
| `currency` | The currency, as an ISO code such as `USD`. Required with `AUTHORISE`. |
| `amount` | The amount to approve, as a decimal string such as `"54.97"`. Required with `AUTHORISE`. |
| `capture_shipping` | `true` to ask the customer for a shipping address and return it in `shipping`. |
| `shipping` | A shipping address to suggest to the customer, with the fields `line1` to `line6` and `country` (see [Addresses](#addresses)). PayPal uses it when `line1`, `line4`, `line5` and `country` are all set. |
| `line_items` | The basket, shown to the customer by providers that support it. See [Line items](#line-items). |

## Line items

`line_items` is an array of the items in the order. Shuttle does not validate them; it passes them to the providers that use them. Use the same fields as on [Create a payment](/platforms/reference/operations/createpayment/):

| Field | Description |
| --- | --- |
| `sku` | Your identifier for the product. |
| `name` | Your label for the item, shown to the customer. |
| `quantity` | The number of units, for example `"2"`. |
| `unit_price` | The price per unit **including** tax, for example `"9.99"`, in the currency of the payment. |
| `total_amount` | The total for the line **including** tax, for example `"19.98"`: normally `quantity` x `unit_price`, less any discount. |
| `total_tax` | Optional. The tax included in `total_amount`. |

For PayPal:

* A line with a `sku` of `SHIPPING`, `HANDLING` or `INSURANCE` (in any case) is shown as that charge in PayPal's order summary, rather than as an item.
* If the items add up to less than `amount`, a **Miscellaneous** item makes up the difference. If they add up to more, the difference is shown as a discount.

## Callbacks

### on_start

Called when the customer starts using a provider's buttons. Not every provider calls it.

```json
{
  "modal": true
}
```

* `modal`: `true` when the provider is covering your page, so you may want to block other input and pause timers.

### on_success

Called when the customer has finished with the provider. No money has moved and nothing has been created in Shuttle: send this to your server, which creates the payment or payment method.

```json
{
  "payment_method_description": "Apple Pay",
  "account": {
    "gateway_key": "jack@example.com",
    "first_name": "Jack",
    "last_name": "Smith",
    "email": "jack@example.com",
    "phone": "+12025552448",
    "address": {
      "line1": "1 Main Street",
      "line4": "Springfield",
      "line5": "62701",
      "line6": "IL",
      "country": "US"
    }
  },
  "shipping": {
    "line1": "1 Main Street",
    "line2": "Apartment 4",
    "line4": "Springfield",
    "line5": "62701",
    "line6": "IL",
    "country": "US"
  },
  "gateway_data": {
    "gateway": "11842_10002",
    "wallet": "apple_pay",
    "card_type": "VISA"
  }
}
```

Each field is present only where the provider returns it.

* `payment_method_description`: what the customer paid with, as a label you can show, such as `PayPal` or `Apple Pay`.
* `account`: the customer, as the provider knows them.
  * `gateway_key`: the provider's identifier for the customer. Keep it if you want to recognise a returning customer.
  * `first_name`, `last_name`, `email`, `phone`: the customer's details. Phone numbers are formatted as the provider returns them, so you may want to normalise them.
  * `address`: the customer's billing address.
* `shipping`: the shipping address the customer chose, when you set `capture_shipping`.
* `gateway_data`: what you pay with, when you set `payment_token`. Its content differs by provider (the example is shortened). Don't read or change it: pass it unchanged to [Create a payment](/platforms/reference/operations/createpayment/) or [Create a payment method](/platforms/reference/operations/createpaymentmethod/), once.

### on_error

Called when the customer cancels, or something goes wrong. Show errors to the customer.

```json
{
  "cancel": false,
  "error": "An error occurred"
}
```

* `cancel`: `true` when the customer cancelled.
* `error`: a message, when the cause was not a cancel.

## Return value

`Shuttle.authenticate` returns a Promise. It resolves to `{ is_available: true }` when at least one provider rendered buttons, and `{ is_available: false }` when none did.

## Addresses

Addresses use Shuttle's address fields:

| Field | Holds |
| --- | --- |
| `line1`, `line2`, `line3` | Street address |
| `line4` | City |
| `line5` | Postcode or ZIP code |
| `line6` | State, county or region |
| `country` | Country, as a two-letter ISO code such as `US` |

## Layout

The buttons belong to each provider, so their appearance is the provider's. shuttle.js adds the class `shuttle-express-checkout` to your element and places each provider's buttons in a child element with the class `shuttle-express-checkout-option`, one under another, `0.75rem` apart. To change the spacing, set `--shuttle-express-checkout-gap` on your element:

```css
#shuttle-express-checkout {
  --shuttle-express-checkout-gap: 1rem;
}
```