Pay by Bank

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. 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. Follow our guide here.

Step 4: 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. (See further information below).

Display Responses Configuration: if this setting is enabled then we will present confirmation of the payment to the user before sending them back to your website. If set to disable then we will navigate the user to the redirect URL without presenting confirmation of the payment.

📘

Note

We recommend that you configure the webhook URL, as it enables you to receive webhook notifications of the final status of the payment.

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-link documentation here.

Step 2: Construct the payment link

1. Append the returned {link_id} to the environment that you wish to target. This is how the above example would look when targeting the production environment - https://pay.acquired.com/4b0a3a3d-b53c-c805-e15a-82ba6583cca4
2. 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/{link_id}

Production URL: https://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=success&transaction_id=1970f4e1-95da-4859-b275-e9ac83f05eb1&order_id=your_unique_reference_1&timestamp=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.

Webhook notifications

While presenting payment confirmation to customers should be handled via the form POST described above, Acquired.com 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, 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.

status_update webhook

The primary webhook delivered for 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.

To view more information on webhooks, including an example webhook notification payload, go to our Webhook Notifications guide.

Customise your checkout

Customise the look and feel of your Checkout to meet your company branding.

Including:

• Upload a logo or icon.
• Customise the Checkout page background colour, header colour and button colour.

Create a hosted checkout template

1. Log into the Hub.
2. Go to Settings > Payment Methods and select Pay by Bank.
3. Select the Customise button.
4. Input a Template Name.
5. Add custom elements, including logo, background colour and header colour.
6. Save the template!

Once your template has been saved, it will be visible in the Customisation table.

See the below video demonstrating these steps:

Display your hosted checkout template

There is no limit to the number of custom templates that you can create. Acquired.com will display your default Checkout template, unless otherwise specified.

If you require more than one custom template, then you can specify which template you wish to display. You can do this by passing the template_id parameter in your payment-link request and populating this field with the template ID value generated for your desired template. (The template_id is obtained from the customisation section within the Hub).

See below example:

{
  "template_id": "92351a6c-45b1-456e-8430-0969dce843ea",
   "transaction": {
     "order_id": "your_unique_reference_1",
     "amount": 14.99,
     "currency": "gbp"
   },
   "payment": {
     "single_immediate_payment": {
       "reference": "Custom Ref 001"
     }
   }
}

Update your default checkout template

To update your default Checkout template simply navigate to the customisation table and complete the following:

1. In the Hub, go to Settings > Payment Methods > Pay by Bank.
2. In the Customisation table, click on the action ellipsis on the template that you want to use and select Set as Default Template.