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 a "transaction_id", "merchant_order_id" or "bin" depending on what information you are looking for. Please see the table below for a complete list of 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 Using the "transaction_id" returned in the INIT response / "original_transaction_id" in the REBILL request, will return a count and the response messages for all REBILL (success and declined) attempts processed against the customers card.
TRANSACTION_ID_CHILDREN_FIRST Using the "transaction_id" returned in the INIT response / "original_transaction_id" in the REBILL request, will return the response message from the first REBILL attempt processed against the customers card.
TRANSACTION_ID_CHILDREN_LAST Using the "transaction_id" returned in the INIT response / "original_transaction_id" in the REBILL request, will return the response message from the last REBILL attempt processed against the customers card.
TRANSACTION_ID_CHILDREN_SUCCESS Using the "transaction_id" returned in the INIT response / "original_transaction_id" in the REBILL request, will return a count and the response messages for all successful REBILL attempts processed against the customers card.
BIN By passing the first 6 digits of the card number Acquired will return more information about the card (issuing_bank, card_category, card_level, issuing_country and issuing_country_iso2).

Request Hash

As with all other transaction types you'll need a "request_hash" value in order to authenticate the request with the Acquired platform. Below is a code example for how to calculate this value for all 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

Within every transaction response, we'll send back a transaction_id value which is our unique reference. Your system can use this value to query us to get information about a specific or set of transactions. There are 4 possible status_request_type requests using this value:

status_request_type Description
TRANSACTION_ID_CHILDREN_ALL Using the "transaction_id" returned in the INIT response / "original_transaction_id" in the REBILL request, will return a count and the response messages for all REBILL (success and declined) attempts processed against the customers card.
TRANSACTION_ID_CHILDREN_FIRST Using the "transaction_id" returned in the INIT response / "original_transaction_id" in the REBILL request, will return the response message from the first REBILL attempt processed against the customers card.
TRANSACTION_ID_CHILDREN_LAST Using the "transaction_id" returned in the INIT response / "original_transaction_id" in the REBILL request, will return the response message from the last REBILL attempt processed against the customers card.
TRANSACTION_ID_CHILDREN_SUCCESS Using the "transaction_id" returned in the INIT response / "original_transaction_id" in the REBILL request, will return a count and the response messages for all successful REBILL attempts processed against the customers 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

You can query a transaction, or group of transactions, using the merchant_order_id value you passed through in the request message. There are 4 possible status_request_type requests using 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

Want to know the associated issuing bank, category (debit / credit), level and issuing country associated with a card before you process a transaction - query the BIN information using the first six digits as the user enters them to know if you want to accept it or ask the user for another card.

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