Set up & Integrate

The key steps to getting your Hosted Checkout working:

1. Create a checkout by generating a payment link.
2. Construct the payment link by appending it to the environment you wish to target and present it to the customer.
3. Handle the redirect to present payment confirmation to the customer.
4. Use webhook notifications to update merchant systems.

Also important:

• How to save card details from a customer's checkout, to power recurring transactions or a one-click checkout experience.
• Common checkout payment flows will help determine what gets displayed to customers and the resulting behaviour of the checkout, depending on what details are provided initially.

Creating a Hosted Checkout Session

Create a Hosted Checkout session by first generating a payment link which contains details of the order or payment and then construct a payment link that can be shared with customers.

Generate a payment link

Make an API request to our payment-links endpoint to generate a link_id.

Request:

{
  "transaction": {
    "order_id": "unique_order_id",
    "amount": 15.02,
    "currency": "gbp"
  }
}

Response

{
  "status": "success",
  "link_id": "4b0a3a3d-b53c-c805-e15a-82ba6583cca4"
}

Construct the payment link

Add the returned {link_id} to the environment that you wish to target. This is how the above example would look in the production environment - https://pay.acquired.com/v1/4b0a3a3d-b53c-c805-e15a-82ba6583cca4

Then share the resulting payment link with your customer through email, SMS, with a website link or through other channels.

QA URL: https://test-pay.acquired.com/v1/{link_id}

Production URL: https://pay.acquired.com/v1/{link_id}

Handling the customer redirect

When the user has completed payment they will be redirected to a payment outcome page. This redirect can be handled by Acquired.com or by you.

• When the Redirect URL is Enabled then Acquired.com will present the customer with our own hosted payment outcome screens.
• When the Redirect URL is Disabled then Acquired.com will send a form POST to the redirect_url configured in the Hub, unless a different URL is provided in the payment-links request.

Configure your Redirect URL from within the Hub at Settings > Hosted Checkout > +Add Responses.

Receive a form POST

To present customers with the payment status, Acquired.com will send a form POST to the redirect_url in format application/x-www-form-urlencoded.

status=executed&transaction_id=1970f4e1-95da-4859-b275-e9ac83f05eb1&order_id=your_unique_reference_1&order_active=undefined&timestamp=1657183950&hash=d201a2ed66573043ff0b210de295c3d565b70aa1ffb35534bd29ce77a5987f14

The keys and values that will be present:

Verify the integrity of the form data

A hash value will be calculated every time a customer is navigated to the redirect_url. This allows you to guarantee the authenticity of the data.

To do this, generate a new hash value and compare it to the returned hash value. If the hash values match then the data has not been altered and the origin and integrity of the data has been verified.

To calculate the hash value, you'll need to do the following:

1. Concatenate the parameters in this order: status . transaction_id . order_id . timestamp

     `executed1970f4e1-95da-4859-b275-e9ac83f05eb1your_unique_reference_11657183950`
   

2. SHA256 encrypt the resulting string.

     `4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007`
   

3. Append your app_key value to the hash value of a string.

     `4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007app_key`
   

4. SHA256 encrypt the resulting string again.

     `4e7e127a6ab8e7c4d73100e0c959eb42e1d61adff6b641c6ea7e4690e44cbff0`
   

5. Compare the generated hash value to the previous returned hash value.

Webhook notifications

Webhooks should be used to update merchant applications with the final status of each payment, as opposed to the redirect form POST. Webhooks are server to server notifications unaffected by potential issues with the front end system and user error.

The webhook notifications will be sent to the webhook_url configured in the Hub Settings for Hosted Checkout, unless a different URL is provided in the payment-links request.

status_update webhook

The primary webhook delivered for payments made from the checkout is the status_update webhook, providing the final status of payment requests. This webhook may also deliver notification of transitionary statuses outlined in the statuses page.

customer_new and card_new webhooks

If the checkout creates a customer or card in the Acquired.com system, then a webhook notification will be delivered. See more about when the checkout will create a customer or card below.

Set up your payment methods

Managing the payment methods included on your checkout and customising the checkout page design is covered in Configure your Checkout.

You can also use the payment_methods array in the /payment-links request to define which payment methods are offered in a specific checkout payment link.

Card payments

Nothing is required of merchants to get started with card payments on Hosted Checkout. If you want to authenticate payments using EMV 3DS though, you must add a contact_url in the Hub or in the tds object of your payment-links request.

Apple Pay

Since the Hosted Checkout is fully hosted by Acquired.com, merchants will be automatically registered with Apple using our certificates and on the Hosted Checkout domain. Unlike a direct integration to Apple Pay, there's nothing required from merchants before accepting Apple Pay payments on Hosted Checkout.

Apple Pay Domain Registration

If the registration with Apple doesn't complete automatically, then follow these steps:

1. Navigate to Settings > Payment Methods > Apple Pay
2. Under Web Domains, hit + Add Domain
3. Enter the domain: pay.acquired.com (PROD) or test-pay.acquired.com (QA)

Testing Apple Pay

In order to test Apple Pay payments you must create a sandbox test account. View our Testing Apple Pay guide here.

Google Pay

As with Apple Pay, nothing is required to add Google Pay to your Hosted Checkout as the checkout is fully hosted by Acquired.com. Note that your company website stored in Settings > Company Details will be included with each Google Pay payment request.

It is important to note also that some merchants may not be able to access Google Pay, depending on their sector. See the Google Pay Policies For Business for more detail.

For information on a direct integration with Google Pay, view our Google Pay guides.

Testing Google Pay

In order to test Google Pay payments, you must use the Google Pay test card suite. View our Testing Google Pay guide here.

Pay by Bank

Offering Acquired.com's proprietary Pay by Bank solution as a payment method in the checkout alongside cards and digital wallets like Apple Pay gives customers incredible choice to pay how they want.

Saving card details

The checkout supports saving customer card details which can be used later for recurring payments or to offer returning customers a one-click checkout.

Recurring payments

In order to process recurring payments from the checkout, is_recurring flag must be true in the payment links request. You must also provide either a customer ID for an existing customer or a customer reference for a new customer.

The customer's checkout page will then load with a notice that their card details will be stored in order to process future payments.

One-click checkout

If a returning customer is checking out and they have existing cards saved in the Acquired system, then they will be presented with a one-click checkout page which requires only the card's security code to complete payment.

To enable this, make sure the 'save cards' option in Settings > Hosted Checkout > Cards Settings is turned on. When enabled, customers will be offered an opt-in checkbox to save their card details at checkout.

Creating customers and cards

Saving card details requires a customer to be saved already as all cards, payments and transactions are linked back to the customer_id. The Hosted Checkout can automatically handle the creation of customers and cards for you in the Acquired.com system.

To enable the saving of card details, turn on the 'save cards' option in Settings > Hosted Checkout > Cards Settings. When enabled, customers will be offered an opt-in checkbox to save their card details at checkout.

A customer_id will be created when at least a customer reference is included within the payment links request, and will be created whenever the customer attempts payment. If a customer_id is instead provided in the payment links request, then any card IDs will be created against that customer_id.

A card_id will be created only when the customer completes a successful payment.

New customer and new card webhooks

Whenever a new customer ID or card ID is created by the checkout, a webhook notification will be sent to the webhook_url configured in the Hub, unless a different URL is provided in the payment-links request.

Hosted Checkout payment flows

When utilising our Hosted Checkout there are different payment routes that the cardholder can follow, depending on multiple factors. See the below process maps detailing the potential payment flows for both recurring and non-recurring payment requests.

For recurring payments

For non-recurring payments