Webhooks

Webhooks are a system of automated notifications indicating that an event has occurred on your account on the Acquired.com platform. Rather than requiring you to pull information via our API, webhooks push information to your system when important events occur.

Webhooks provide a solution that send JSON notifications when particular events happen i.e. Fraud alerts and customer disputes.

All webhooks are configured by our Support and are sent to a designated URL which is specified by you.

If you choose to avail the solution, you will benefit from increased automation, enhanced efficiency, reduction in costs as well as a reduction in the time spent on back office tasks.

If the immediate webhook notification solution interests you, just contact your account manager and they will help you out.

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.
For the parameters and sample code for these webhooks, please see here.

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.
For the parameters and sample code for these webhooks, please see here.

Transaction Update Webhooks (Banking Services / Faster Payments)

Name Event Use Case
Transaction Update Alert transaction_update Whenever a faster payments/banking transaction is updated using the Acquired.com platform we will send you a notification.
Transaction Outcome Response transaction_outcome Whenever a faster payments/banking transaction is processed 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).
For the parameters and sample code for these webhooks, please see here.

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/Flase 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",
    "mid": "1187",
    "hash": "B9AE9775EE4A07079191C0E5B96FDBCEF5C964DD17C8AEE03EF6508F3AA27123",
    "event": "fraud_new",
    "list": [
        {
            "transaction_id":"10680696",
            "merchant_order_id":"5990700",
            "parent_id":"",
            "arn":"74567618008180083399312",
            "rrn":"720010680696",
            "fraud": {
                "fraud_id":"",
                "date":"2018-01-15",
                "amount":"130.52",
                "currency":"USD",
                "auto_refund":false
            },
            "history": {
                "retrieval_id":"",
                "fraud_id":"",
                "dispute_id":""
            }
        }
    ]
}

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

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

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