Banking API

The Acquired.com Banking API solution allows you to send funds instantly to a customers bank account when they are applying for a loan. 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.

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 benefciary 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 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 the customers 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 to 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, in the format yyyymmddhhmmss.
company_id
Required
int 3 API Company ID we issue to merchants.
company_pass
Required
string 10-30 API Password we issue to merchants.
request_hash
Required
string 64 Verification hash value - please see here.
transaction
Required
object Click here.
merchant_order_id
Required
string 50 Unique ID you’ll use to identify each transaction.
transaction_type
Required
string 1-20 The type of transaction you are trying to perform.
merchant_customer_id string 0-50 Unique ID to indentify your customer.
merchant_custom_1 string 0-50 Custom merchant data.
merchant_custom_2 string 0-50 Custom merchant data.
merchant_custom_3 string 0-50 Custom merchant data. If utilising dynamic narritive the value should passed in this field.
customer
Required
object Click here.
customer_fname
Required
string Customer’s first name.
customer_lname
Required
string Customer’s last name.
billing object Click here.
billing_street string 0-100 Cardholder’s billing street address.
billing_street2 string 0-100 Cardholder’s billing street address, line 2.
billing_city string 0-100 Cardholder’s billing city.
billing_state string 0-100 Cardholder’s billing state or province.
billing_zipcode string 0-100 Cardholder’s billing ZIP or postal code.
account
Required
object Click here.
sort_code
Required
int 6 Customer's bank sort code.
account_number
Required
int 8 Customer's bank account number.
{
  "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, in the format yyyymmddhhmmss.
response_code int 1-3 Code describing the transaction results.
response_message string 1-100 Message describing the transaction results.
company_id int 1-11 API Company ID we issue to merchants.
mid string 1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
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.
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.
beneficiary_id string 36 The unique ID relating to the newly created beneficiary.
response_hash string 64 Verification hash value.
{
"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",
"beneficiary_id":"5bf53231-9895-4f69-aeee-38177e0c5853",
"response_hash":"835956a9fe56d65416.....",
}

Send Funds

The second step is to push funds to the newly created or already existing benefciary. 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 of the transaction outcome via the transaction_outcome webhook.

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

Parameter Format Length Description
timestamp
Required
date 14 Date and time of transaction submission, in the format yyyymmddhhmmss.
company_id
Required
int 1-11 API Company ID we issue to merchants.
company_pass
Required
string 1-30 API Password we issue to merchants.
request_hash
Required
string 64 Verification hash value.
transaction object
merchant_order_id
Required
string 1-50 Unique ID you’ll use to identify each transaction.
transaction_type
Required
string 1-20 Transaction type is PAY_OUT.
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.
amount
Required
string 1-36 The amount you want to send to the beneficiary.
reference
Required
string 1-18 The reference you want to appear on the customers bank statement for this payment.
{
    "timestamp":"20190101010102",
    "company_id":"113",
    "company_pass":"password",
    "request_hash":"f0a18260b08a0bfacb.....",
    "transaction":"":{
        "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 of the final status via the transaction_outcome webhook.
Parameter Format Length Description
timestamp date 14 Date and time of transaction submission, in the format yyyymmddhhmmss.
response_code int 1-3 Transaction result code.
response_message string 1-100 Transaction result text.
company_id int 1-11 API Company ID we issue to merchants, repeated from the request message.
mid int 1-11 Merchant ID the transaction was processed through.
transaction_id int 1-10 Unique ID we generate to identify the transaction.
response_hash string 64 Verification hash value.
{
    "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 in the format yyyymmddhhmmss.
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.