Upfront Payment Widget

Embed the Upfront Payment Widget

As part of the spend journey you will call the authorisation endpoint to make the purchase. If an upfront payment is required, the response will look as below.

You can then use the redirect href to load the upfront payment widget to allow the customer to continue the spend journey.
You should also add a redirect_uri to the query string of the redirect href.

Get control back from the Upfront Payment Widget

The Upfront Payment Widget will try and collect a card payment from the customer.
On completion of this or if any unrecoverable error has occured, the widget will post serialized data back to the redirect_uri provided in the query string.
The data returned by the widget must be deserialized before usage.

Expected POST request payloads

The payload will have different formats based on the outcome of upfront payment.
The expected formats are:

Success

You should then call the authorisation endpoint again, adding the payment token and the payment session id to the request.

Declined

The widget will send a Declined event when the payment has been declined by the card issuer or payment gateway. This is distinct from technical errors and indicates that the payment was processed but not approved.

When you receive this event, you should handle it appropriately for your customer journey, which may include redirecting to a payment declined page that explains the payment was not successful.

Errors

Error Types:

• TechnicalError - Technical failures during payment processing (e.g., service unavailable, fingerprinting timeout)
• CardPaymentError - Errors from the payment service during card processing
• AuthenticationError - 3D Secure authentication failures
• MaxNumberOfAttemptsReachedError - Customer has exceeded the maximum number of payment attempts (3 attempts)

Handling Errors:

Some errors are handled internally by the widget and allow the customer to retry their payment without any action from your application. These retry scenarios are invisible to your integration.

When you receive an Error event from the widget, it indicates an unrecoverable error that should terminate the spend flow. You should:

• Display an appropriate error page to the customer
• Log the error for debugging purposes
• Provide the customer with options to exit the flow or contact support

Google analytics

In order to activate the GA tracking inside the widget the query parameter analyticsCookieConsent=true needs to be passed in the url. This parameter is optional and if not sent the GA tracking will not be activated.