Please note that we are no longer onboarding new customers to this version of our API. Please visit our new documentation site https://docs.acquired.com
Get a test account Login

Card API

Integrating directly with Acquired.com’s platform using our CARD API is a great choice if you have enhanced security capabilities. That’s because you’ll be responsible for PCI DSS (that’s Payment Card Industry Data Security Standard) yourself, with the more complicated requirement of completing SAQ (Self-Assessment Questionnaire) D.

Endpoints

Time to play - access your API using these endpoints:

Authorisation

Card transactions result in one of two transaction_type parameters for authorisation:

  • AUTH_ONLY verifies the customer account and okays the transaction now. The payment completes when you process the CAPTURE later.
  • AUTH_CAPTURE performs both actions in one step to process the payment now.

Here’s a list of mandatory and additional parameters that may accompany a request, and some handy sample code.

Request

Parameter Format Length Description
timestamp
Required		 date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id
Required		 int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
company_pass
Required		 string 10-30 API Password we issue to merchants.
Acceptable Characters: 0-9 a-z A-z
company_mid_id int 1-11 Targets a specific mid_id within the company structure. Leave it blank (or don't pass it) to balance traffic across multiple mid_ids (banks).
Acceptable Characters: 0-9
user_agent string 1-1000 Useragent data.
vt boolean 1 Additional parameter to flag a transaction as MOTO - include if processing payments via phone or an IVR solution.
Acceptable Characters: 0/1
request_hash
Required		 string 64 Verification hash value - please see here.
Acceptable Characters: 0-9 a-z A-z _ -
transaction
Required		 object Click here.
merchant_order_id
Required		 string 1-50 Unique ID you’ll use to identify each transaction.
Acceptable Characters: a-z A-Z 0-9 _ -
transaction_type
Required		 string 1-20 The type of transaction you are trying to perform - possible values for this request are either AUTH_ONLY or AUTH_CAPTURE.
Acceptable Characters: a-z A-Z _
amount
Required		 string 0-11 Transaction amount.
Acceptable Characters: 0-9 in the format DDDDDD.CC
currency_code_iso3
Required		 string 3 Transaction currency, an ISO 4217 3-digit code.
Acceptable Characters: a-z A-Z
subscription_type string 1-20 If you want to tokenise the card details for future use - set this field to INIT. See here for more information.
Acceptable Characters: a-Z A-Z _
merchant_customer_id string 0-50 Your internal unique customer reference. You can use this field to link multiple transactions to a single customer.
Acceptable Characters: a-z A-Z 0-9 , . - _
merchant_custom_1 string 0-50 You can send additional data relating to the customer or another internal reference - with more data, your internal teams will be able to identify the customer’s transactions.
Acceptable Characters: a-z A-Z 0-9 , . - _
merchant_custom_2 string 0-50 You can send additional data relating to the customer or another internal reference - with more data, your internal teams will be able to identify the customer’s transactions.
Acceptable Characters: a-z A-Z 0-9 , . - _
merchant_custom_3 string 0-50 You can send additional data relating to the customer or another internal reference - with more data, your internal teams will be able to identify the customer’s transactions. If you are using our dynamic descriptor feature, you will not be able to use the merchant_custom_3 field as the dynamic descriptor value should be passed in this field.
Acceptable Characters: a-z A-Z 0-9 , . - _
customer
MCC 6012		 object Click here. Click here.
customer_fname string 0-50 Customer’s first name.
Acceptable Characters: a-z A-Z , . - _
customer_lname
MCC 6012		 string 0-50 Customer’s last name.
Acceptable Characters: a-z A-Z , . - _
customer_ipaddress string The customer’s IP address used in submitting the transaction.
Acceptable Characters: 0-9 in the format XXX.XXX.XXX.XXX (IPv4 / IPv6 )
customer_dob
MCC 6012		 string 10 Customer’s date of birth.
Acceptable Characters: 0-9 in the format YYYY-MM-DD
billing
Required		 object Click here. Click here.
cardholder_name
EMV 3DS (Required)		 string 0-45 Cardholder’s name as printed on their card.
Acceptable Characters: a-z A-Z , . - '
cardnumber
Required		 int 12-19 Card number used for the transaction.
Acceptable Characters: 0-9
cardcvv int 3-4 Card verification value, formatted as three or four digits (for AMEX) depending on the card type.
Acceptable Characters: 0-9 in the format XXXX
cardexp
Required		 string 6 Expiration date of the card used for the transaction, formatted as MMYYYY.
Acceptable Characters: 0-9 in the format MMYYYY
billing_street
AVS & EMV 3DS (Recommended)		 string 0-50 Cardholder’s billing street address.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
billing_street2 string 0-50 Cardholder’s billing street address, line 2.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
billing_city
EMV 3DS (Recommended)		 string 0-100 Cardholder’s billing city.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
billing_state string 0-100 Cardholder’s billing state or province.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_zipcode
MCC 6012 & AVS & EMV 3DS (Recommended)		 string 0-100 Cardholder’s billing ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_country_code_iso2
EMV 3DS (Recommended)		 string 2 Cardholder’s billing country, an ISO 3166 2-character code.
Acceptable Characters: a-z A-Z
billing_phone_code string 3 Cardholder’s billing phone number country code (For example, 44 for the UK).
Acceptable Characters: 0-9 ( ) -
billing_phone string 7-15 Cardholder’s billing phone number.
Acceptable Characters: 0-9 ( ) -
billing_email
EMV 3DS (Recommended)		 string 0-254 Cardholder’s billing email address.
Acceptable Characters: 0-9 a-z A-z _ - . @
shipping object Click here.
shipping_street string 0-100 Cardholder’s shipping street address.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
shipping_street2 string 0-100 Cardholder’s shipping street address, line 2.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
shipping_city string 0-100 Cardholder’s shipping city.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
shipping_state string 0-100 Cardholder’s shipping state or province.
Acceptable Characters: a-z A-Z 0-9 , . - _
shipping_zipcode string 0-100 Cardholder’s shipping ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
shipping_country_code_iso2 string 2 Cardholder’s shipping country, an ISO 3166 2-character code.
Acceptable Characters: a-z A-Z
shipping_phone_code string 2 Cardholder’s shipping phone number country code (For example, 44 for the UK).
Acceptable Characters: 0-9 ( ) -
shipping_phone string 7-15 Cardholder’s shipping phone number.
Acceptable Characters: 0-9 ( ) -
shipping_email string 0-254 Cardholder’s shipping email address.
Acceptable Characters: 0-9 a-z A-z _ - . @ 
{
  "timestamp":"20190620101530",
  "company_id":113,
  "company_pass":"password",
  "company_mid_id":1045,
  "vt":"",
  "useragent":"",
  "request_hash" : "f0a18260b08a0bfacb.....",
"transaction":{ 
    "merchant_order_id":"a9f0ce93-6f0d-4a15-a18b-45f1304b4bc0",
    "transaction_type":"AUTH_CAPTURE",
    "amount":"14.99",
    "currency_code_iso3":"GBP",
    "subscription_type":"INIT",
    "merchant_customer_id":"",
    "merchant_custom_1":"",
    "merchant_custom_2":"",
    "merchant_custom_3":""
    
},
"customer" : { 
    "customer_fname":"Edward",
    "customer_lname":"Johnson",
    "customer_ipaddress":"127.0.0.1",
    "customer_dob":"1988-10-03"
    
},
"billing" : { 
    "cardholder_name":"",
    "cardnumber":4000011180138710,
    "cardcvv":123,
    "cardexp":"022020",
    "billing_street":"Suite 2, 4th Floor",
    "billing_street2":"44 Baker Street",
    "billing_city":"London",
    "billing_state":"",
    "billing_zipcode":"W1U7AL",
    "billing_country_code_iso2":"GB",
    "billing_phone_code":"44",
    "billing_phone":"02039826580",
    "billing_email":"support@acquired.com"
    
},
"shipping" : { 
    "shipping_street":"Suite 2, 4th Floor",
    "shipping_street2":"44 Baker Street",
    "shipping_city":"London",
    "shipping_state":"",
    "shipping_zipcode":"W1U7AL",
    "shipping_country_code_iso2":"GB",
    "shipping_phone_code":"44",
    "shipping_phone":"02039826580",
    "shipping_email":"support@acquired.com"
    
}
}
Do you need to authenticate your customer via 3-D Secure? There is an additional tds object you need to add to your request. Please see here for Version 1 or here for Version 2.

After processing the transaction request, we’ll return a response to confirm the outcome. Again, some handy sample code alongside.

Response

Parameter Format Length Description
timestamp date 14 Date and time of transaction response.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
response_code int 3 Code describing the transaction result.
Acceptable Characters: 0-9
response_message string 1-100 Text describing the transaction response.
Acceptable Characters: 0-9 a-z A-z _ - ()[]{};~!@#$%^*,./\?:”’ +=`
company_id int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
mid string 1-11 MID_ID the transaction was processed through.
Acceptable Characters: 0-9
transaction_id int 1-10 Unique ID we generate to identify the transaction.
Acceptable Characters: 0-9
transaction_type string 1-12 Transaction type, repeated from the request message.
Acceptable Characters: a-z A-Z _
merchant_order_id string 1-50 Unique ID you’ll use to identify each transaction, repeated from the request.
Acceptable Characters: a-z A-Z 0-9 _ -
amount string 1-11 Transaction amount.
Acceptable Characters: 0-9 in the format DDDDDD.CC
currency_code_iso3 string 3 Transaction currency, an ISO 4217 3-digit code.
Acceptable Characters: a-z A-Z
authorization_code string 0-50 Authorisation code returned by the issuing bank.
Acceptable Characters: 0-9
acquirer_reference_number string 0-50 Value set by the acquirer to track the transaction, when present.
Acceptable Characters: 0-9
scheme_reference_data string 0-15 Value set by the schemes to track the transaction, returned where supported.
Acceptable Characters: a-zA-Z0-9
avsaddress string 1-2 AVS check on the first line of the customer’s address, when available.
Acceptable Characters: a-z A-Z
avszipcode string 1-2 AVS check on the customer’s postcode or zipcode, when available.
Acceptable Characters: a-z A-Z
cvvresult string 1-2 Result of CVV2 security check.
Acceptable Characters: a-z A-Z
bank_response_code int 2 Transaction result code communicated by the issuing bank.
Acceptable Characters: 0-9
bin object
issuing_bank string 0-50 Name of the bank issuing the card used for the transaction.
Acceptable Characters: a-z A-Z .
card_category string 0-30 Category of the card used, for example CREDIT or DEBIT.
Acceptable Characters: a-z A-Z
card_level string 0-30 Level of the card used, for example CLASSIC.
Acceptable Characters: a-z A-Z
issuing_country string 0-50 Country issuing the card used for the transaction.
Acceptable Characters: a-z A-Z
issuing_country_iso2 string 2 Country issuing the card used for the transaction, an ISO2 two-letter code.
Acceptable Characters: a-z A-Z
response_hash string 64 Verification hash value.
Acceptable Characters: a-z A-Z 0-9
tds
3D Secure		 object
status
3D Secure		 string 1 This is where you find the outcome of the authentication. The possible values you will find are:

Y Cardholder has been successfully authenticated.

A: Cardholder is enrolled and the bank has acknowledged the attempted authentication.

N: Cardholder did not authenticate successfully (the password entered was incorrect). If you choose to authorise this transaction, you will be liable for a dispute.

U: Cardholder authentication is currently unavailable.
eci
3D Secure		 int 1 The e-commerce indicator. 

{
    "timestamp": "20190620101531",
    "response_code": "1",
    "response_message": "Transaction Success",
    "company_id": 113,
    "mid": 1045,
    "transaction_id": "5436756",
    "transaction_type": "AUTH_CAPTURE",
    "amount": "14.99",
    "currency_code_iso3": "GBP",
    "authorization_code": "123456",
    "acquirer_reference_number": "7270912091283121",
    "avsaddress": "M",
    "avszipcode": "M",
    "cvvresult": "M",
    "bank_response_code": "1",
    "bin": {
        "issuing_bank": "ACQUIRED.COM",
        "card_category": "DEBIT",
        "card_level": "STANDARD",
        "issuing_country": "United Kingdom",
        "issuing_country_iso2": "GB"
    },
    "response_hash": "835956a9fe56d65416....."
}

Void

An almost-sale, we hate these too. A ‘void’ transaction removes a transaction from the current batch so the customer is not charged at all. When this happens, you need to set the transaction_type parameter to VOID.

Please note - you can only process a VOID the day the transaction is processed.

Below is a list of mandatory and additional parameters that may accompany a request, and some handy sample code.

Request

Parameter Format Length Description
timestamp
Required		 date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id
Required		 int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
company_pass
Required		 string 1-30 API Password we issue to merchants.
Acceptable Characters: 0-9 a-z A-z
request_hash
Required		 string 64 Verification hash value.
Acceptable Characters: 0-9 a-z A-z _ -
transaction object
transaction_type
Required		 string 1-20 Transaction type is VOID.
Acceptable Characters: a-z A-Z _
original_transaction_id
Required		 string 1-10 transaction_id value we generated and returned in the original request.
Acceptable Characters: 0-9		 

{
    "timestamp": "20190620101530",
    "company_id": "113",
    "company_pass": "password",
    "request_hash": "f0a18260b08a0bfacb.....",
    "transaction": {
        "transaction_type": "VOID",
        "original_transaction_id": "5436756"
    }
}

Again, after processing the transaction request we’ll return a response to confirm the outcome. Take a look at the handy sample code alongside.

Response

Parameter Format Length Description
timestamp date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
response_code int 1-3 Transaction result code.
Acceptable Characters: 0-9
response_message string 1-100 Transaction result text.
Acceptable Characters: 0-9 a-z A-z _ - ()[]{};~!@#$%^*,./\?:”’ +=`
company_id int 1-11 API Company ID we issue to merchants, repeated from the request message.
Acceptable Characters: 0-9
mid int 1-11 MID_ID the transaction was processed through.
Acceptable Characters: 0-9
transaction_id int 1-10 Unique ID we generate to identify the transaction.
Acceptable Characters: 0-9
response_hash string 64 Verification hash value.
Acceptable Characters: a-z A-Z 0-9 

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

Capture

Let’s get some money in the bank - it’s time to submit or ‘capture’ a batch of authorised transactions for settlement. The transaction_type parameter gets the valueCAPTURE.

We didn’t forget, here’s your list of mandatory and additional parameters that may accompany the request. Again, some handy sample code alongside.

Request

Parameter Format Length Description
timestamp
Required		 date 1-10 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id
Required		 int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
company_pass
Required		 string 1-30 API Password we issue to merchants.
Acceptable Characters: 0-9 a-z A-z
request_hash
Required		 string 64 Verification hash value.
Acceptable Characters: 0-9 a-z A-z _ -
transaction object
transaction_type
Required		 string 1-20 Transaction type is CAPTURE.
Acceptable Characters: a-z A-Z _
original_transaction_id
Required		 int 1-10 Transaction_id value we generated and returned in the original request.
Acceptable Characters: 0-9
amount
Required		 int 1-11 Transaction amount you want to capture.
Acceptable Characters: 0-9 in the format DDDDDD.CC 
{
    "timestamp": "20170612200234",
    "company_id": "133",
    "company_pass": "password",
    "request_hash": "335956a9fe56d65455.....",
    "transaction": {
        "transaction_type": "CAPTURE",
        "original_transaction_id": 5436756,
        "amount": "14.99"
    }
}

You guessed it! After processing the transaction request, we’ll return a response to confirm the outcome. There’s sample code alongside in case you need it.

Response

Parameter Format Length Description
timestamp date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
response_code int 1-3 Transaction result code.
Acceptable Characters: 0-9
response_message string 1-100 Transaction result text.
Acceptable Characters: 0-9 a-z A-z _ - ()[]{};~!@#$%^*,./\?:”’ +=`
company_id int 1-11 API Company ID we issue to merchants, repeated from the request message.
Acceptable Characters: 0-9
mid int 1-11 Merchant ID the transaction was processed through.
Acceptable Characters: 0-9
transaction_id int 1-10 Unique ID we generate to identify the transaction.
Acceptable Characters: 0-9
response_hash string 64 Verification hash value.
Acceptable Characters: a-z A-Z 0-9 

{
    "timestamp":"20170612200235",
    "response_code":"1",
    "response_message":"Transaction Success",
    "company_id":113,
    "mid":1045,
    "transaction_id":6784323,
    "response_hash":"835956a9fe56d65416....."
}

Refund

Someone wants their money back. In other words, you need to return the total amount of a previously captured transaction back to the cardholder. It’s not the end of the world. A refund transaction gets captured in the current batch for settlement, and the transaction_type parameter gets the value REFUND.

For reference, here’s the mandatory and additional parameters that may accompany a request. In case you need it, there is some sample code on the right too.

Request

Parameter Format Length Description
timestamp
Required		 date 14 Date and time of transaction submission.
0-9 in the format yyyymmddhhmmss
company_id
Required		 int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
company_pass
Required		 string 1-30 API Password we issue to merchants.
Acceptable Characters: 0-9 a-z A-z
request_hash
Required		 string 64 Verification hash value.
Acceptable Characters: 0-9 a-z A-z _ -
transaction object
transaction_type
Required		 string 1-20 Transaction type is REFUND.
Acceptable Characters: a-z A-Z _
original_transaction_id
Required		 int 1-10 Transaction_id value we generated and returned in the original request.
Acceptable Characters: 0-9
amount
Required		 int 1-11 Transaction amount you want to refund back to the cardholder.
Acceptable Characters: 0-9 in the format DDDDDD.CC 

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

Just like other transaction types, after processing the request we’ll return a response to confirm the outcome. Your sample code is to the right.

Response

Parameter Format Length Description
timestamp
 date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
response_code
 int 1-3 Transaction result code.
Acceptable Characters: 0-9
company_id
 int 1-11 API Company ID we issue to merchants, repeated from the request message.
Acceptable Characters: 0-9
mid
 string 1-11 MID_ID the transaction was processed through.
Acceptable Characters: 0-9
transaction_id int 1-10 Unique ID we generate to identify the transaction.
Acceptable Characters: 0-9
transaction_type
 string 1-12 Transaction type, repeated from the request message.
Acceptable Characters: a-z A-Z _
avsaddress
 string 1-2 AVS check on the first line of the customer’s address, when available.
Acceptable Characters: a-z A-Z
avszipcode
 string 1-2 AVS check on the customer’s postcode or zipcode, when available.
Acceptable Characters: a-z A-Z
cvvresult
 string 1-2 Result of CVV2 security check.
Acceptable Characters: a-z A-Z
response_hash
 string 64 Verification hash value.
Acceptable Characters: a-z A-Z 0-9		 

{
    "timestamp": "20191119161310",
    "response_code": "1",
    "response_message": "Transaction Success",
    "company_id": "198",
    "mid": "1698",
    "transaction_id": "31345918",
    "transaction_type": "REFUND",
    "avsaddress": "NC",
    "avszipcode": "NC",
    "cvvresult": "NP",
    "response_hash": "6ca59b64a2278c4e76014062a5748b85cdea09577d6de4da6a60c75247e70ba3"
}