Banking API

Endpoints

Time to play - access your API using these endpoints:

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 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 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.
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
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-100 Cardholder’s billing street address.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_street2 string 0-100 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.
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.....",
}

Send Funds

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 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.
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
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",
    "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.
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.