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.

Note It is possible to submit a query instead of receiving a webhook using the Hub API, see here

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.

All webhooks are configured by our Support team and are sent to a designated URL which is specified by you. Each URL is required to begin with https:// and you can set a different target URL for each webhook notification.

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.

If you would like to view more information about the webhooks we are sending you, or would like to resend a webhook, you can do so by navigating to the Requests Page. Here we have added a webhooks tab where you can view the logs of all the webhooks we have sent.

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.

Pro tip: It’s time to get your company_hashcode (if you haven't already). Send the support@acquired.com team a note, they’ll allocate one straight away.

Webhook Hash

To calculate the hash value, please follow the steps listed below:

  1. Sort the transaction parameters - excluding your company hash - alphabetically and then concatenate (don’t you just love this word?). Here are some examples:

    id . timestamp . company_id . event
      //C9EDECD6-D0B5-AED5-48E6-EF235ECD5A5420200626110608207dispute_new
            
  2. SHA256 encrypt the resulting string:

    4107fb43722f1aeaaa4cb6330306b394ce84f97f5fd3e00d4aaedab9a5084d51
  3. Then, append your company_hashcode to the string generated in step two and SHA256 encrypt again:

    4107fb43722f1aeaaa4cb6330306b394ce84f97f5fd3e00d4aaedab9a5084d51company_hashcode
    ca8358ac0c846b50b5e998658d17f8518aca1baea67f1c3d31e5a5d9c5d2220d

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 string0-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 string0-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 string0-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"
  }
}