Set up & Integrate

Getting started

In this first section we will detail how to get started with your Hosted Checkout and outline the steps needed to request your first API call.

Step 1: Sign up

To start your development journey you need to create an account with Acquired.com. View our Getting Started guide here.

Step 2: Authenticate with the API

To understand how to authenticate with our API, follow our Authentication guide here.

Step 3: Make your first API request

You now have the required information to make your first API request by requesting an access_token.

1. In the Hub, navigate to Settings > API Access.
2. Click into the app_key field and expose the value.
3. Copy and paste both the app_id and app_key values and pass through your request to generate an access_token.

Request:

{
    "app_id": "87656778",
    "app_key": "9084j54309k..."
}

Response:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "{token}"
}

Step 4: Configure your checkout response options

The next step is to configure your Redirect URL and Webhook URL from within the Hub.

1. Log into the Hub.
2. Go to Settings > Hosted Checkout.
3. Click on + Add Responses and input your Redirect URL and Webhook URL in the required fields.
4. Select your preferred option for the Display Responses Configuration and click Save.

When the Redirect URL is Enabled then Acquired.com will send a form POST to the URL. See the Handle the customer redirect section later on this page for how to handle the form POST.

When the Redirect URL is Disabled then Acquired.com will present the customer with our own hosted payment outcome screens.

📘

Using the redirect URL and webhook URL.

The form POST to the redirect URL can be used to present confirmation of the payment status to users.

The webhook notifications sent to the webhook URL should be used to update merchant applications with the final status of each payment.

Set up your Hosted Checkout

This section is short because setting up your Hosted Checkout requires almost no development work. Managing the payment methods included on your checkout and customising the checkout page design is covered in Configure your Checkout.

Set Up 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.

Once registered on the Hosted Checkout domain, the relevant URL will be added to the list of Web Domains in the Apple Pay Settings of your Acquired.com Hub.

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

Creating a Hosted Checkout Session

In this section we will demonstrate how to create a Hosted Checkout session by first generating a payment-link which contains details of the order or payment and then how to construct a payment link that can be shared with customers.

We'll also cover what happens to a customer after they have completed the payment and get redirected to a URL of your choosing.

Step 1: Generate a payment-link request

1. Make a single API request to our payment-link endpoint to generate a link_id.

Request:

{
    "transaction": {
        "order_id": "unique_order_id",
        "amount": 15.02,
        "currency": "gbp"
    },
    "tds": {
        "is_active": true,
        "contact_url": "https://yourdomain.com/contact"
    },
    "redirect_url": "https://yourdomain.com/redirect"
}

Response

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

📘

Note

For more information, visit our payment link API reference documentation.

Step 2: Construct the payment link

1. Add the returned link_id to the environment that you wish to target.
2. Share the resulting payment link with your customer through email, SMS, with a website link or through other channels.

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

Step 3: Return to merchant

When the user has completed the payment we will redirect them to the redirect_url configured in the Hub (unless a different URL is provided in the payment-link request).

In order for you to be able to present your customer with the payment status, we will send a form POST to the redirect URL.

We also send webhook notifications to the webhook_url configured in the Hub (unless a different URL is provided in the payment-link request). Webhooks should be used to update merchant applications with the final status of each payment.

Handling the customer redirect

In this section we will demonstrate how to present confirmation of the payment status to users.

Step 1: 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×tamp=1657183950&hash=d201a2ed66573043ff0b210de295c3d565b70aa1ffb35534bd29ce77a5987f14

The keys and values that will be present:

Step 2: Verify the integrity of the form data

A hash value will be calculated every time a customer is navigated to the redirect_url used for the payment. 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.