Set up & Integrate
Learn how to set up and integrate your Hosted Checkout.
The key steps to getting your Hosted Checkout working:
- Create a checkout by generating a payment link.
- Construct the payment link by appending it to the environment you wish to target and present it to the customer.
- Handle the redirect to present payment confirmation to the customer.
- 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×tamp=1657183950&hash=d201a2ed66573043ff0b210de295c3d565b70aa1ffb35534bd29ce77a5987f14
The keys and values that will be present:
Field | Type | Description |
---|---|---|
status | string | The final status of the payment. For a list of all possible statuses see here. |
transaction_id | string | UUID assigned by Acquired.com. |
order_id | string | The order ID value that was passed in the payment-link request. |
order_active | boolean | Whether the order ID is still active or not, and whether payment can be reattempted by the same payment link. |
timestamp | integer | Exact date when response was posted to the redirect URL in UNIX timestamp format. |
hash | string | A calculated hash value which can be used to verify the integrity of the data. |
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:
-
Concatenate the parameters in this order: status . transaction_id . order_id . timestamp
`executed1970f4e1-95da-4859-b275-e9ac83f05eb1your_unique_reference_11657183950`
-
SHA256 encrypt the resulting string.
`4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007`
-
Append your
app_key
value to the hash value of a string.`4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007app_key`
-
SHA256 encrypt the resulting string again.
`4e7e127a6ab8e7c4d73100e0c959eb42e1d61adff6b641c6ea7e4690e44cbff0`
-
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
status_update
webhookThe 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
customer_new
and card_new
webhooksIf 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:
- Navigate to Settings > Payment Methods > Apple Pay
- Under Web Domains, hit + Add Domain
- 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

Updated 14 days ago