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 in 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:

QA: https://qaapp.acquired.com
PROD: https://app.acquired.com

Authorization

The app_id and app_key values for this request can be found in the Acquired.com Hub. If you are unable to find them please contact your company admin or support@acquired.com.

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
app_id Required	`string`	1-50	The ID of your API user, you can get it from the Hub. Acceptable Characters: a-zA-Z0-9
app_key Required	`string`	1-50	The secret app key of your API user, you can get it from the Hub. Acceptable Characters: a-zA-Z0-9
api Required	`boolean`		Should be set to true.

JSON

{
  "app_id" : "25416783",
  "app_key" : "331f1416d8e4999a75ec677cd9a6239sd",
  "api" : true
}

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

JSON

{
    "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	Format	Length	Description
company_id	`int`	1-11	API Company ID we issue to merchants. If you've only got one or want to query them all, no need to send it. Acceptable Characters: 0-9
mid_id	`int`	1-11	API Merchant ID we issue to merchants. If you've only got one or want to query them all, no need to send it. Acceptable Characters: 0-9
start_date Required	`string`	0-10	The date you want your search results to start, in the format: YYYY-MM-DD. Acceptable Characters: 0-9 -
end_date Required	`string`	0-10	The date you want your search results to end, in the format: YYYY-MM-DD. Acceptable Characters: 0-9 -

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.
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	`int`	1-11	API Company ID we issue to merchants.
mid_id	`int`	1-11	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	Your internal unique customer reference. You can use this field to link multiple transactions to a single 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.

JSON

{
    "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	Format	Length	Description
company_id	`int`	1-11	API Company ID we issue to merchants. If you've only got one or want to query them all, no need to send it. Acceptable Characters: 0-9
mid_id	`int`	1-11	API Merchant ID we issue to merchants. If you've only got one or want to query them all, no need to send it. Acceptable Characters: 0-9
bank	`string`	1-20	Acquiring bank identifier. If you're connected to more than one, we'll let you know what they are.
start_date Required	`string`	0-10	The date you want your search results to start, in the format: YYYY-MM-DD. Acceptable Characters: 0-9 -
end_date Required	`string`	0-10	The date you want your search results to end, in the format: YYYY-MM-DD. Acceptable Characters: 0-9 -

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

JSON

{
    "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	Format	Length	Description
company_id	`int`	1-11	API Company ID we issue to merchants. Acceptable Characters: 0-9
mid_id	`int`	1-11	API Merchant ID we issue to merchants. Acceptable Characters: 0-9
card_type	`string`	0-10	Possible Values are: VISA / MC.
start_date	`string`	0-10	The month you want your search results to start, in the format: YYYY-MM. Acceptable Characters: 0-9 - Required
end_date	`string`	0-10	The month you want your search results to end, in the format: YYYY-MM. Acceptable Characters: 0-9 - 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	Format	Length	Description
company_id	`int`	1-11	API Company ID we issue to merchants. Acceptable Characters: 0-9
mid_id	`int`	1-11	API Merchant ID we issue to merchants. Acceptable Characters: 0-9
card_type	`string`	0-10	Possible Values are: VISA / MC. Acceptable Characters: a-z A-Z
status	`string`	1-50	Possible values are: noaction, defended, lost. Acceptable Characters: a-z A-Z
reason_code	`string`	1-11	Dispute Category (10) and / or condition (10.1). Acceptable Characters: 0-9 .
start_date	`string`	0-10	The day you want your search results to start, in the format: YYYY-MM-DD. Required Acceptable Characters: 0-9 -
end_date	`string`	0-10	The day you want your search results to end, in the format: YYYY-MM-DD. Required Acceptable Characters: 0-9 -

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. Acceptable Characters: 0-9
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. Acceptable Characters: 0-9
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.

Webhooks

Want to query our system for Banking and Fraud updates without having the notifications pushed to you from our system? Query the API to retrieve customer updates and pull them directly into your system.

GET /webhooks

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

Query Params

Parameter	Format	Length	Description
company_id	`int`	1-11	API Company ID we issue to merchants. If you've only got one or want to query them all, no need to send it. Acceptable Characters: 0-9
mid_id	`int`	1-11	API Merchant ID we issue to merchants. If you've only got one or want to query them all, no need to send it. Acceptable Characters: 0-9
start_date	`datetime`	0-19	The date you want your search results to start, in the format: YYYY-MM-DD HH:MM:SS Acceptable Characters: 0-9 -
end_date	`datetime`	0-19	The date you want your search results to end, in the format: YYYY-MM-DD HH:MM:SS Acceptable Characters: 0-9 -
transaction_id	`string`	1-10	Unique ID we generate to identify the transaction.
event	`string`	8-20	The type of webhook records you want to get back in the response Acceptable Values: retrival_new, fraud_new, dispute_new, dispute_recovered, dashboard_response, transaction_outcome, account_updater, transaction_update, funds_received

Please see below for an example of the query string:

https://qaapp.acquired.com/webhooks?company_id=113&mid_id=1045&event=transaction_outcome

Response

Parameter	Format	Length	Description
status	`int`	1-2	The outcome of the request.
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`		Please see here

JSON

{
  "status": 1,
  "message": "Success",
  "data": {
    "total": 1,
    "lists": [
        {
        "id": "80FE1D63-B791-B6E8-4916-F3D2C2984856",
        "timestamp": "20201023062731",
        "company_id": "113",
        "hash": "55d08d145e53a7f98795aee0f37826d6812c4a27b7ebc6db4c0c699063d4a0cd",
        "event": "transaction_outcome",
        "response_code": "1",
        "response_message": "Transaction Success",
        "transaction_type": "pay_out",
        "mid_id": "1045",
        "transaction_id": "329120"
    }
    ]
  }
}

Note It is also possible to query a specific webhook, see below for details of how to achieve this.

GET /webhooks/{{webhook_id}}

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

Parameters

Parameter	Format	Length	Description
webhook_id	`string`	0-36	A unique reference for a webhook

Response

Parameter	Format	Length	Description
status	`int`	1-2	The outcome of the request.
message	`string`	0-100	Handy text describing the status for debugging.
data	`object`		The results of the query, please see here for reference.

JSON

{
    "status": 1,
    "message": "Success",
    "data": {
        "id": "80FE1D63-B791-B6E8-4916-F3D2C2984856",
        "timestamp": "20201023062731",
        "company_id": "113",
        "hash": "55d08d145e53a7f98795aee0f37826d6812c4a27b7ebc6db4c0c699063d4a0cd",
        "event": "transaction_outcome",
        "response_code": "1",
        "response_message": "Transaction Success",
        "mid_id": "1045",
        "transaction_id": "329120"
    }
}