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": "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 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;
}