Please note that we are no longer onboarding new customers to this version of our API. Please visit our new documentation site https://docs.acquired.com
Get a test account Login

Banking API

The Acquired.com Banking API solution allows you to send funds instantly to a customers bank account. We offer a real-time service via API to let you know the outcome of sending funds immediately.

If you wish to avail the solution, please contact support@acquired.com to enable this feature on your account.

Endpoints

Time to play - access your API using these endpoints:

In addition to this you will also be required to provide your IP address(s) to support@acquired.com in order to use this API in the production environment.

Request Hash

The request_hash field is required for each transaction in order to verify that the contents are received securely.

Create the request_hash by concatenating request fields with a hash_code provided by Acquired.com and taking the SHA256 hash of that string.

For BENEFICIARY_NEW and PAY_OUT request types concatenate the values from the table below:

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp date 14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
transaction_type string 1-20 The transaction type being performed.
Acceptable Characters: a-z A-Z _
company_id int 1-11 API ID issued by Acquired.com to the merchant.
Acceptable Characters: 0-9
merchant_order_id string 1-50 The unique ID used by the merchant to identify the transaction.
Acceptable Characters: a-z A-Z 0-9 _ -
request_hash string 1-30 Hash value assigned by Acquired.com to merchant.
Acceptable Characters: a-z A-Z 0-9 
function secret_hash($param,$secret){
if(in_array($param['transaction_type'],array('AUTH_ONLY','AUTH_CAPTURE','CREDIT','BENEFICIARY_NEW','PAY_OUT'))){
    $str=$param['timestamp'].$param['transaction_type'].$param['company_id'].
    $param['merchant_order_id'];
    }elseif(
        in_array($param['transaction_type'],array('CAPTURE','VOID',
        'REFUND','SUBSCRIPTION_MANAGE'))){
        $str=$param['timestamp'].$param['transaction_type'].$param['company_id'].
        $param['original_transaction_id'];
    }
    return hash('sha256',$str.$secret);
}

Response Hash

Included in Acquired.com’s response to all merchants’ transaction requests, is a parameter called a response_hash. The response_hash allows merchants to confirm that the transaction response came from Acquired.com.

For all transaction types the response_hash parameter is calulated in the same way, a 64-character SHA256 hash of the following response values concatenated:

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp date 14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
transaction_type string 1-20 The transaction type being performed.
Acceptable Characters: a-z A-Z _
company_id int 1-11 API ID issued by Acquired.com to the merchant.
Acceptable Characters: 0-9
transaction_id int 1-10 The unique ID generated by Acquired.com for the transaction.
Acceptable Characters: 0-9
response_code int 1-3 The code describing the results of the transaction.
Acceptable Characters: 0-9
hash_code string 1-30 Hash value assigned by Acquired.com to merchant.
Acceptable Characters: a-z A-Z 0-9

How it Works

The solution is based on two seperate requests to allow you to set up a customer and send funds straight away. The first request is known as BENEFICIARY_NEW and the second is called PAY_OUT.

These request types are populated in each request within the transaction_type parameter.

  • BENEFICIARY_NEW creates a brand new beneficiary you would like to send funds to. This verifies the details provided are correct i.e correct sort code/account number, address etc.
  • PAY_OUT This is used to push funds to a newly created or already existing beneficiary.

Please see below for how to include both BENEFICIARY_NEW and PAY_OUT for your application. We provide code examples and the required parameters to be passed through in every request.

Creating a New Beneficiary

As mentioned previously, the first step is creating the beneficiary you want to send funds to.

To do so, you must provide us with the customer's details (name, address and bank account information). Within each response, we'll create a transaction_id which is to be used for any subsequent payments to this customer.

Info - Whilst it is optional, we recommend that you send the customers address details within each BENEFICIARY_NEW request.

Here is a list of the mandatory and required fields that may accompany a request. Please also see some handy sample code to your right hand side.

Parameter Format Length Description
timestamp
Required		 date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id
Required		 int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
company_pass
Required		 string 10-30 API Password we issue to merchants.
Acceptable Characters: 0-9 a-z A-z
company_mid_id
Required		 int 1-11 Targets a specific company_mid_id (ledger) within your company to create the beneficiary against.
Acceptable Characters: 0-9
request_hash
Required		 string 64 Verification hash value - please see here.
Acceptable Characters: a-z A-Z 0-9
transaction
Required		 object Click here.
merchant_order_id
Required		 string 50 Unique ID you’ll use to identify each transaction.
Acceptable Characters: a-z A-Z 0-9 _ -
transaction_type
Required		 string 1-20 The type of transaction you are trying to perform.
Acceptable Characters: a-z A-Z _
merchant_customer_id string 0-50 Your internal unique customer reference. You can use this field to link multiple transactions to a single customer.
Acceptable Characters: a-z A-Z 0-9 , . - _
merchant_custom_1 string 0-50 You can send additional data relating to the customer or another internal reference - with more data, your internal teams will be able to identify the customer’s transactions.
Acceptable Characters: a-z A-Z 0-9 , . - _
merchant_custom_2 string 0-50 You can send additional data relating to the customer or another internal reference - with more data, your internal teams will be able to identify the customer’s transactions.
Acceptable Characters: a-z A-Z 0-9 , . - _
merchant_custom_3 string 0-50 You can send additional data relating to the customer or another internal reference - with more data, your internal teams will be able to identify the customer’s transactions. If you are using our dynamic descriptor feature, you will not be able to use the merchant_custom_3 field as the dynamic descriptor value should be passed in this field.
Acceptable Characters: a-z A-Z 0-9 , . - _
customer
Required		 object Click here.
customer_fname
Required		 string Customer’s first name.
Acceptable Characters: a-z A-Z , . - _
customer_lname
Required		 string Customer’s last name.
Acceptable Characters: a-z A-Z , . - _
billing object Click here.
billing_street string 0-50 Cardholder’s billing street address.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_street2 string 0-50 Cardholder’s billing street address, line 2.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_city string 0-100 Cardholder’s billing city.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_state string 0-100 Cardholder’s billing state or province.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_zipcode string 0-100 Cardholder’s billing ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
account
Required		 object Click here.
sort_code
Required		 int 6 Customer's bank sort code.
Acceptable Characters: 0-9
account_number
Required		 int 8 Customer's bank account number.
Acceptable Characters: 0-9		 
{
  "timestamp":"20190101010101",
  "company_id":"113",
  "company_pass":"password",
  "company_mid_id":"0146",
  "request_hash" : "f0a18260b08a0bfacb.....",
"transaction":{ 
    "merchant_order_id":"a9f0ce93-6f0d-4a15-a18b-45f1304b4bc0",
    "transaction_type":"BENEFICIARY_NEW",
    "merchant_customer_id":"11223344",
    "merchant_custom_1":"C1",
    "merchant_custom_2":"C2",
    "merchant_custom_3":"C3"
    
},
"customer" : { 
    "customer_fname":"Edward",
    "customer_lname":"Johnson"
    
},
"billing" : { 
    "cardholder_name":"Mr. Edward Johnson",
    "billing_street":"44 Baker Street",
    "billing_street2":"Flat 1",
    "billing_city":"London",
    "billing_state":"",
    "billing_zipcode":"W1U 7AL"
    
},
"account" : { 
    "sort_code":"123456",
    "account_number":"12345678"
    
}
}

After processing the transaction request, we’ll return a response to confirm the outcome. Again, some handy sample code alongside.

Parameter Format Length Description
timestamp date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
response_code int 1-3 Code describing the transaction results.
Acceptable Characters: 0-9
response_message string 1-100 Message describing the transaction results.
Acceptable Characters: 0-9 a-z A-z _ - ()[]{};~!@#$%^*,./\?:”’ +=`
company_id int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
mid string 1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
Acceptable Characters: 0-9
transaction_id int 1-10 Unique ID we assign to each transaction that is processed. This value is to be used in the subsequent PAY_OUT request.
Acceptable Characters: 0-9
transaction_type string 1-12 Transaction type, repeated from the request message.
Acceptable Characters: a-z A-Z _
merchant_order_id string 1-50 Unique ID you’ll use to identify each transaction, repeated from the request.
Acceptable Characters: a-z A-Z 0-9 _ -
response_hash string 64 Verification hash value.
Acceptable Characters: a-z A-Z 0-9		 
{
"timestamp":"20190101010101",
"response_code":"1",
"response_message":"Transaction Success",
"company_id":"113",
"mid":"1046",
"transaction_id":"5436756",
"transaction_type":"BENEFICIARY_NEW ",
"merchant_order_id":"a9f0ce93-6f0d-4a15-a18b-45f1304b4bc0",
"response_hash":"835956a9fe56d65416....."
}

Pay Out

The second step is to push funds to the newly created or already existing beneficiary. To complete this, you can submit a PAY_OUT request. The request will include the amount and the reference you want to appear on your customer's bank statement.

Once the PAY_OUT is processed, the transaction will initially be assigned a Pending status. You will then be updated on the transaction outcome via the transaction_outcome webhook.

Below is a list of mandatory and additional parameters that may accompany the PAY_OUT request, and some handy sample code.

Parameter Format Length Description
timestamp
Required		 date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id
Required		 int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
company_pass
Required		 string 1-30 API Password we issue to merchants.
Acceptable Characters: 0-9 a-z A-z
company_mid_id
Required		 int 1-11 Targets a specific company_mid_id (ledger) within your company you want to process your PAY_OUT against.
Acceptable Characters: 0-9
request_hash
Required		 string 64 Verification hash value.
Acceptable Characters: a-z A-Z 0-9
transaction object
merchant_order_id
Required		 string 1-50 Unique ID you’ll use to identify each transaction.
Acceptable Characters: a-z A-Z 0-9 _ -
transaction_type
Required		 string 1-20 Transaction type is PAY_OUT.
Acceptable Characters: a-z A-Z _
original_transaction_id
Required		 string 1-10 Transaction_id value we generated in the BENEFICIARY_NEW response for the person you are looking to send funds to.
Acceptable Characters: 0-9
amount
Required		 string 1-36 The amount you want to send to the beneficiary.
Acceptable Characters: 0-9 in the format DDDDDD.CC
reference
Required		 string 1-18 The reference you want to appear on the customers bank statement for this payment.
Acceptable Characters: a-z A-Z 0-9 _ - 
{
    "timestamp": "20190101010102",
    "company_id": "113",
    "company_pass": "password",
    "company_mid_id": "0146",
    "request_hash": "f0a18260b08a0bfacb.....",
    "transaction": {
        "merchant_order_id": "12345678",
        "transaction_type": "PAY_OUT",
        "original_transaction_id": "5436756",
        "amount": "10.99",
        "reference": "your reference"
    }
}

Again, after processing the transaction request we’ll return a response to confirm the outcome. Take a look at the handy sample code alongside.

Info - if everything has gone right up until this point, you'll get back an 11 response_code (Pending). We'll update you on the final status via the transaction_outcome webhook.
Parameter Format Length Description
timestamp date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
response_code int 1-3 Transaction result code.
Acceptable Characters: 0-9
response_message string 1-100 Transaction result text.
Acceptable Characters: 0-9 a-z A-z _ - ()[]{};~!@#$%^*,./\?:”’ +=`
company_id int 1-11 API Company ID we issue to merchants, repeated from the request message.
Acceptable Characters: 0-9
mid int 1-11 Merchant ID the transaction was processed through.
Acceptable Characters: 0-9
transaction_id int 1-10 Unique ID we generate to identify the transaction.
Acceptable Characters: 0-9
response_hash string 64 Verification hash value.
Acceptable Characters: a-z A-Z 0-9		 
{
    "timestamp":"20190101010102",
    "response_code":"11",
    "response_message":"Pending",
    "company_id":"113",
    "mid":"1046",
    "transaction_id":"6784323",
    "response_hash":"835956a9fe56d65416....."
}

Transaction Outcome

We will update on the outcome of each Faster Payment attempt via a webhook notification. Since we initially respond with Pending within the PAY_OUT response and will subsequently update the status.

You will need to tell support@acquired.com which URL you would like us to send the webhook notification to. We must receive a HTTP 200 response code from this URL.

There are four possible outcomes we may send within the webhook notification:

  • Success - The funds have left your account and are on the way to the customer.
  • Quarentined - This attempt requires a further review. Please contact support@acquired.com.
  • Declined - This attempt has been declined.
  • Error - An error has occurred with your request, please contact support@acquired.com.

Webhook Parameters

Below is a list of parameters that we will send for each transaction_outcome notification alongside some handy sample code.

Parameter Format Length Description
id string 36 The unique ID we assign to every webhook notification.
timestamp date 14 The date and time the webhook was sent.
company_id int 1-11 API Company ID we issue to merchants.
hash string 64 Verification hash value.
event string 64 The type of webhook being sent (transaction_outcome).
response_code int 1-3 The code that describes the transaction outcome.
response_message string 1-100 The text that describes the transaction outcome.
transaction_type string 1-20 Transaction type is PAY_OUT.
transaction_id int 1-10 The transaction_id we return within the webhook will match the one returned in the response to the PAY_OUT request. 
{
    "id":"3128C1A3-66D6-8290-CC92-B4E41F9D3F4C",
    "timestamp":"20190101010103",
    "company_id":"113",
    "hash":"835956a9fe56d65416.....",
    "event":"transaction_outcome",
    "response_code":"1",
    "response_message":"Transaction Success",
    "transaction_type":"PAY_OUT",
    "transaction_id":"6784323"
}

Response Codes

In addition to the complete list of response codes, here are the relevant Banking API response codes for Faster Payments.

Code Message Description
1 Transaction Success Request was successfully processed.
11 Pending PAY_OUT request was successfully processed, please wait for the transaction_outcome webhook notification for the final status.
13 Quarentined The transaction has been marked for review, please contact support@acquired.com if a success / declined outcome is not received shortly.
101 Declined Transaction has declined, please check the details provided and try again.
601 Error: Invalid sort_code sort_code field contains invalid characters, please check the details provided and try again.
602 Error: Invalid account_number account_number field contains invalid characters, please check the details provided and try again.
603 Error:Invalid reference reference field contains invalid characters, please check the details provided and try again.
605 Error:Invalid Account The account_number / sort_code provided by the BENEFICIARY_NEW request cannot be found, please ask the customer to check their details and try again.
650 Declined:Account Balance PAY_OUT request has declined due to your account balance being too low, please transfer funds to your account and try again.
651 Declined: Following Review The payment has been rejected following a review, please contact support@acquired.com.
909 Error: Bank response Format Error Please contact support@acquired.com if you receive this response code and include the transaction_id value.
Please note: if you're using both Recurring Payments as well as our Banking API, you should consider grouping your payments using our Transaction Link feature. This is to Link the card re-payment to the initial funds that were sent, this information can then be pulled into your dispute packs to strengthen your defence and increase your chances of winning your case.