Web: Headless (advanced)

The headless integration allows for greater flexibility and customization on how you display the payment method options to your customers, leveraging the ProcessOut API. This section covers the necessary steps to build your payment sheet, from displaying the payment methods to completing the payment.

Retrieve payment methods from the ProcessOut API

After an invoice is created from your server, the frontend can retrieve the payment methods available for the invoice by calling the Fetch an invoice endpoint.

Dynamic Checkout processes your project configuration and returns the available payment methods in the invoice response, under a invoice.payment_methods array. Each payment method has a type property that lets your application know how it should be handled. The same payment method type can be repeated multiple times.

Available payment method types are:

Additionally, each object contains a property named after the payment method type. It contains configuration specific to the payment method. For example, a card payment method will have a card property which contains the card configuration. More information on the available properties can be found in the API reference.

Processing each payment method’s type and configuration is required in order to render the UI and to initiate the payment properly.

Render payment methods

All payment method objects have a display object with presentation elements, such as the name and logo URLs. These can be used to render and style payment method interface elements on your platform of choice.

As mentioned above, payment method configuration included in each payment method object can be used in respective integrations to configure and customize behavior.

Apple Pay and Google Pay

To render the Apple Pay and Google Pay buttons using their respective third-party SDKs, you can follow these instructions:

• Using Apple Pay
• Using Google Pay

Card

To render the card form, you can use the ProcessOut SDKs by following these instructions:

• Tokenizing a card in the browser
• Tokenizing a card in a mobile app

Alternatively, you can choose to render the card form and collect details directly from your app, as long as your organization and application are PCI compliant.

Alternative payment methods

There are two types of alternative payment methods:

• Hosted Payment Page - The apm.redirect_urlproperty is available in the configuration. You should configure a button event handler to open the third-party payment provider website for the customer to complete their payment.
• Embedded Components - The apm.redirect_urlis absent, but the apm.gateway_configuration_id property is available in the configuration. You should follow these instructions to display the UI components and the payment sheet. Alternatively, if you prefer to have full control of the UI components, you can follow the Server to Server instructions.

Optional: display saved payment methods

Payment methods previously saved for future use by the customer associated with the invoice can be presented again. Saving a payment method creates a customer token that is returned alongside the normal list of payment methods. This feature allows users to complete the checkout flow faster without having to re-enter their card or APM details.

To provide this capability without compromising security, we’ve introduced the concept of client secret. A client secret is an opaque value returned by the ProcessOut API during the invoice creation. It should be used by your frontend to retrieve the invoice and the customer’s payment methods. The client secret is only valid for a short duration, so you should always get a fresh one from the ProcessOut API before rendering the payment form.

The client secret is available in the header of the invoice response as x-processout-client-secret. The frontend should fetch the invoice and pass its value in the header of the request as x-processout-client-secret.

You can set whether to allow saving payment methods in your Dynamic Checkout configuration in the ProcessOut Dashboard. This sets the saving_allowed field in the invoice payment methods response, which can be used, for example, to render a “Save” checkbox in the payment form.

Complete the payment

Apple Pay, Google Pay and cards

When a customer selects a Google Pay, Apple Pay or card payment method, you can use the token as a source when authorizing the payment. In some cases you may have to redirect the customer for 3-D Secure authentication during the payment flow.

Alternative Payment Methods (APM)

When a customer selects an APM, an APM payment token is provided and can be used as a source when authorizing the payment. For Embedded Components the payment authorization is done using separate endpoints.

📘

Note that some payment providers do not support authorize-only payments. In such cases, if you accept to immediately attempt to capture the payment, you can use the parameter allow_fallback_to_sale. This allows ProcessOut to capture the transaction directly and return the result. Otherwise, the authorization will fail.

Optional: Saving and using saved payment methods

If a customer chooses to save a card or APM for future use during the payment flow, you should pass the client secret and set the parameter save_source when authorizing the payment. For APMs, instead of using redirect_url from the payment method configuration, authorize the payment using the gateway_configuration_id as a source.

In some cases the response may contain a URL where the user should be redirected to perform 3-D Secure authentication or to complete the payment on the payment provider’s website.

When a customer selects a previously-saved payment method, you can use the customer token as source when authorizing the payment. If the customer token configuration contains a redirect_url property, it should be used to redirect the user. This will allow them to authenticate before your application can authorize the payment using the returned APM payment token.