API Reference

The Acquired API integration method offers merchants with enhanced security capabilities the ability to integrate directly into our low latency platform.

Authentication

Endpoints:

QA: "https://qaapi.acquired.com/api.php"

PROD: "https://gateway.acquired.com/api.php"

To authenticate with the Acquired API in either the Production or QA environment you will need:

company_id: API Company ID issued by Acquired to the merchant.

company_pass: API password required for all requests.

hash_code: used to generate both request_hash and response_hash values.

In addition to this you will also be required to provide your IP address(s) to [email protected] in order to use this API in the production environment.

Request Hash

//This is a PHP example for an AUTH_ONLY request type:

hash('sha256', $timestamp . $transaction_type . $company_id .
$merchant_order_id . $hash_code);

hash('sha256', "20170612200234". "AUTH_ONLY" . "133" .
"20170612200234" . "hash_code");

The request_hash field is required for each transaction in order to verify that the contents are received securely.

Create the request_hash by concatenating request fields with a hash_code provided by Acquired and taking the SHA256 hash of that string

For AUTH_ONLY, AUTH_CAPTURE and CREDIT request types concatenate the values from the table below:

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
string 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
transaction_type
string a-z A-Z _
1-20 The transaction type being performed.
company_id
int / string 0-9
1-11 API ID issued by Acquired to the merchant.
merchant_order_id
string a-z A-Z 0-9 - _
1-50 The unique ID used by the merchant to identify the transaction.
hash_code
string a-z A-Z 0-9 _
1-30 Hash value assigned by Acquired to merchant.

For CAPTURE, VOID and REFUND request types concatenate the values from the table below:


PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
string 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
transaction_type
string a-z A-Z _
1-20 The transaction type being performed.
company_id
int / string 0-9
1-11 API ID issued by Acquired to the merchant.
original_transaction_id
int / string 0-9
1-10 Transaction_id value generated by Acquired and returned in the original request.
hash_code
string a-z A-Z 0-9 _
1-30 Hash value assigned by Acquired to merchant.

Response Hash

Included in Acquired’s response to all merchants’ transaction requests, is a parameter called a response_hash. The response_hash allows merchants to confirm that the transaction response came from Acquired.

For all transaction types the response_hash parameter is calulated in the same way, a 64-character SHA256 hash of the following response values concatenated:


PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
string 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
transaction_type
string a-z A-Z _
1-20 The transaction type being performed.
company_id
int / string 0-9
1-11 API ID issued by Acquired to the merchant.
transaction_id
int / string 0-9
1-10 The unique ID generated by Acquired for the transaction.
response_code
string 0-9
1-3 The code describing the results of the transaction.
hash_code
string a-z A-Z 0-9 _
1-30 Hash value assigned by Acquired to merchant.

You will find sample code for how to calculate the request_hash value below:


function secret_hash($param,$secret){
if(in_array($param['transaction_type'],array('AUTH_ONLY','AUTH_CAPTURE','CREDIT'))){ $str=$param['timestamp'].$param['transaction_type'].$param['company_id']. $param['merchant_order_id']; }elseif( in_array($param['transaction_type'],array('CAPTURE','VOID', 'REFUND','SUBSCRIPTION_MANAGE'))){
$str=$param['timestamp'].$param['transaction_type'].$param['company_id']. $param['original_transaction_id'];
} return hash('sha256',$str.$secret);
}

AUTHORISATION

There are two request_type parameters for authorisation AUTH_ONLY, which will only authorise the transaction and require an additional CAPTURE. An AUTH_CAPTURE which performs both actions in one step.

{
" timestamp " : " 20170612200234 ",
" company_id " : " 133 ",
" company_pass " : " password ",
" company_mid_id " : " ",
" vt " : " ",
" useragent " : " ",
" request_hash " : " f0a18260b08a0bfacb..... ",
" transaction " : {
" merchant_order_id " : " 20170612200234 ",
" transaction_type " : " AUTH_ONLY ",
" subscription_type " : " ",
" amount " : "100 ",
" currency_code_iso3 " : " GBP ",
" merchant_customer_id " : " 100000087 ",
" merchant_custom_1 " : " C1 ",
" merchant_custom_2 " : " C2 ",
" merchant_custom_3 " : " C3 "
} ,
" customer " : {
" customer_title " : " Mr ",
" customer_fname " : " Edward ",
" customer_mname " : " N ",
" customer_lname " : " Johnson ",
" customer_gender " : " M ",
" customer_dob " : " 1988-12-14 ",
" customer_ipaddress " : " 2a02:d7f:c401:5f00:7538:fbfc:4a41:e3d2 ",
" customer_company " : " Acquired Payments "
} ,
" billing " : {
" cardholder_name " : " MR E N JOHNSON ",
" cardnumber " : " 4242424242424242 ",
" card_type " : " VISA ",
" cardcvv " : " 123 ",
" cardexp " : " 022020 ",
" billing_street " : " 44 Baker Street ",
" billing_street2 " : " ",
" billing_city " : " London ",
" billing_state " : " ",
" billing_zipcode " : " W1U 7AL ",
" billing_country_code_iso2 " : " GB ",
" billing_phone " : " +44 (0) 7763270200 ",
" billing_email " : " [email protected] "
}
}
< request >
< timestamp > 20170612200234 </ timestamp >
< company_id > 133 </ company_id >
< company_pass > secret </ company_pass >
< company_mid_id > </ company_pass >
< vt > </ vt >
< useragent > </ useragent >
< request_hash > f0a18260b08a0bfacb.....  </ request_hash >
< transaction >
< merchant_order_id > 20170612200234 </ merchant_order_id >
< transaction_type > AUTH_ONLY </ transaction_type >
< subscription_type > </ subscription_type >
< amount > 100 </ amount >
< currency_code_iso3 > GBP </ currency_code_iso3 >
< merchant_customer_id > 100000087 </ merchant_customer_id >
< merchant_custom_1 > C1 </ merchant_custom_1 >
< merchant_custom_2 > C2 </ merchant_custom_2 >
< merchant_custom_3 > C3 </ merchant_custom_3 >
</ transaction >
< customer >
< customer_title > Mr </ customer_title >
< customer_fname > Edward </ customer_fname >
< customer_mname > N </ customer_mname >
< customer_lname > Johnson </ customer_lname >
< customer_gender > M </ customer_gender >
< customer_dob > 1988-12-14 </ customer_dob >
< customer_ipaddress > 2a02:d7f:c401:5f00:7538:fbfc:4a41:e3d2 </ customer_ipaddress >
< customer_company > Acquired Payments </ customer_company >
</ customer >
< billing >
< cardholder_name > MR E N JOHNSON </ cardholder_name >
< cardnumber > 4242424242424242 </ cardnumber >
< card_type > VISA </ card_type >
< cardcvv > 123 </ cardcvv >
< cardexp > 022020 </ cardexp >
< billing_street > 44 Baker Street </ billing_street >
< billing_street2 > </ billing_street2 >
< billing_city > London </ billing_city >
< billing_state > </ billing_state >
< billing_zipcode > W1U 7AL </ billing_zipcode >
< billing_country_code_iso2 > GB </ billing_country_code_iso2 >
< billing_phone > +44 (0) 7763270200 </ billing_phone >
< billing_email > [email protected] </ billing_email >
</ billing >
</ request >

Request Parameters

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
Required
string 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
company_id
Required
int 0-9
1-11 API ID issued by Acquired to the merchant.
company_pass
Required
string 0-9 a-z A-z _ -
1-30 API Password issued by Acquired to the merchant.
company_mid_id
int 0-9
1-11 Allows you to target a specific mid_id within the company struture.
useragent
string 0-9 a-z A-z _ - ()[]{};[email protected]#$%^*,./\?:”’ +=
1-1000 useragent Data
vt
boolean 0 / 1
1 Additional parameter to flag a transaction as MOTO. Should be included if process payments over the phone or via an IVR solution.
request_hash
Required
string a-z A-Z 0-9
64 A verification hash value.
transaction object
merchant_order_id
Required
string a-z A-Z 0-9 - _
1-50 The unique ID used by the merchant to identify the transaction.
transaction_type
Required
string a-z A-Z _
1-20 The transaction type being performed.
amount
Required
string 0-9 in the format DDDDDD.CC
1-11 The amount of the transaction.
currency_code_iso3
Required
string a-z A-Z
0-3 The ISO 4217 3-digit currency code of the currency used in the transaction.
merchant_customer_id
string a-z A-Z 0-9 , . - _
0-50 The unique customer ID used by the merchant to identify the customer.
merchant_custom_1
string a-z A-Z 0-9 , . - _
0-50 Merchant custom data.
merchant_custom_2
string a-z A-Z 0-9 , . - _
0-50 Merchant custom data.
merchant_custom_3
string a-z A-Z 0-9 , . - _
0-50 Merchant custom data.
customer object
customer_title
string a-z A-Z , . - _
0-20 The customer’s title such as Mr. or Mrs.
customer_fname
string a-z A-Z , . - _
0-50 The customer’s first name.
customer_mname
string a-z A-Z , . - _
0-50 The customer’s middle name.
customer_lname
MCC 6012
string a-z A-Z , . - _
0-50 The customer’s last name.
customer_gender
string M / F
1 A one character code indicating the customer’s gender.
customer_ipaddress
string IPv4 / IPv6
0-50 The customer’s IP address used in submitting the transaction. 7 to 15 numeric characters in XXX.XXX.XXX.XXX format.
customer_dob
MCC 6012
string 0-9 in the format YYYY-MM-DD
10 The customer’s date of birth in YYYY-MM-DD format.
customer_company
string a-z A-Z 0-9 , . - _
0-50 The customer’s company.
billing object
cardholder_name
string a-z A-Z , . - _
1-100 The cardholder’s name as printed on the card.
cardnumber
Required
int 0-9
12-19 The credit/debit card number used for the transaction.
card_type
string a-z A-Z
2-8 The type of debit/credit card used for the transaction.
Possible values are VISA, MC, AMEX, DISCOVER, DINERS, JCB, MAESTRO.
cardcvv
int 0-9
3-4 The 3-4 digit card verification number. For American Express, four digits displayed on the front of the card; for other card types, usually three digits displayed on the back of the card.
cardexp
Required
string 0-9 in the format MMYYYY
6 The expiration date of the credit/debit card used for the transaction. Details to be submitted in the format MMYYYY.
billing_street
AVS
string a-z A-Z 0-9 , . - _ # / \
1-100 The cardholder’s street address.
billing_street2
string a-z A-Z 0-9 , . - _ # / \
0-100 The cardholder’s street address, line 2.
billing_city
string a-z A-Z 0-9 , . - _
1-100 The city of the cardholder’s address.
billing_state
string a-z A-Z 0-9 , . - _
1-100 The state or province of the cardholder’s address.
billing_zipcode
MCC 6012 & AVS
string a-z A-Z 0-9 , . - _
1-50 The cardholder’s billing ZIP or postal code.
billing_country_code_iso2
string a-z A-Z
2 The ISO 3166 2-character country code of the cardholder’s address. Refer to ‘Country Code v1.0.pdf’ for full list of valid Country Codes.
billing_phone
string 0-9 ( ) + -
7-20 The cardholder’s billing phone number.
billing_email
string 0-9 a-z A-z _ - . @
1-50 The cardholder’s billing email address.
tds object
action
3-D Secure
string a-z A-Z
1-20 Value should be passed as ENQUIRE. Please see here for more information.


{
" timestamp " : " 20170612200235 ",
" response_code " : " 1 ",
" response_message " : " Transaction Success ",
" company_id " : " 133 ",
" mid " : " 1025 ",
" transaction_id " : " 5436756 ",
" transaction_type " : " AUTH_ONLY ",
" merchant_order_id " : " 20170612200234 ",
" amount " : " 100 ",
" currency_code_iso3 " : " GBP ",
" authorization_code " : " ",
" acquirer_reference_number " : " ",
" bank_response_code " : " 1 ",
" avsaddress " : " M ",
" avspostcode " : " M ",
" cvvresult " : " M ",
" bin " : {
" issuing_bank " : " JP MORGAN CHASE NA ",
" card_category " : " CREDIT ",
" card_level " : " ",
" issuing_country " : " United States ",
" issuing_country_iso2 " : " US "
} ,
" response_hash " : " 835956a9fe56d65416..... "
}
< timestamp > 20170612200234 </ timestamp >
< response_code > 1 </ response_code >
< response_message > Transaction Success </ response_message >
< company_id > 133 </ company_id >
< mid > 1025 </ mid >
< transaction_id > 5436756 </ transaction_id >
< transaction_type > AUTH_ONLY </ transaction_type >
< merchant_order_id > 20170612200234 </ merchant_order_id >
< amount > 100 </ amount >
< currency_code_iso3 > GBP </ currency_code_iso3 >
< authorization_code > 4568942 </ authorization_code >
< acquirer_reference_number > </ acquirer_reference_number >
< bank_response_code > 1 </ bank_response_code >
< bin >
< issuing_bank > JP MORGAN CHASE NA </ issuing_bank >
< card_category > CREDIT </ card_category >
< card_level > </ card_level >
< issuing_country > United States </ issuing_country >
< issuing_country_iso2 > US </ issuing_country_iso2 >
</ bin >
< response_hash > 835956a9fe56d65416..... </ response_hash >
</ response >

Response Parameters

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
string 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
response_code
string 0-9
1-3 The code describing the results of the transaction.
response message
string 0-9 a-z A-z _ - ()[]{};[email protected]#$%^*,./\?:”’ +=`
1-65535 Text describing the transaction response.
company_id
string 0-9
1-11 The company ID value. Echoes the company_id from the request message.
mid
string 0-9
1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
transaction_id
string 0-9
1-10 The unique ID generated by Acquired for the transaction.
transaction_type
string a-z A-Z _
1-12 The transaction type being performed. This echoes the tran_type from the request message.
merchant_order_id
string a-z A-Z 0-9 - _
1-50 The unique ID used by the merchant to identify the transaction. This echoes the merchant_order_id from the request message.
amount
string 0-9
1-11 The amount of the transaction.
currency_code_iso3
string a-z A-Z
3 The ISO 4217 3-digit currency code
authorisation_code
string 0-9 a-z A-z _ - ()[]{};[email protected]#$%^*,./\?:”’ +=`
0-50 The authorization code returned by the Issuing Bank.
acquirer_reference_number
string 0-9
0-50 When present, the acquirer reference number is a value set by the acquirer to track the transaction.
avsaddress
string a-z A-Z
1-2 When available the result of the AVS check on the first line of the address.
avszipcode
string a-z A-Z
1-2 When available the result of the AVS check on the customer’s postcode / zipcode.
cvvresult
string a-z A-Z
1-2 The result of the CVV2 security check.
bin object
issuing_bank
string a-z A-Z .
0=50 The name of the bank the issued the card used.
card_category
string a-z A-Z
0-30 The category of the card used. For example CREDIT / DEBIT.
card_level
string a-z A-Z
0-30 The level of the card used. For example CLASSIC.
issuing_country
string a-z A-Z
0-50 The country the issued the card.
issuing_country_iso2
string a-z A-Z
0-50 The ISO2 country code for the country that issued the card.
response_hash
string a-z A-Z 0-9
64 A verification hash value.

An additional response parameter that Acquired can return to its merchants in real-time is the ‘bank_response_code’, which is the actual transaction result code as communicated by the cardholder’s issuing bank. By providing this information it allows merchants to build logic into their payment system to help improve authorisation rates. Contact [email protected] for further details on enabling this feature.


PARAMETER FORMAT LENGTH DESCRIPTION
bank_response_code
int 0-9
2 The transaction result code as communicated by the Issuing Bank.


VOID

A void transaction removes a sale transaction from the existing batch so that the customer will not be charged. Use the VOID value for the transaction_type parameter to perform a void transaction.

{
" timestamp " : " 20170612200234 ",
" company_id " : " 133 ",
" company_pass " : " password ",
" request_hash " : " f0a18260b08a0bfacb.....  ",
" transaction " : {
" transaction_type " : " VOID ",
" original_transaction_id " : " 5436756 "
}
}
< request >
< timestamp > 20170612200234 </ timestamp >
< company_id > 133 </ mid_id >
< company_pass > secret </ mid_pass >
< request_hash > f0a18260b08a0bfacb.....  </ request_hash >
< transaction >
< transaction_type > AUTH_ONLY </ transaction_type >
< original_transaction_id > 5436756 </ original_transaction_id >
</ transaction >

Request Parameters

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
Required
date 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
company_id
Required
int 0-9
1-11 API ID issued by Acquired to the merchant.
company_pass
Required
string 0-9 a-z A-z _ -
1-30 API Password issued by Acquired to the merchant.
request_hash
Required
string a-z A-Z 0-9
64 A verification hash value.
transaction object
transaction_type
Required
string a-z A-Z _
1-20 The transaction type being performed.
original_transaction_id
Required
int 0-9
1-10 Transaction_id value generated by Acquired and returned in the original request.


{
" timestamp " : " 20170612200235 ",
" response_code " : " 1 ",
" response_message " : " Transaction Success ",
" company_id " : " 133 ",
" mid_id " : " 1025 ",
" transaction_id " : " 6784323 ",
" response_hash " : " 835956a9fe56d65416..... "
}
< response >
< timestamp > 20170612200234 </ timestamp >
< response_code > 1 </ response_code >
< response_message > Transaction Success </ response_message >
< company_id > 133 </ company_id >
< mid_id > 1025 </ mid_id >
< transaction_id > 6784323 </ transaction_id >
< response_hash > 835956a9fe56d65416..... </ response_hash >
</ response >

Response Parameters

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
date 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
response_code
int 0-9
1-3 The code describing the results of the transaction.
response message
string 0-9 a-z A-z _ - ()[]{};[email protected]#$%^*,./\?:”’ +=`
1-65535 Text describing the transaction response.
company_id
int 0-9
1-11 The company ID value. Echoes the company_id from the request message.
mid
int 0-9
1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
transaction_id
int 0-9
1-10 The unique ID generated by Acquired for the transaction.
response_hash
string a-z A-Z 0-9
64 A verification hash value.


CAPTURE

A capture transaction request inserts (or captures) a previously authorised transaction into the current batch for settlement. Use the CAPTURE value for the transaction_type parameter to perform a capture transaction.

{
" timestamp " : " 20170612200234 ",
" company_id " : " 133 ",
" company_pass " : " password ",
" request_hash " : " f0a18260b08a0bfacb.....  ",
" transaction " : {
" transaction_type " : " CAPTURE ",
" original_transaction_id " : " 5436756 ",
" amount " : " 100 "
}
}

< request >
< timestamp > 20170612200234 </; timestamp >
< company_id > 133 </; company_id >
< company_pass > secret </; company_pass >
< request_hash > f0a18260b08a0bfacb.....  </; request_hash >
< transaction >
< transaction_type > AUTH_ONLY </; transaction_type >
< original_transaction_id > </; original_transaction_id >
< amount > 100 </; amount >
</ transaction >
</ request >

Request Parmeters

{
" timestamp " : " 20170612200235 ",
" response_code " : " 1 ",
" response_message " : " Transaction Success ",
" company_id " : " 133 ",
" mid_id " : " 1025 ",
" transaction_id " : " 6784323 ",
" response_hash " : " 835956a9fe56d65416..... "
}

< response >
< timestamp > 20170612200234 </ timestamp >
< response_code > 1 </ response_code >
< response_message > Transaction Success </ response_message >
< company_id > 133 </ company_id >
< mid_id > 1025 </ mid_id >
< transaction_id > 6784323 </ transaction_id >
< response_hash > 835956a9fe56d65416..... </ response_hash >
</ response >
PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
Required
date 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
company_id
Required
int 0-9
1-11 API ID issued by Acquired to the merchant.
company_pass
Required
string 0-9 a-z A-z _ -
1-30 API Password issued by Acquired to the merchant.
request_hash
Required
string a-z A-Z 0-9
64 A verification hash value.
transaction object
transaction_type
Required
string a-z A-Z _
1-20 The transaction type being performed.
original_transaction_id
Required
int 0-9
1-10 Transaction_id value generated by Acquired and returned in the original request.
amount
Required
string 0-9 in the format DDDDDD.CC
1-11 The amount of the transaction.


Response Parameters

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
date 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
response_code
int 0-9
1-3 The code describing the results of the transaction.
response message
string 0-9 a-z A-z _ - ()[]{};[email protected]#$%^*,./\?:”’ +=`
1-65535 Text describing the transaction response.
company_id
int 0-9
1-11 The company ID value. Echoes the company_id from the request message.
mid
int 0-9
1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
transaction_id
int 0-9
1-10 The unique ID generated by Acquired for the transaction.
response_hash
string a-z A-Z 0-9
64 A verification hash value.


REFUND

A refund transaction credits the total amount of a previously captured transaction to the cardholder and captures that transaction in the current batch for settlement. Use the REFUND value for the transaction_type parameter to perform a refund transaction.

{
" timestamp " : " 20170612200234 ",
" company_id " : " 133 ",
" company_pass " : " password ",
" request_hash " : " f0a18260b08a0bfacb.....  ",
" transaction " : {
" transaction_type " : " REFUND ",
" original_transaction_id " : " 5436756 ",
" amount " : " 100 "
}
}

< request >
< timestamp > 20170612200234 </ timestamp >
< company_id > 133 </ mid_id >
< company_pass > secret </ company_pass >
< request_hash > f0a18260b08a0bfacb.....  </ request_hash >
< transaction >
< transaction_type > REFUND </ transaction_type >
< original_transaction_id > 5436756 </ original_transaction_id >
< amount > 100 </ amount >
</ transaction >
</ request >
PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
Required
date 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
company_id
Required
int 0-9
1-11 API ID issued by Acquired to the merchant.
company_pass
Required
string 0-9 a-z A-z _ -
1-30 API Password issued by Acquired to the merchant.
request_hash
Required
string a-z A-Z 0-9
64 A verification hash value.
transaction object
transaction_type
Required
string a-z A-Z _
1-20 The transaction type being performed.
original_transaction_id
Required
int 0-9
1-10 Transaction_id value generated by Acquired and returned in the original request.
amount
Required
string 0-9 in the format DDDDDD.CC
1-11 The amount of the transaction.


Response Parameters

{
" timestamp " : " 20170612200235 ",
" response_code " : " 1 ",
" response_message " : " Transaction Success ",
" company_id " : " 133 ",
" mid " : " 1025 ",
" transaction_id " : " 6984324 ",
" transaction_type " : " REFUND ",
" response_hash " : " 835956a9fe56d65416..... "
}

< response >
< timestamp > 20170612200234 </ timestamp >
< response_code > 1 </ response_code >
< response_message > Transaction Success </ response_message >
< company_id > 133 </ company_id >
< mid > 1025 </ mid >
< transaction_id > 6984324 </ transaction_id >
< transaction_type > REFUND </ transaction_id >
< response_hash > 835956a9fe56d65416..... </ response_hash >
</ response >
PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
date 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
response_code
int 0-9
1-3 The code describing the results of the transaction.
response message
string 0-9 a-z A-z _ - ()[]{};[email protected]#$%^*,./\?:”’ +=`
1-65535 Text describing the transaction response.
company_id
int 0-9
1-11 The company ID value. Echoes the company_id from the request message.
mid
int 0-9
1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
transaction_id
int 0-9
1-10 The unique ID generated by Acquired for the transaction.
transaction_type
string a-z A-Z _
1-20 The transaction type being performed.
response_hash
string a-z A-Z 0-9
64 A verification hash value.


CREDIT

A credit transaction credits a specified amount to the cardholder and captures that transaction in the current batch for settlement. Use the CREDIT value for the transaction_type parameter to perform a credit transaction.

This transaction type should only be used by merchant assigned either MCC 6211 or 7995, if you are unsure of your MCC please contact [email protected].

{
" timestamp " : " 20170612200234 ",
" company_id " : " 133 ",
" company_pass " : " password ",
" company_mid_id " : " ",
" request_hash " : " f0a18260b08a0bfacb..... ",
" transaction " : {
" merchant_order_id " : " 20170612200234 ",
" transaction_type " : CREDIT ",
" amount " : 100 ",
" currency_code_iso3 " : GBP ",
" merchant_customer_id " : 100000087 ",
" merchant_custom_1 " : C1 ",
" merchant_custom_2 " : C2 ",
" merchant_custom_3 " : C3 "
} ,
" customer " : {
" customer_title " : Mr ",
" customer_fname " : Edward ",
" customer_mname " : N ",
" customer_lname " : Johnson ",
" customer_gender " : M ",
" customer_dob " : 1988-12-14 ",
" customer_ipaddress " : " 2a02:d7f:c401:5f00:7538:fbfc:4a41:e3d2 ",
" customer_company " : Acquired Payments "
} ,
" billing " : {
" cardholder_name " : MR E N JOHNSON ",
" cardnumber " : 4242424242424242 ",
" card_type " : VISA ",
" cardcvv " : 123 ",
" cardexp " : 022020 ",
" billing_street " : 44 Baker Street ",
" billing_street2 " : ",
" billing_city " : London ",
" billing_state " : ",
" billing_zipcode " : W1U 7AL ",
" billing_country_code_iso2 " : GB ",
" billing_phone " : +44 (0) 7763270200 ",
" billing_email " : [email protected] "
}
}
< request >
< timestamp > 20170612200234 </ timestamp >
< company_id > 133 </ company_id >
< company_pass > secret </ company_pass >
< company_mid_id > </ company_pass >
< request_hash > f0a18260b08a0bfacb.....  </ request_hash >
< transaction >
< merchant_order_id > 20170612200235 </ merchant_order_id >
< transaction_type > CREDIT </ transaction_type >
< amount > 100 </ amount >
< currency_code_iso3 > GBP </ currency_code_iso3 >
< merchant_customer_id > 100000087 </ merchant_customer_id >
< merchant_custom_1 > C1 </ merchant_custom_1 >
< merchant_custom_2 > C2 </ merchant_custom_2 >
< merchant_custom_3 > C3 </ merchant_custom_3 >
</ transaction >
< customer >
< customer_title > Mr </ customer_title >
< customer_fname > Edward </ customer_fname >
< customer_mname > N </ customer_mname >
< customer_lname > Johnson </ customer_lname >
< customer_gender > M </ customer_gender >
< customer_dob > 1988-12-14 </ customer_dob >
< customer_ipaddress > 2a02:d7f:c401:5f00:7538:fbfc:4a41:e3d2 </ customer_ipaddress >
< customer_company > Acquired Payments </ customer_company >
</ customer >
< billing >
< cardholder_name > MR E N JOHNSON </ cardholder_name >
< cardnumber > 4242424242424242 </ cardnumber >
< card_type > VISA </ card_type >
< cardcvv > 123 </ cardcvv >
< cardexp > 022020 </ cardexp >
< billing_street > 44 Baker Street </ billing_street >
< billing_street2 > </ billing_street2 >
< billing_city > London </ billing_city >
< billing_state > </ billing_state >
< billing_zipcode > W1U 7AL </ billing_zipcode >
< billing_country_code_iso2 > GB </ billing_country_code_iso2 >
< billing_phone > +44 (0) 7763270200 </ billing_phone >
< billing_email > [email protected] </ billing_email >
</ billing >
</ request >

Request Parameters

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
Required
date 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
company_id
Required
int 0-9
1-11 API ID issued by Acquired to the merchant.
company_pass
Required
string 0-9 a-z A-z _ -
1-30 API Password issued by Acquired to the merchant.
company_mid_id
string 0-9
1-11 Allows you to target a specific mid_id within the company struture.
request_hash
Required
string a-z A-Z 0-9
64 A verification hash value.
transaction object
merchant_order_id
Required
string a-z A-Z 0-9 - _
1-50 The unique ID used by the merchant to identify the transaction.
transaction_type
Required
string a-z A-Z _
1-20 The transaction type being performed.
amount
Required
string 0-9 in the format DDDDDD.CC
1-11 The amount of the transaction.
currency_code_iso3
Required
string a-z A-Z
0-3 The ISO 4217 3-digit currency code of the currency used in the transaction.
merchant_customer_id
string a-z A-Z 0-9 , . - _
0-50 The unique customer ID used by the merchant to identify the customer.
merchant_custom_1
string a-z A-Z 0-9 , . - _
0-50 Merchant custom data.
merchant_custom_2
string a-z A-Z 0-9 , . - _
0-50 Merchant custom data.
merchant_custom_3
string a-z A-Z 0-9 , . - _
0-50 Merchant custom data.
customer object
customer_title
string a-z A-Z , . - _
0-20 The customer’s title such as Mr. or Mrs.
customer_fname
string a-z A-Z , . - _
0-50 The customer’s first name.
customer_mname
string a-z A-Z , . - _
0-50 The customer’s middle name.
customer_lname
MCC 6012
string a-z A-Z , . - _
0-50 The customer’s last name.
customer_gender
string M / F
1 A one character code indicating the customer’s gender.
customer_ipaddress
string IPv4 / IPv6
0-50 The customer’s IP address used in submitting the transaction. 7 to 15 numeric characters in XXX.XXX.XXX.XXX format.
customer_dob
MCC 6012
string 0-9 in the format YYYY-MM-DD
10 The customer’s date of birth in YYYY-MM-DD format.
customer_company
string a-z A-Z 0-9 , . - _
0-50 The customer’s company.
billing object
cardholder_name
string a-z A-Z , . - _
1-100 The cardholder’s name as printed on the card.
cardnumber
Required
int 0-9
12-19 The credit/debit card number used for the transaction.
card_type
Required
string a-z A-Z
2-8 The type of debit/credit card used for the transaction.
cardexp
Required
int 0-9 in the format MMYYYY
6 The expiration date of the credit/debit card used for the transaction. Details to be submitted in the format MMYYYY.
billing_street
AVS
string a-z A-Z 0-9 , . - _
1-100 The cardholder’s street address.
billing_street2
string a-z A-Z 0-9 , . - _
0-100 The cardholder’s street address, line 2.
billing_city
string a-z A-Z 0-9 , . - _
1-100 The city of the cardholder’s address.
billing_state
string a-z A-Z 0-9 , . - _
1-100 The state or province of the cardholder’s address.
billing_zipcode
MCC 6012 & AVS
string a-z A-Z 0-9 , . - _
1-50 The cardholder’s billing ZIP or postal code.
billing_country_code_iso2
string a-z A-Z
2 The ISO 3166 2-character country code of the cardholder’s address. Refer to ‘Country Code v1.0.pdf’ for full list of valid Country Codes.
billing_phone
string 0-9 ( ) + -
7-20 The cardholder’s billing phone number.
billing_email
string 0-9 a-z A-z _ - . @
1-50 The cardholder’s billing email address.


{
" timestamp " : " 20170612200235 ",
" response_code " : " 1 ",
" response_message " : " Transaction Success ",
" company_id " : " 133 ",
" mid " : " 1025 ",
" transaction_id " : " 5436756 ",
" transaction_type " : " CREDIT ",
" merchant_order_id " : " 20170612200234 ",
" amount " : " 100 ",
" currency_code_iso3 " : " GBP ",
" authorization_code " : " ",
" acquirer_reference_number " : " ",
" bank_response_code " : " 1 ",
" bin " : {
" issuing_bank " : " JP MORGAN CHASE NA ",
" card_category " : " CREDIT ",
" card_level " : " ",
" issuing_country " : " United States ",
" issuing_country_iso2 " : " US ",
" response_hash " : " 835956a9fe56d65416..... "
}
}

< timestamp > 20170612200235 </ timestamp >
< response_code > 1 </ response_code >
< response_message > Transaction Success </ response_message >
< company_id > 133 </ company_id >
< mid > 1025 </ mid >
< transaction_id > 5436756 </ transaction_id >
< transaction_type > CREDIT </ transaction_type >
< merchant_order_id > 20170612200234 </ merchant_order_id >
< amount > 100 </ amount >
< currency_code_iso3 > GBP </ currency_code_iso3 >
< authorization_code > 4568942 </ authorization_code >
< acquirer_reference_number > </ acquirer_reference_number >
< bank_response_code > 1 </ bank_response_code >
< bin >
< issuing_bank > JP MORGAN CHASE NA </ issuing_bank >
< card_category > CREDIT </ card_category >
< card_level > </ card_level >
< issuing_country > United States </ issuing_country >
< issuing_country_iso2 > US </ issuing_country_iso2 >
</ bin >
< response_hash > 835956a9fe56d65416..... </ response_hash >
</ response >

Response Parameters

PARAMETER FORMAT LENGTH DESCRIPTION
timestamp
date 0-9 in the format yyyymmddhhmmss
14 The date and time the transaction was submitted in the format yyyymmddhhmmss format.
response_code
int 0-9
1-3 The code describing the results of the transaction.
response message
string 0-9 a-z A-z _ - ()[]{};[email protected]#$%^*,./\?:”’ +=`
1-65535 Text describing the transaction response.
company_id
int 0-9
1-11 The company ID value. Echoes the company_id from the request message.
mid
int 0-9
1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
transaction_id
int 0-9
1-10 The unique ID generated by Acquired for the transaction.
transaction_type
string a-z A-Z _
1-12 The transaction type being performed. This echoes the tran_type from the request message.
merchant_order_id
string a-z A-Z 0-9 - _
1-50 The unique ID used by the merchant to identify the transaction. This echoes the merchant_order_id from the request message.
amount
string 0-9
1-11 The amount of the transaction.
currency_code_iso3
int a-z A-Z
3 The ISO 4217 3-digit currency code
authorisation_code
string 0-9 a-z A-z _ - ()[]{};[email protected]#$%^*,./\?:”’ +=`
0-50 The authorization code returned by the Issuing Bank.
acquirer_reference_number
int 0-9
0-50 When present, the acquirer reference number Is a value set by the acquirer to track the transaction.
avsaddress
string a-z A-Z
1-2 When available the result of the AVS check on the first line of the address.
avszipcode
string a-z A-Z
1-2 When available the result of the AVS check on the customer’s postcode / zipcode.
cvvresult
string a-z A-Z
1-2 The result of the CVV2 security check.
bin object
issuing_bank
string a-z A-Z .
0-50 The name of the bank the issued the card used.
card_category
string a-z A-Z
0-30 The category of the card used. For example CREDIT / DEBIT.
card_level
string a-z A-Z
0-30 The level of the card used. For example CLASSIC.
issuing_country
string a-z A-Z
0-50 The country that issued the card.
issuing_country_iso2
string a-z A-Z
0-50 The ISO2 country code for the country that issued the card.
response_hash
string a-z A-Z 0-9
64 A verification hash value.
bank_response_code
int 0-9
2 The transaction result code as communicated by the Issuing Bank.