Query API
It is possible to get the outcome of an individual transaction (for recurring payments a group of transactions) by utilising the Acquired.com Query API. There are a number of reasons as to why you may want to use this feature, possible reasons might include:
- You may want to query Acquired's BIN database before processing an authorisation attempt for information on the issuing bank, card category, card level and issuing country.
- You may have received a dispute and wanted to lookup the other associated transactions.
- You might want an alternative means of recieving transaction notifications, that is not via a webhook.
- You might want query a transaction at any point in time.
Endpoints
There are different endpoints for this service:
Request Types
It is possible to perform a query on transactions previously processed through the Acquired.com Platform.
You can query using the transaction_id, merchant_order_id. You are also able to query our BIN database - the choice is yours and depends on what information you are looking for.
Please see the table below for a complete list of the possible values for the status_request_type parameter and what field you should use within the transaction object of the request.
| status_request_type | Description |
|---|---|
| ORDER_ID_ALL | Will return a list of all response messages for transactions using the specified merchant_order_id. |
| ORDER_ID_FIRST | This will return the response message for the first authorisation attempt using the specified merchant_order_id.
|
| ORDER_ID_LAST | This will return the response message for the last authorisation attempt using the specified merchant_order_id.
|
| ORDER_ID_SUCCESS | This will return the response message for the successful authorisation attempt using the specified merchant_order_id. There can only be one successful authorisation per merchant_order_id. |
| TRANSACTION_ID | Will return the response message from a specific transaction_id.
|
| TRANSACTION_ID_CHILDREN_ALL | Passing through the transaction_id returned from the INIT request or the original_transaction_id from a REBILL request will then return a count and the response message for all REBILL attempts.
|
| TRANSACTION_ID_CHILDREN_FIRST | Passing through the transaction_id returned from the INIT request or the original_transaction_id from a REBILL request will then return the response message from the first REBILL attempt processed against your customer’s card.
|
| TRANSACTION_ID_CHILDREN_LAST | Passing through the transaction_id returned from the INIT request or the original_transaction_id from a REBILL request will then return the response message from the last REBILL attempt processed against your customer’s card. |
| TRANSACTION_ID_CHILDREN_SUCCESS | Passing through the transaction_id returned from the INIT request or the original_transaction_id from a REBILL request will then return the response message for all successful REBILL attempts processed against your customer’s card.
|
| BIN | By passing the first 6 or first 8 digits of the card number Acquired.com will return more information about the card (issuing_bank, card_category, card_level, issuing_country and issuing_country_iso2).
|
Request Hash
As with all transaction_type's, you will need to generate a request_hash value to authenticate yourself when processing a request into the Acquired.com platform.
Please see below some sample code that you can use to generate the request_hash value for all different status_request_type parameters.
function sha256hash_status($param,$secret){
if(in_array($param['status_request_type'],array('ORDER_ID_ALL','ORDER_ID_FIRST','ORDER_ID_LAST','ORDER_ID_SUCCESS'))){
$str=$param['timestamp'].$param['status_request_type'].$param['company_id'].$param['merchant_order_id'];
}elseif(in_array($param['status_request_type'],array('TRANSACTION_ID','TRANSACTION_ID_CHILDREN_ALL','TRANSACTION_ID_CHILDREN_FIRST','TRANSACTION_ID_CHILDREN_LAST','TRANSACTION_ID_CHILDREN_SUCCESS'))){
$str=$param['timestamp'].$param['status_request_type'].$param['company_id'].$param['transaction_id'];
}elseif(in_array($param['status_request_type'],array('BIN'))){
$str=$param['timestamp'].$param['status_request_type'].$param['company_id'].$param['bin'];
}
return hash('sha256',$str.$secret);
}public String statusRequestHash(Map param, String secret) throws Exception {
String str = “”;
String status_request_type = param.get(“status_request_type”);
String[] status_request_type_order = {“ORDER_ID_ALL”,“ORDER_ID_FIRST”,“ORDER_ID_LAST”,“ORDER_ID_SUCCESS”};
String[] status_request_type_transaction = {“TRANSACTION_ID”,“TRANSACTION_ID_CHILDREN_ALL”,“TRANSACTION_ID_CHILDREN_FIRST”,“TRANSACTION_ID_CHILDREN_LAST”,“TRANSACTION_ID_CHILDREN_SUCCESS”};
String[] status_request_type_bin = {“BIN”};
if(Arrays.asList(status_request_type_order).contains(status_request_type)) {
str = param.get(“timestamp”) + param.get(“status_request_type”) + param.get(“company_id”) + param.get(“merchant_order_id”);
}else if(Arrays.asList(status_request_type_transaction).contains(“transaction_type”)){
str = param.get(“timestamp”) + param.get(“status_request_type”) + param.get(“company_id”) + param.get(“transaction_id”);
}else if(Arrays.asList(status_request_type_bin).contains(“transaction_type”)){
str = param.get(“timestamp”) + param.get(“status_request_type”) + param.get(“company_id”) + param.get(“bin”);
}
String secstr = str + secret;
return sha256hash(secstr);
}
public String StatusRequestHash(Hashtable param, String secret)
{
string str = “”;
string status_request_type = param[“status_request_type”].ToString();
string[] status_request_type_order = { “ORDER_ID_ALL”,“ORDER_ID_FIRST”,“ORDER_ID_LAST”,“ORDER_ID_SUCCESS”};
string[] status_request_type_transaction = { “TRANSACTION_ID”, “TRANSACTION_ID_CHILDREN_ALL”, “TRANSACTION_ID_CHILDREN_FIRST”, “TRANSACTION_ID_CHILDREN_LAST”, “TRANSACTION_ID_CHILDREN_SUCCESS” };
string[] status_request_type_bin = { “BIN” };
if (Array.IndexOf(status_request_type_order, status_request_type) != -1)
{
str = param[“timestamp”].ToString() + param[“status_request_type”].ToString() + param[“company_id”].ToString() + param[“merchant_order_id”].ToString();
}
else if (Array.IndexOf(status_request_type_transaction, status_request_type) != -1)
{
str = param[“timestamp”].ToString() + param[“status_request_type”].ToString() + param[“company_id”].ToString() + param[“transaction_id”].ToString();
}
else if (Array.IndexOf(status_request_type_bin, status_request_type) != -1)
{
str = param[“timestamp”].ToString() + param[“status_request_type”].ToString() + param[“company_id”].ToString() + param[“bin”].ToString();
}
string secstr = str + secret;
return Sha256hash(secstr);
}Transaction ID
For every transaction processed, we assign a unique transaction_id within each response - this value is our internal reference. Your system can use this value to query our database to get information surrounding one specific transaction of a set of transactions.
There are four possible status_request_type requests that use this value.
| status_request_type | Description |
|---|---|
| TRANSACTION_ID_CHILDREN_ALL | Passing through the transaction_id returned from the INIT request or the original_transaction_id from a REBILL request will then return a count and the response message for all REBILL attempts. |
| TRANSACTION_ID_CHILDREN_FIRST | Passing through the transaction_id returned from the INIT request or the original_transaction_id from a REBILL request will then return the response message from the first REBILL attempt processed against your customer’s card. |
| TRANSACTION_ID_CHILDREN_LAST | Passing through the transaction_id returned from the INIT request or the original_transaction_id from a REBILL request will then return the response message from the last REBILL attempt processed against your customer’s card. |
| TRANSACTION_ID_CHILDREN_SUCCESS | Passing through the transaction_id returned from the INIT request or the original_transaction_id from a REBILL request will then return the response message for all successful REBILL attempts processed against your customer’s card. |
Example
{
"timestamp":"20170612200234",
"company_id":"133",
"company_pass":"password ",
"request_hash":"ffs934d87d3240dw32..... ",
"transaction":{
"status_request_type":"TRANSACTION_ID_CHILDREN_SUCCESS",
"transaction_id":"138210"
}
}{
"timestamp": "20170612200235",
"company_id": "133",
"result_code": "1 ",
"result_message": "Success",
"response_hash": "",
"total_transaction": "2",
"transaction": [
{
"mid": "1045",
"response_code": "1",
"response_message": "Transaction Success ",
"transaction_id": "138756",
"transaction_type": "AUTH_CAPTURE",
"merchant_order_id": "20180306211733",
"amount": "100.00",
"currency_code_iso3": "GBP",
"authorisation_code": "123456",
"acquirer_reference_number": "{}",
"transaction_datetime": "2018-03-06 21:17:51",
"bin": {
"issuing_bank": "JPMORGAN CHASE BANK NA",
"card_category": "CREDIT",
"card_level": "STANDARD",
"issuing_country": "United States",
"issuing_country_iso2": "US"
}
{
"mid": "1045",
"response_code": "1",
"response_message": "Transaction Success ",
"transaction_id": "138396",
"transaction_type": "AUTH_CAPTURE",
"merchant_order_id": "20180215153938-538",
"amount": "175.00",
"currency_code_iso3": "GBP",
"authorisation_code": "654321",
"acquirer_reference_number": "{}",
"transaction_datetime": "2018-02-15 15:39:38",
"bin": {
"issuing_bank": "JPMORGAN CHASE BANK NA",
"card_category": "CREDIT",
"card_level": "STANDARD",
"issuing_country": "United States",
"issuing_country_iso2": "US"
}
}]
}
Please note - In the event of an error we will respond with "result_code":"-1".
Order ID
For every transaction processed, you assign a unique internal reference within the merchant_order_id within each request.merchant_order_id within each request.merchant_order_id within each request. Your system can use this value to query our database to get information surrounding one specific transaction of a set of transactions.
There are four possible status_request_type requests that use this value.
| status_request_type | Description |
|---|---|
| ORDER_ID_ALL | Will return a list of all response messages for transactions using the specified merchant_order_id. |
| ORDER_ID_FIRST | This will return the response message for the first authorisation attempt using the specified merchant_order_id. |
| ORDER_ID_LAST | This will return the response message for the last authorisation attempt using the specified merchant_order_id. |
| ORDER_ID_SUCCESS | This will return the response message for the successful authorisation attempt using the specified merchant_order_id. There can only be one successful authorisation per merchant_order_id. |
{
"timestamp":"20170612200244",
"company_id":"133",
"company_pass":"password ",
"request_hash":"vdrv342487dsclelvs..... ",
"transaction":{
"status_request_type":"ORDER_ID_ALL",
"merchant_order_id":"20180306211733"
}
}{
"timestamp": "20170612200245",
"company_id": "133",
"result_code": "1 ",
"result_message": "Success",
"response_hash": "",
"total_transaction": "1",
"transaction": [
{
"mid": "1045",
"response_code": "1",
"response_message": "Transaction Success ",
"transaction_id": "138756",
"transaction_type": "AUTH_CAPTURE",
"merchant_order_id": "20180306211733",
"amount": "100.00",
"currency_code_iso3": "GBP",
"authorisation_code": "123456",
"acquirer_reference_number": "{}",
"transaction_datetime": "2018-03-06 21:17:51",
"bin": {
"issuing_bank": "JPMORGAN CHASE BANK NA",
"card_category": "CREDIT",
"card_level": "STANDARD",
"issuing_country": "United States",
"issuing_country_iso2": "US"
}
}]
}
Please note - In the event of an error we will respond with "result_code":"-1".
BIN
Would you like to know your customer’s issuing bank, the card category (Debit or Credit), card level (prepaid or corporate for example) and which country was the card issued before processing a transaction?
You can query our BIN database using the first six digits as your customer enters in their payment details which will allow you to determine if you want to accept the card being used or ask the user to use alternative payment details.
{
"timestamp":"20170612200224",
"company_id":"133",
"company_pass":"password ",
"request_hash":"d98wd34349d23034fe..... ",
"transaction":{
"status_request_type":"BIN",
"bin":"40000122"
}
}{
"timestamp":"20170612200225",
"company_id":"133",
"result_code":"1",
"result_message":"Success",
"response_hash":"",
"bin":{
"issuing_bank":"ACQUIRED.COM",
"card_category":"DEBIT",
"card_level":"STANDARD",
"issuing_country":"United Kingdom",
"issuing_country_iso2":"GB"
}
}
Please note - In the event of an error we will respond with "result_code":"-1".