Pay by Bank

Learn how to set up your account and build your Pay by Bank integration.

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:

FieldTypeDescription
statusstringThe final status of the payment, for all possible statuses see here.
transaction_idstringUUID assigned by Acquired.com.
order_idstringThe order ID value that was passed in the payment-link request.
timestampintegerExact date when response was posted to the redirect URL in UNIX timestamp format.
hashstringA calculated hash value which can be used to verify the integrity of the data.

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

  1. SHA256 encrypt the resulting string.

4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007

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

4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007app_key

  1. SHA256 encrypt the resulting string again.

4e7e127a6ab8e7c4d73100e0c959eb42e1d61adff6b641c6ea7e4690e44cbff0

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