Webhooks
A webhook is an automatic notification that we can send directly to your system after an event takes place against your account. Rather than requiring you to pull information via our API, webhook notifications will push information directly to a URL that is specified by you via HTTPS POST.
The solution allows you, rather than sending API requests, to update your internal systems automatically, resulting in increased automation and enhanced efficiency.
Configuration
With all webhooks you will be required to complete configuration within the Acquired portal in order to activate the service, selecting the webhooks which are in-scope for you and setting the URL(s) that Acquired are to target when sending webhook notifications. If the immediate webhook notification solution interests you, just contact your account manager and they will help you out.
For webhook events / alerts, your server should respond within 10 seconds with a HTTP 200 status code to indicate you have successfully received the message. If we receive anything other than a HTTP 200 (or if there is no response within 10 seconds) we will retry the post to your webhook URL every 10 minutes for the next hour, if at which point we have still not received a successful response, we will stop sending the webhook.
There are a number of different webhooks that we offer. For a full list of the events we send webhooks for, please seehere.
Security
Before you can begin to receive webhook notifications, you will need to open your firewall to allow incoming messages from our IPs. Contact support@acquired.com to receive them.
After our IP addresses are whitelisted on your side, you can begin to receive webhook notifications. If you would like to further validate that the webhooks are coming from us, you can do so by verifying the hash value we send through with the webhook by making sure the hash we have sent through with the webhook corresponds to the hash you have calculated. Whilst not required, we would recommend implementing the logic to improve the security of your integration.
Webhook Hash
To calculate the hash value, please follow the steps listed below:
-
Concatenate the below request parameters excluding your company hash.
- id
- timestamp
- company_id
- event
-
SHA256 encrypt the resulting string:
4107fb43722f1aeaaa4cb6330306b394ce84f97f5fd3e00d4aaedab9a5084d51
-
Then, append your company_hashcode to the string generated in step two and SHA256 encrypt again:
4107fb43722f1aeaaa4cb6330306b394ce84f97f5fd3e00d4aaedab9a5084d51company_hashcode
ca8358ac0c846b50b5e998658d17f8518aca1baea67f1c3d31e5a5d9c5d2220d
id . timestamp . company_id . event
//C9EDECD6-D0B5-AED5-48E6-EF235ECD5A5420200626110608207dispute_new
With us so far? To get you started, here are samples of code to generate encrypted hash values:
$param = array(
'id'=>'C9EDECD6-D0B5-AED5-48E6-EF235ECD5A54',
'timestamp'=>'20200626110608',
'company_id'=>'207',
'event'=>'dispute_new',
);
$company_hashcode ='company_hashcode';
// $plain = implode('', $param);
$plain = $param["id"] . $param["timestamp"] . $param["company_id"] . $param["event"];
// $plain ="C9EDECD6-D0B5-AED5-48E6-EF235ECD5A5420200626110608207dispute_new";
$temp = hash('sha256', $plain);
// $temp = "4107fb43722f1aeaaa4cb6330306b394ce84f97f5fd3e00d4aaedab9a5084d51";
$hash = hash('sha256', $temp.$company_hashcode);
//$hash = "ca8358ac0c846b50b5e998658d17f8518aca1baea67f1c3d31e5a5d9c5d2220d"
echo "- plain is {$plain}\n";
echo "-- temp is {$temp}\n";
echo "--- hash is {$hash}\n";
import java.util.Map;
import java.util.HashMap;
import java.security.MessageDigest;
import java.nio.charset.Charset;
import java.security.NoSuchAlgorithmException;
import java.io.UnsupportedEncodingException;
public class GenerateHash {
public static void main(String[] args) {
GenerateHash.getwebhookHash();
}
private static String getwebhookHash() {
String companyHash="company_hashcode";
String webhookHash="";
Map map = new HashMap();
map.put("id", "C9EDECD6-D0B5-AED5-48E6-EF235ECD5A54");
map.put("timestamp", "20200626110608");
map.put("company_id", "207");
map.put("event", "dispute_new");
String plain = map.get("id") + map.get("timestamp") + map.get("company_id") + map.get("event");
// plain = "C9EDECD6-D0B5-AED5-48E6-EF235ECD5A5420200626110608207dispute_new";
String temp = String2SHA256(plain);
// temp = "4107fb43722f1aeaaa4cb6330306b394ce84f97f5fd3e00d4aaedab9a5084d51";
webhookHash = String2SHA256( temp + companyHash);
// webhookHash = "ca8358ac0c846b50b5e998658d17f8518aca1baea67f1c3d31e5a5d9c5d2220d";
System.out.println("- plain is " + plain);
System.out.println("- temp is " + temp);
System.out.println("- plain is " + webhookHash);
return "";
}
private static String String2SHA256(String str) {
MessageDigest messageDigest;
String encodeStr = "";
try {
messageDigest = MessageDigest.getInstance("SHA-256");
messageDigest.update(str.getBytes("UTF-8"));
encodeStr = byte2Hex(messageDigest.digest());
} catch (NoSuchAlgorithmException e) {
e.printStackTrace();
} catch (UnsupportedEncodingException e) {
e.printStackTrace();
}
return encodeStr;
}
private static String byte2Hex(byte[] bytes) {
StringBuffer stringBuffer = new StringBuffer();
String temp = null;
for (int i = 0; i < bytes.length; i++) {
temp = Integer.toHexString(bytes[i] & 0xFF);
if (temp.length() == 1) {
stringBuffer.append("0");
}
stringBuffer.append(temp);
}
return stringBuffer.toString();
}
}
using System;
using System.Collections.Generic;
using System.Text;
using System.Security.Cryptography;
namespace GenerateHashApplication
{
class GenerateHash
{
public static void Main(string[] args)
{
string companyHashCode = "company_hashcode";
Dictionary param = new Dictionary
{
["id"] = "C9EDECD6-D0B5-AED5-48E6-EF235ECD5A54",
["timestamp"] = "20200626110608",
["company_id"] = "207",
["event"] = "dispute_new"
};
String plain = param["id"] + param["timestamp"] + param["company_id"] + param["event"];
// plain = "C9EDECD6-D0B5-AED5-48E6-EF235ECD5A5420200626110608207dispute_new";
string temp = SHA256(plain);
// temp = "4107fb43722f1aeaaa4cb6330306b394ce84f97f5fd3e00d4aaedab9a5084d51";
string webhookHash = SHA256(temp + companyHashCode);
// webhookHash = "ca8358ac0c846b50b5e998658d17f8518aca1baea67f1c3d31e5a5d9c5d2220d";
Console.WriteLine("- plain is " + plain);
Console.WriteLine("- temp is " + temp);
Console.WriteLine("- hash is " + webhookHash);
}
public static string SHA256(string str)
{
byte[] SHA256Data = Encoding.UTF8.GetBytes(str);
SHA256Managed Sha256 = new SHA256Managed();
byte[] by = Sha256.ComputeHash(SHA256Data);
return BitConverter.ToString(by).Replace("-", "").ToLower(); //64
}
}
}
Available Events
We currently have three categories of webhooks:
- Dispute Alerts
- Fraud Alerts
- Transaction Alerts
Dispute Webhooks
Name | Event | Use Case |
---|---|---|
Dispute Alert | dispute_new |
All new disputes / chargebacks instances will be sent to you. |
Fraud Webhooks
Name | Event | Use Case |
---|---|---|
New Fraud Alert | fraud_new |
An alert to notify you in the event you receive a TC40/SAFE entry. |
Transaction Update Webhooks (Banking Services / Faster Payments)
Name | Event | Use Case |
---|---|---|
Transaction Outcome Response | transaction_outcome |
Whenever a faster payments/banking transaction is processed using the Acquired.com platform we will send you a notification. |
Funds Received Alert | funds_received |
Whenever any funds are received by one of your Acquired.com bank accounts, we will send you a notification. |
Transaction Update Alert | transaction_update |
Whenever a faster payments/banking transaction is updated using the Acquired.com platform we will send you a notification. |
Token Update Response | account_updater |
We confirm the outcome of your token update requests via webhook notification. |
Dashboard Response | dashboard_response |
Triggered whenever a transaction is processed via the hub (Via the VT / a transaction is Voided / Refunded). |
Sample Webhooks
Please see webhook example parameters below and an exmaple of the webhook alongside:
Dispute Alert
Parameter | Format | Length | Description |
---|---|---|---|
id | string |
36 | The unique reference for the webhook. |
timestamp | date |
14 | Date and time of webhook. |
company_id | int |
1-11 | API Company ID we issue to merchants. |
hash | string |
64 | Verification hash value. |
event | string |
36 | The event for which the webhook is being triggered. |
list | object |
||
mid | int |
1-11 | Merchant ID the transaction was processed through. |
transaction_id | int |
1-10 | Unique ID we generate to identify the transaction. |
merchant_order_id | string |
1-50 | Unique ID you’ll use to identify each transaction, repeated from the request. |
parent_id | string |
1-10 | transaction_id value we generated and returned in the original request. |
arn | string |
0-64 | Value set by the acquirer to track the transaction, when present. |
rrn | string |
0-64 | Value set by the acquirer to track the transaction, when present. |
dispute | object |
||
dispute_id | string |
Unique ID we generate to identify the dispute. | |
reason_code | string |
1-11 | Dispute Category and / or condition. |
description | string |
1-100 | Description of dispute category and / or condition. |
date | date |
14 | Date and time of dispute submission. |
amount | string |
1-11 | Transaction amount. |
currency | string |
3 | Transaction currency, an ISO 4217 3-digit code. |
history | object |
||
retrieval_id | string |
0-64 | Unique ID we generate to identify the retrieval of the dispute, when present. |
fraud_id | string |
0-64 | Unique ID we generate to identify the fraud, when present. |
dispute_id | string |
0-64 | Value set by the acquirer to track the dispute, when present. |
{
"id": "C9EDECD6-D0B5-AED5-48E6-EF235ECD5A54",
"timestamp": "20200626110608",
"company_id": "207",
"hash": "282ae91439a1b214046ee8020a641ec1acb969008b68e77ac6e75478331d80f5",
"event": "dispute_new",
"list": [
{
"mid": "1111",
"transaction_id": "38311111",
"merchant_order_id": "1234567_001",
"parent_id": "38311109",
"arn": "74089120120017577925402",
"rrn": "012011111111",
"dispute": {
"dispute_id": "CB_38317766_334344",
"reason_code": "10.4",
"description": "Fraud",
"date": "2020-01-01",
"amount": "19.95",
"currency": "GBP"
},
"history": {
"retrieval_id": "0",
"fraud_id": "0",
"dispute_id": "0"
}
}
]
}
New Fraud Alert
Parameter | Format | Length | Description |
---|---|---|---|
id | string |
36 | The unique reference for the webhook. |
timestamp | date |
14 | Date and time of webhook. |
company_id | int |
1-11 | API Company ID we issue to merchants. |
mid | int |
1-11 | Merchant ID the transaction was processed through. |
hash | string |
64 | Verification hash value. |
event | string |
36 | The event for which the webhook is being triggered. |
list | object |
||
transaction_id | int |
1-10 | Unique ID we generate to identify the transaction. |
merchant_order_id | string |
1-50 | Unique ID you’ll use to identify each transaction, repeated from the request. |
parent_id | string |
1-10 | transaction_id value we generated and returned in the original request. |
arn | string |
0-64 | Value set by the acquirer to track the transaction, when present. |
rrn | string |
0-64 | Value set by the acquirer to track the transaction, when present. |
fraud | object |
||
fraud_id | string |
Unique ID we generate to identify the fraud. | |
date | date |
14 | Date and time of dispute submission. |
amount | string |
1-11 | Transaction amount. |
currency | string |
3 | Transaction currency, an ISO 4217 3-digit code. |
auto_refund | string |
3 | True / False value stating whether or not the transaction has been auto refunded. |
history | object |
||
retrieval_id | string |
0-64 | Unique ID we generate to identify the retrieval of the dispute, when present. |
fraud_id | string |
0-64 | Unique ID we generate to identify the fraud, when present. |
dispute_id | string |
0-64 | Value set by the acquirer to track the dispute, when present. |
{
"id": "fea514d1-272d-4fed-bad3-0f4e19e88918",
"timestamp": "15012018182020",
"company_id": "126",
"hash": "B9AE9775EE4A07079191C0E5B96FDBCEF5C964DD17C8AEE03EF6508F3AA27123",
"event": "fraud_new",
"list": [
{
"mid": "1187",
"transaction_id":"10680696",
"merchant_order_id":"5990700",
"parent_id":"",
"arn":"74567618008180083399312",
"rrn":"720010680696",
"fraud": {
"fraud_id":"FD_10680696_131",
"date":"2020-11-15",
"amount":"130.52",
"currency":"GBP",
"auto_refund":false
},
"history": {
"retrieval_id":"0",
"fraud_id":"0",
"dispute_id":"0"
}
}
]
}
Transaction Outcome Response
Parameter | Format | Length | Description |
---|---|---|---|
id | string |
36 | The unique reference for the webhook. |
timestamp | date |
14 | Date and time of transaction submission. |
company_id | int |
1-11 | API Company ID we issue to merchants. |
hash | string |
64 | Verification hash value. |
event | string |
36 | The event for which the webhook is being triggered. |
response_code | int |
3 | Code describing the transaction result. |
response_message | string |
1-100 | Text describing the transaction response. |
transaction_type | string |
1-12 | Transaction type, repeated from the request message. |
mid_id | int |
1-11 | MID_ID the transaction was processed through. |
transaction_id | int |
1-10 | Unique ID we generate to identify the transaction. Acceptable Characters: 0-9 |
{
"id": "1873E97B-460D-92F8-49F2-650B32C60E27",
"timestamp": "20200626044442",
"company_id": "111",
"hash": "072d418db4646d9d14a88eeac78377a59c23a3bc6e63d24db1e6a01bbaf53a2f",
"event": "transaction_outcome",
"response_code": 1,
"response_message": "Transaction Success",
"transaction_type": "pay_out",
"mid_id": "1111",
"transaction_id": "40621111"
}
Transaction Update Alert
Parameter | Format | Length | Description |
---|---|---|---|
id | string |
36 | The unique reference for the webhook. |
timestamp | date |
14 | Date and time of transaction submission. |
company_id | int |
1-11 | API Company ID we issue to merchants. |
hash | string |
64 | Verification hash value. |
event | string |
36 | The event for which the webhook is being triggered. |
transaction_id | int |
1-10 | Unique ID we generate to identify the transaction. |
transaction_type | string |
1-12 | Transaction type, repeated from the request message. |
response_code | int |
1-3 | Transaction result code. |
rejection_reasons | list |
{
"id": "fea514d1-272d-4fed-bad3-0f4e19e88918",
"timestamp": "15012018180000",
"company_id": "202",
"hash": "A7C96262C21DB9A06FD49E307D694FD95F624569F9B35BB3FFACD880440F9787",
"event": "transaction_update",
"transaction_id": "28090303",
"transaction_type": "pay_out",
"response_code": "652",
"response_message": "Rejected",
"rejection_reasons": [
"beneficiary-sort-code-and-account-number-unknown"
]
}
Funds Received Alert
Parameter | Format | Length | Description |
---|---|---|---|
id | string |
36 | The unique reference for the webhook. |
timestamp | date |
14 | Date and time of transaction submission. |
company_id | int |
1-11 | API Company ID we issue to merchants. |
hash | string |
64 | Verification hash value. |
event | string |
36 | The event for which the webhook is being triggered. |
response_code | int |
1-3 | Transaction result code. |
response_message | string |
1-100 | Text describing the transaction response. |
type | string |
1-100 | Text describing the payment type. |
amount | string |
1-11 | Transaction amount. |
currency | string |
3 | Transaction currency, an ISO 4217 3-digit code. |
ledger_details | object |
||
account_name | string |
1-50 | The name on the account which is displayed within the Hub to differentiate accounts. |
ledger_id | string |
36 | The unique reference for the ledger which will be used for future requests. You should take note of this. |
sort_code | string |
6 | Returned for GBP accounts, the sortcode of the ledger that received the funds. |
account_number | string |
8 | Returned for GBP accounts, the account number of the ledger that received the funds. |
iban | string |
16-34 | The IBAN of the ledger that received the funds. |
bic_swift | string |
8-11 | The BIC of the ledger that received the funds. |
merchant_customer_id | string |
1-50 | Your internal unique customer reference set when creating the ledger. You can use this field to link multiple transactions to a single customer. |
merchant_custom_1 | string | 0-50 | Custom value set by you when creating the ledger the funds were received into. Acceptable Characters: a-z A-Z 0-9 , . - _ |
merchant_custom_2 | string | 0-50 | Custom value set by you when creating the ledger the funds were received into. Acceptable Characters: a-z A-Z 0-9 , . - _ |
merchant_custom_3 | string | 0-50 | Custom value set by you when creating the ledger the funds were received into. Acceptable Characters: a-z A-Z 0-9 , . - _ |
balance | int |
1-11 | The balance on the ledger after recieving these funds. |
sender_details | object |
||
account_name | string |
1-50 | The person’s name on the account that has sent the funds. |
account_number | string |
8 | Returned for GBP payments, the account number of the sender. |
sort_code | string |
6 | Returned for GBP payments, the sort code of the sender. |
iban | string |
16-34 | The IBAN of the sender. |
bic_swift | string |
8-11 | The BIC of the sender. |
reference | string |
1-18 | A description of the payment that will appear on the sender and receiver's bank statements. |
{
"id":"476A672D-21DF-2BC9-8EBB-5EDB7E65D132",
"timestamp":"20200810030716",
"company_id":"202",
"hash":"0195813eaf8dc73e54f8463017df6243a8bd414dc92aef1583c2a1ce99f461c8",
"event":"funds_received",
"response_code":1,
"response message":"Transaction Success",
"type":"faster_payments",
"amount":"130.52",
"currency":"GBP",
"ledger_details":{
"account_name":"Account Name",
"ledger_id":"55938286-283a-4594-b21c-afb1bd52d22c",
"sort_code":"040052",
"account_number":"00459615",
"iban":"GB22PAYR04005200459615",
"bic_swift":"PAYRGB20XXX",
"merchant_customer_id":"a customer id",
"merchant_custom_1":"some info",
"merchant_custom_2":"some info",
"merchant_custom_3":"some info",
"balance":"2091.52"
},
"sender_details":{
"account_name":"Sender Name",
"account_number":"12345678",
"sort_code":"123456",
"iban":"GB29NWBK60161331926819",
"bic":"REVOGB21",
"reference":"Loan 092832"
}
}
Token Update Response
Parameter | Format | Length | Description |
---|---|---|---|
id | string |
36 | The unique reference for the webhook. |
timestamp | date |
14 | Date and time of webhook submission. |
company_id | int |
1-11 | API Company ID we issue to merchants, repeated from the request message. |
hash | string |
64 | Verification hash value. |
event | string |
36 | The event for which the webhook is being triggered. |
mid_id | int |
1-11 | MID_ID the transaction was processed through. |
transaction_id | int |
1-10 | Unique ID we generate to identify the transaction. |
list | object |
||
transaction_id | int |
1-10 | The unique ID generated by Acquired for the account_updater request. Acceptable Characters: 0-9 |
parent_id | int |
1-10 | The transaction_id value returned in the transaction response of the original INIT authorisation request - which represents the token. |
status | int |
2 | Code which identifies the outcome of the update request. Possible status codes: 1 - Updated (Account details successfully updated). 2 - Not Updated (There is no update available for the account provided). 3 - Error (An error occurred with the account updater request). |
bulk_update | int |
1 | Code to determine which scenario this update falls within. 1 - We have initiated the request on cards that are due to expire this month. 0 - Automatic submission due to a transaction declining due to a Lost/Stolen or Expired response. |
update_billing | object |
||
old_cardnumber | int |
12-19 | Contains the masked cardnumber of the existing token. |
old_expdate | string |
6 | Contains the expiry date of the existing token in the format MMYYYY. |
new_cardnumber | int |
12-19 | Contains the masked cardnumber of the new token. |
new_expdate | string |
6 | Contains the expiry date of the existing token in the format MMYYYY. |
card_scheme_response | object |
||
response_code | string |
1 | The code that is returned by Visa when a Visa account number has been queried. Possible status codes: A - Account number changed (expiry date unchanged). C - Closed account advice. E - Expiry date changed. N - Non-participating BIN. P - Participating BIN, no match. Q - Contact cardholder advice. V - Match made, account number and expiry date unchanged. |
reason_identifier | string |
5-10 | The reason identifier code that is returned by Mastercard when a Mastercard account number has been queried. UPDATE - Account number changed (expiry date unchanged). CONTAC - Closed account advice. EXPIRY - Expiry date changed. VALID - Non-participating BIN. UNKNWN - Participating BIN, no match. |
response_indicator | string |
1 | The response indicator code that is returned by Mastercard when a Mastercard account number has been queried. V - Matches the account as reported by the Issuer. P - No match, participating BIN / Issuer. N - No match, non-participating BIN / Issuer. R - Replacement card. B - Brand Flip to MasterCard match. C - Closed account. E - Update expiration date. |
{
"id": "4A956D7E-1775-1CAD-0E9E-F987F357BD0A",
"timestamp": "20200626112124",
"company_id": "111",
"hash": "c5337a8f0c2f1054a717b688d3d005c3d77b8e79c909ced3546aeb4dcb57389a",
"event": "account_updater",
"mid_id": "1111",
"transaction_id": "40621111",
"list": [
{
"transaction_id": "40621111",
"parent_id": "35501111",
"status": "2",
"update_billing": {
"old_cardnumber": "424242######4242",
"old_expdate": "012021",
"new_cardnumber": "424242######4242",
"new_expdate": "012022"
},
"card_scheme_response": {
"response_code": "V",
"reason_identifier": "",
"response_indicator": ""
}
}
]
}
Dashboard Response
Parameter | Format | Length | Description |
---|---|---|---|
id | string |
36 | The unique reference for the webhook. |
timestamp | date |
14 | Date and time of webhook submission. |
company_id | int |
1-11 | API Company ID we issue to merchants, repeated from the request message. |
mid_id | int |
1-11 | MID_ID the transaction was processed through. |
transaction_id | int |
1-10 | Unique ID we generate to identify the transaction. |
hash | string |
64 | Verification hash value. |
event | string |
36 | The event for which the webhook is being triggered. |
response | object |
||
timestamp | date |
14 | Date and time of transaction response. |
response_code | int |
3 | Code describing the transaction result. |
response_message | string |
1-100 | Text describing the transaction response. |
mid | string |
1-11 | MID_ID the transaction was processed through. |
transaction_id | int |
1-10 | Unique ID we generate to identify the transaction. |
transaction_type | string |
1-12 | Transaction type, repeated from the request message. |
merchant_order_id | string |
1-50 | Unique ID you’ll use to identify each transaction, repeated from the request. |
amount | string |
1-11 | Transaction amount. |
currency_code_iso3 | string |
3 | Transaction currency, an ISO 4217 3-digit code. |
authorization_code | string |
0-50 | Authorisation code returned by the issuing bank |
acquirer_reference_number |
|
1-10 | |
avsaddress |
string |
1-2 | AVS check on the first line of the customer’s address, when available. |
avszipcode |
string |
1-2 | AVS check on the customer’s postcode or zipcode, when available. |
cvvresult |
string |
1-2 | Result of CVV2 security check. |
bin | object |
||
issuing_bank | string |
0-50 | Name of the bank issuing the card used for the transaction. |
card_category | string |
0-30 | Category of the card used, for example CREDIT or DEBIT. |
card_level | string |
0-30 | Level of the card used, for example CLASSIC. |
issuing_country | string |
0-50 | Country issuing the card used for the transaction. |
issuing_country_iso2 | string |
2 | Country issuing the card used for the transaction, an ISO2 two-letter code. |
response_hash | string |
64 | Verification hash value. |
{
"id": "03179302-0D12-F716-E821-D84D16D08E4F",
"timestamp": "20200624092426",
"company_id": "357",
"mid_id": "1487",
"transaction_id": "315865",
"hash": "c6a2c758d1c81daaf4672d530c5285896d6c9fe5d03540339e05a1242cdaf1cc",
"event": "dashboard_response",
"response": {
"timestamp": "20200624082426",
"response_code": "1",
"response_message": "Transaction Success",
"mid": "1487",
"transaction_id": "315865",
"transaction_type": "AUTH_CAPTURE",
"merchant_order_id": "1592986996763",
"amount": "11",
"currency_code_iso3": "GBP",
"authorization_code": "TEST12",
"acquirer_reference_number": "",
"avsaddress": "NP",
"avszipcode": "N",
"cvvresult": "N",
"bin": {
"issuing_bank": "",
"card_category": "CREDIT",
"card_level": "",
"issuing_country": "United States",
"issuing_country_iso2": "US"
},
"response_hash": "f860f563dacd7df70249ac011f538173a48b85c50691b55bb6dc85d1805568d9"
}
}