Set up & Integrate
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.
- Contact us and we will create your test account. Once we have created your account you will receive an activation email.
- 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.
- In the Settings tab, select Payment Methods > Pay by Bank.
- Click Add Responses and input your Redirect URL and Webhook URL.
- 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
.
- Navigate to Settings > API Access (like you did previously in step 2).
- Click into the
app_key
field and expose. - Copy and paste both the
app_id
andapp_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
- 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
- Append the returned
link_id
to the environment that you wish to target. - 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:
Field | Type | Description |
---|---|---|
status | string | The final status of the payment, for 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. |
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. |
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:
- 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.
Updated 23 days ago