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.

YYou 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 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'].$_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. 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":"400001"
  }
}
{
  "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".