Set up & Integrate

Getting started

This first section gives an overview of the four steps necessary to make your first API call.

Step 1: Sign up

To start your development journey, create an account with Acquired.com.

1. Contact us and we will create your test account. Once we have created your account you will receive an activation email.
2. Visit our test portal and sign in using your registered credentials.

Step 2: Authenticate with the API

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

Step 3: Configure your response options

The next step is to set your Redirect URL and Webhook URL. These are configurable within the Settings section of the Hub.

1. In the Settings tab, select Payment Methods > Pay by Bank.
2. Click Add Responses and input your Redirect URL and Webhook URL.
3. Select your preferred option for the Display Responses Configuration and click Save.

Step 4: Make your first API request

You can now test that you are able to access our API by requesting an access_token.

1. Navigate to Settings > API Access (like you did previously in step 2).
2. Click into the app_key field and expose.
3. Copy and paste both the app_id and app_key values which can then be used within the code.

Request:

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

Response:

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

Pay by Bank checkout

In this section we will demonstrate how to generate a payment-link request.

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": "your_unique_reference_1",
      "amount": 14.99,
      "currency": "GBP"
   },
   "payment": {
      "single_immediate_payment": {
         "reference": "custom ref 001"
      }
   }
}

Response:

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

📘

Note

View the API reference payment-links documentationhere.

Step 2: Construct the payment link

1. Append 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/{link_id}

Step 3: Return to merchant

Once the user has completed the payment we will redirect them to your redirect_url configured in the Hub, unless a different URL was provided in your initial 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 update your application with the final status of each payment.

Handle the customer redirect

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

Step 1: Send a form post

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 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

See below for a table of the keys and values that will be present:

Step 2: Verify the integrity of the form data

A hash value will be calculated by Acquired.com every time we navigate the customer back to the redirect_url used for the payment. This allows you to guarantee the authenticity of the data.

To do this you can 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.