Payment form

The payment form is the screen your merchants' customers use to pay. It is the white-labelled checkout Shuttle serves on your behalf: it carries your branding, offers whichever payment methods the merchant's gateway setup allows, collects the card or bank details, handles any bank authentication step, and hands the result back to the page that opened it. The same screen also serves as the "save a card" step when a merchant wants to store a payment method without charging it straight away.

Where to find it

Customers do not navigate to this form and it has no address they can visit. Your platform opens it for them: your integration creates a checkout request saying what is being paid for, by whom, and under what constraints, and then opens the form in a popup, in a full page, or embedded inside your own page. Customers reach it by pressing your own "Pay" or "Add card" buttons.

What you see

Almost nothing on this form is fixed by Shuttle. Two things decide what a customer meets: what your checkout request set, and what the merchant's gateways support.

For most of what follows, your request has three choices. Fix it, and the customer sees it as a heading they cannot change. Default it, and the customer sees your value already filled in and may change it. Leave it out, and the customer chooses from whatever the merchant has enabled. Amount, currency, frequency and start date all work this way, which is why two merchants on your platform can present very different pages.

The exception is the payment details themselves. The card or bank fields are always the customer's to complete, and your platform never sees them.

Read the list below as everything the form is capable of showing. Against each item is who decides it.

• Your logo and page title, from the merchant's branding. The customer's name or email appears underneath when your request identifies them.
• The amount and currency. Yours to fix, default or leave open. Fixed, they are a heading. Left open, the customer types an amount and picks from the currencies the merchant has enabled. Merchants can also offer a row of suggested amounts with an "other" option.
• A description of what is being paid for, which your request supplies, and a choice of initiative (fund, campaign or product line), which the customer makes when the merchant has more than one and your request does not name it.
• Recurring payment options: frequency, an optional later start date and an optional fixed number of payments. Same three choices as the amount. Fixed, the customer sees a summary such as "£10 / monthly" rather than the controls. Where your request carries a schedule of instalments, the first instalment date is shown with a link to the full schedule.
• The customer's saved cards, shown only when your request identifies a returning customer who has some. The customer chooses between a saved card and entering a new one.
• The payment details: card number, expiry and security code, or the equivalent bank fields for SEPA, BACS or ACH where the merchant offers them. Always the customer's to enter. A toggle appears when both card and bank are available.
• Extra fields the merchant's gateway requires: name on the account, email, phone, postcode or ZIP, and a billing address. Which of these appear is the gateway's decision, not yours and not the merchant's.
• A save this card tick box, when your request allows saving and the customer is present. Your request can also pre-tick it or hide it entirely.
• Wallet and gateway buttons: PayPal, Apple Pay, Google Pay, Click to Pay, and any gateway-hosted or offline buttons. Which appear is set by the merchant's gateway setup, not by your request, and they are separated from the card form by an "or" divider.

What you can do

Things to note

• Bank authentication. When the card issuer requires 3D Secure, the customer is shown the issuer's challenge inside the checkout, or in a separate window where the gateway insists on one. They can cancel and return to the form. Once the challenge succeeds the payment completes and the receipt is shown.

• Security code for stored cards. Some gateways need the security code again before a stored card, or a card supplied by a wallet, can be charged. The customer sees a single security-code step between the form and the confirmation.

• Customer present or not. Your request tells Shuttle whether the customer is at the keyboard or a member of the merchant's staff is entering details for them. Saving cards and asking for the security code only happen when the customer is present.

• Save-card checkout. When your request asks only to store a card against an existing recurring agreement that has money outstanding, the form warns the customer that the outstanding amount will be taken with the new card and that it will be used for future payments.

• Duplicate requests. If your platform opens the same checkout request twice after it has already been paid, the customer is told the payment was already made and can continue to the receipt rather than paying again.

• Embedded mode. When the checkout is embedded inside your page rather than opened as its own page, the header is trimmed, the amount step and the card step are shown one at a time, and your page can lock the form while it updates the request. See Embedding the checkout in your own page.

• When nothing can be offered. If the merchant's gateways do not support the requested currency, payment method, or initiative, the customer sees a clear "not available" message instead of an empty form, and Shuttle records the event so the configuration can be fixed.

• Bot protection. Merchants can turn on an invisible CAPTCHA check, which runs when the customer submits and does not normally interrupt them.

• Languages. The form follows the language your platform passes, then the customer's browser language, and falls back to English.

Related tasks

• Taking a payment
• Saving a payment method without charging it
• Setting up a recurring payment
• Embedding the checkout in your own page