Hub API

Once you have payments flowing, it’s time to understand your transactions better. When you’re integrated via API into the Acquired.com Hub, you can get reports such as Reconciliations, Settlements, Disputes (there is more detailed information in the Reporting Section) and you can complete necessary admin such as submitting Dispute Responses.

Don't forget that before you can access this API, you’ll need an API user created on your account. These details are used to complete the Authorization step explained below. Pick your best person, you can only have one API user.

To confirm if each request into the Hub API is sucessful or not, we return a HTTP response code. For a full list of codes that may be returned, please look to your right.

Within each request, we pass the status parameter within the response. If status is set to 1, your call was successful, if it is set to -1, an error occurred and the call was unsuccessful.

Error Handling - HTTP response codes
  • 200 (Everything worked)
  • 400 (Check your request parameters)
  • 401 (Check your token)
  • 404 (Check the endpoint)
  • 409 (Conflicting request with a different request)
  • 429 (Too many requests at once)
  • 5XX (Errors, contact us!)

Endpoints

Time to play - access the Hub API using these endpoints:

Authorization

The first step to using the Hub API is to generate a token. This token is to be used in the "Authorization" header of all subsequent requests and acts as a security measure. The token value is generated by "logging in" to the Acquired.com Hub.

After you have "logged in", you will receive the token value.

POST /login
Headers
Content-Type: application/json
Accept: application/json

Parameters

Please see to your right a code example of the Authorization request.

Parameter Format Length Description
email
Required
string 1-4 The email address of your API user.
password
Required
string 1-4 The password created for your API user.
{
  "email" : "tech@yourdomain.com",
  "password" : "4]'Hy.$.MC=dQ9Uz"
 }
                        

Response

In response you will get a token value which you’ll use in the Authorization header of all other requests - please see to your right a code example.

Parameter Format Length Description
status int 1-2 The outcome of the request.
Possible values are 1 (Success) or -1 (Failure).
message string 0-100 Handy text describing the status for debugging.
data object
token string 240 A unique token value to be used in the "Authorization" header to access the rest of the Hub API.
last_login_time string 19 The date and time the login details were last used.
login_timeout int 4 The amount of time (in seconds) before this token becomes invalid and you need to request a new one.
{
  "status" : 1,
  "message" : "Success"
  "data" : {
    "token" : "eyJ0eXAiOiJqd3QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiOiI0NjBlYWM1ODFiOTczZjkwOTA5M2Y1NzM2MjE5N2U0OCIsImlkIjoiMzM5IiwidGltZSI6IjIwMTktMDMtMTJUMDc6NTA6MDIrMDAwMCIsInR0bCI6NzIwMCwiaXAiOiIxNzYuMjQuNDYuMTY3In0.gjxFz_q2yR1ttxSsp9xBJOjz6kXDXivPNUJTdE9HA2Q"
    "last_login_time" : "2019-08-22 16:47:18"
    "login_timeout" : 7200
  }
 }
                        
Pro tip: Only one token can be active at a time, and it expires after two hours. After that, you’ll have to ask for a new token. Alternatively, generate a new token for each request - your call.

Reconciliation

Want to avoid downloading your Reconciliation reports via the Hub? Here's how you can get them in JSON format and pull them straight into your system.

GET /reconciliation
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Query Params

Parameter Description
company_id API Company ID we issue to merchants.
If you've only got one or want to query them all, no need to send it.
mid_id API Merchant ID we issue to merchants.
If you've only got one or want to query them all, no need to send it.
start_date
Required
The date you want your search results to start e.g 2019-08-01.
end_date
Required
The date you want your search results to end e.g 2019-08-03.
Pro tip: You can query multiple company_id's or mid_id's with a comma to separate them. You'll see what I mean in the example below.
https://qaapp.acquired.com/reconciliation?company_id=113&mid_id=1045,1046&start_date=2019-08-01&end_date=2019-08-01

Response

Parameter Format Length Description
status int 1-2 The outcome of the request.
Possible values are 1 (Success) or -1 (Failure).
message string 0-100 Handy text describing the status for debugging.
data object The results of the query
{{file_name}} object The name of the file you are getting from the Hub.
Format is {{company_name}}_{{mid_id}}_{{date}}
company_name string 1-50 The name of your company as configured in the Hub.
company_id string 3 API Company ID we issue to merchants.
mid_id string 4 API Merchant ID we issue to merchants.
bank string 1-20 Name of the acquiring bank records relates to.
bank_id string 1-20 Unique ID assigned to you by the acquiring bank.
This value may appears on your bank statements for settlements.
currency_code_iso3 string 3 The associated currency for the transaction_data records.
transaction_data array Individual transaction records that make up the settlement to your bank account.
transaction_id string 1-10 Unique ID we generate to identify the transaction.
date string 10 The date the transaction / record was processed.
arn string 0-24 Value set by the acquirer to track the transaction, when present.
merchant_order_id string 1-50 Unique ID you’ll use to identify each transaction.
merchant_customer_id string 1-50 Unique ID to indentify your customer.
card_type string 0-10 The card scheme the records relates to.
amount string 0-50 The GROSS amount for the transaction.
commission string 0-50 The total fees applied by the acquirer.
net_amount string 0-50 The NET amount for the transaction.
{
  "status": 1,
  "message": "Success",
  "data": {
  "CompanyName_1045_YYYYMMDD": {
    "company_name": "CompanyName",
    "company_id": "113",
    "mid_id": "1045",
    "bank": "Acquired.com",
    "currency_code_iso3": "GBP",
    "transaction_data": [
        {
            "transaction_id": "218127",
            "date": "2019-08-01",
            "arn": "'74089129151921131515371",
            "merchant_order_id": "your_request_reference",
            "merchant_customer_id": "your_customer_id",
            "card_type": "VISA",
            "type": "SALE",
            "amount": "50.000000",
            "commission": "-0.047600",
            "net_amount": "49.952400",
        },
        {
            "transaction_id": "211922",
            "date": "2019-08-01",
            "arn": "'74089129151921131234567",
            "merchant_order_id": "your_request_reference",
            "merchant_customer_id": "your_customer_id",
            "card_type": "VISA",
            "type": "REFUND",
            "amount": "-25.000000",
            "commission": "-1.357000",
            "net_amount": "-26.357",
        },
        ]
    }
  }
 }

Settlement

Don't need all of the transaction level data but want a breakdown of an upcoming or previous settlement to your bank account? Here's how you can get the Settlement reports from the Hub via the API.

GET /settlement
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Query Params

Parameter Description
company_id API Company ID we issue to merchants.
If you've only got one or want to query them all, no need to send it.
mid_id API Merchant ID we issue to merchants.
If you've only got one or want to query them all, no need to send it.
banks Acquiring bank identifier
If you're connected to more than one, we'll let you know what they are.
start_date
Required
The date you want your search results to start e.g 2019-08-01.
end_date
Required
The date you want your search results to end e.g 2019-08-03.
Pro tip: You can query multiple company_id's or mid_id's with a comma to separate them. You'll see what I mean in the example below.
https://qaapp.acquired.com/settlement?company_id=113&mid_id=1045,1046&banks=&start_date=2019-08-01&end_date=2019-08-01

Response

Parameter Format Length Description
status int 1-2 The outcome of the request.
Possible values are 1 (Success) or -1 (Failure).
message string 0-100 Handy text describing the status for debugging.
data object The results of the query
total int 1-10 The total number of lines in the lists array.
lists array Contents of the Settlement Report table from the Hub.
created_date string 10 The date of the settlement report.
open_balance string 0-50 The balance on your account at the start of the day before settlement.
sales_gross_amount string 0-50 The GROSS sales total before an fees are applied by the acquirer.
sales_net_amount string 0-50 The NET sales total after fees are applied by the acquirer.
sales_count string 1-50 Total number of SALE records.
refund_gross_amount string 0-50 The GROSS refunds / credits total before an fees are applied by the acquirer.
refund_net_amount string 0-50 The NET refunds / credits total after fees are applied by the acquirer.
refund_count string 1-50 Total number of REFUND records.
dispute_amount string 0-50 Total amount for DISPUTE records occuring due to dispute activity.
dispute_count string 1-50 Total count of DISPUTE records.
dispute_fee_amount string 0-50 Total amount for DISPUTE FEE records occuring due to dispute activity.
dispute_fee_count string 0-50 Total count of DISPUTE FEE records.
fraud_fee_amount string 0-50 Total amount for FRAUD FEE records occuring due to TC40 / SAFE activity.
fraud_fee_count string 0-50 Total count of FRAUD FEE records.
misc_amount string 0-50 Total amount of misc. fees that may have been applied by the acquirer.
reserve_held_amount string 0-50 Rolling Reserve HELD before settlement is performed (if applicable)
reserve_released_amount string 0-50 Rolling Reserve RELEASED before settlement is performed (if applicable)
total_reserve string 0-50 Sum of reserve_held_amount and reserve_released_amount.
net_settle string 0-50 The amount to be settled (or already settled) to your bank account.
m_currency_code_iso3 string 3 The settlement currency.
currency_symbol_html string 4 HTML currency code.
{
  "status": 1,
  "message": "Success",
  "data": {
    "total": 1,
    "lists": [
        {
        "created_date": "2019-08-01",
        "open_balance": "0.000000",
        "sales_gross_amount": "10000.000000",
        "sales_net_amount": "9800.000000",
        "sales_count": "300",
        "refund_gross_amount": "0.000000",
        "refund_net_amount": "0.000000",
        "refund_count": "0",
        "dispute_amount": "-220.000000",
        "dispute_count": "5",
        "dispute_fee_amount": "-40.000000",
        "dispute_fee_count": "5",
        "fraud_fee_amount": "0.000000",
        "fraud_fee_count": "0",
        "misc_amount": "-20.000000",
        "reserve_held_amount": "0.000000",
        "reserve_released_amount": "0.000000",
        "total_reserve": "0.000000",
        "net_settle": "9520.000000",
        "m_currency_code_iso3": "GBP",
        "currency_symbol_html": "£",
    }
    ]
  }
}

Dispute Report

Looking for a summary of your disputes for a given month including count, amount and percentage vs sales? Query the API to get the Hub Dispute report and pull it directly into your system.

GET /disputes/report
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Query Params

Parameter Description
company_id API Company ID we issue to merchants.
mid_id API Merchant ID we issue to merchants.
card_type VISA / MC
start_date The month you want your search results to start e.g 2019-08.
Required
end_date The month you want your search results to end e.g 2019-08.
Required

Please see below for an example of the query string:

https://qaapp.acquired.com/disputes/report?company_id=113&mid_id=1045&card_type=visa&start_month=2019-08&end_month=2019-08
            

Dispute Details

The Dispute Report provides a summarised view of your disputes that have been raised against your account. To get a list disputes on a transational level, use the Dispute Details query.

A more detailed view provides information that will allow you to identify a customer and perform any actions you deem to be necessary. You may wish to contact the customer and/or submit a Dispute Response.

GET /disputes/details
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Query Params

Parameter Description
company_id API Company ID we issue to merchants.
mid_id API Merchant ID we issue to merchants.
card_type VISA / MC
status noaction, defended, lost, recovered
reason_code Dispute Category (10) and / or condition (10.1)
start_date The day you want your search results to start e.g 2019-08-01.
Required
end_date The day you want your search results to end e.g 2019-08-01.
Required

Please see below for an example of the query string:

https://qaapp.acquired.com/disputes/details&company_id=113&mid_id=1045&card_type=visa&status=lost&reason_code=10&start_date=2019-08-01&end_date=2019-08-01
              

Dispute Response

You can easily submit a dispute response via the API as well as upload supporting documentation. For more information check out here.

You can also see your dispute pack IDs from within Hub. If you’re having trouble with this part, just shoot support@acquired.com an email and they will sort it out. This dispute pack ID notifies us of which Dispute Response Pack saved on your account you wish to submit as part of your Defence Pack.

POST /disputes/response
Headers
Content-Type: multipart/form-data
Accept: application/json
Authorization: token {{token value from here}}

Parameters

Parameter Format Length Description
pack_id int 1-4 Pack ID from the Hub.
transaction_reciept_type int 1 0 = None, 1 = Auto, 2 = Upload
custom_field string 1-1000 Custom text which will replace the custom field text within the defence pack.
transaction_id int 1-10 Unique ID we generate to identify the transaction.
transaction_reciept file Max Size 0.5 MB File location on your side to upload.
proof_of_delivery file Max Size 0.5MB File location on your side to upload.
application_history file Max Size 0.5 MB File location on your side to upload.