Express Checkout options

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.

{
  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.
`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). 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 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:

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.

{
  "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.

{
  "payment_method_description": "Apple Pay",
  "account": {
    "gateway_key": "[email protected]",
    "first_name": "Jack",
    "last_name": "Smith",
    "email": "[email protected]",
    "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 or Create a payment method, once.

on_error

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

{
  "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:

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