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.

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

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

Parameter Format Length Description
timestamp
Required
date 14 Date and time of transaction submission.
company_id
Required
int 3 API Company ID we issue to merchants.
company_pass
Required
string 10-30 API Password we issue to merchants.
company_mid_id int 0-4 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).
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.
request_hash
Required
string 64 Verification hash value - please see here.
transaction
Required
object Click here.
merchant_order_id
Required
string 1-50 Unique ID you’ll use to identify each transaction.
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.
amount
Required
decimal 0-11 Transaction amount.
currency_code_iso3
Required
string 3 Transaction currency, an ISO 4217 3-digit code.
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.
merchant_customer_id string 0-50 Unique ID to indentify your customer.
merchant_custom_1 string 0-50 Custom merchant data.
merchant_custom_2 string 0-50 Custom merchant data.
merchant_custom_3 string 0-50 Custom merchant data. If utilising dynamic narritive the value should passed in this field.
customer
MCC 6012
object Click here. Click here.
customer_fname string 0-50 Customer’s first name.
customer_lname
MCC 6012
string 0-50 Customer’s last name.
customer_ipaddress string The customer's IP address in either IPv4 or IPv6 format.
customer_dob
MCC 6012
string Customer’s date of birth formatted as YYYY-MM-DD.
billing
Required
object Click here. Click here.
cardholder_name
SCA
string 0-100 Cardholder’s name as printed on their card.
cardnumber
Required
int 12-19 Card number used for the transaction.
cardcvv int 3-4 Card verification value, formatted as three or four digits (for AMEX) depending on the card type.
cardexp
Required
string 6 Expiration date of the card used for the transaction, formatted as MMYYYY.
billing_street
AVS & SCA
string 0-100 Cardholder’s billing street address.
billing_street2
SCA
string 0-100 Cardholder’s billing street address, line 2.
billing_city
SCA
string 0-100 Cardholder’s billing city.
billing_state string 0-100 Cardholder’s billing state or province.
billing_zipcode
MCC 6012 & AVS & SCA
string 0-100 Cardholder’s billing ZIP or postal code.
billing_country_code_iso2
SCA
string 2 Cardholder’s billing country, an ISO 3166 2-character code.
billing_phone_code
SCA
string 2 Cardholder’s billing phone number country code (For example, 44 for the UK).
billing_phone
SCA
string 7-20 Cardholder’s billing phone number.
billing_email
SCA
string 0-50 Cardholder’s billing email address.
shipping object Click here.
shipping_street string 0-100 Cardholder’s shipping street address.
shipping_street2 string 0-100 Cardholder’s shipping street address, line 2.
shipping_city string 0-100 Cardholder’s shipping city.
shipping_state string 0-100 Cardholder’s shipping state or province.
shipping_zipcode string 0-100 Cardholder’s shipping ZIP or postal code.
shipping_country_code_iso2 string 2 Cardholder’s shipping country, an ISO 3166 2-character code.
shipping_phone_code string 2 Cardholder’s shipping phone number country code (For example, 44 for the UK).
shipping_phone string 7-20 Cardholder’s shipping phone number.
shipping_email string 0-50 Cardholder’s shipping email address.
{
  "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,
    "card_exp":"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":"+44(0)2039826580",
    "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":"+44(0)2039826580",
    "shipping_email":"support@acquired.com"
    
},
}
Processing with 3-D Secure / SCA? there is an additional "tds" object you will need to send with this request, you should take a look here.

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

Parameter Format Length Description
timestamp date 14 Date and time of transaction response.
response_code int 3 Code describing the transaction result.
response_message string 1-100 Text describing the transaction response.
company_id int 3 API Company ID we issue to merchants.
mid string 4 MID_ID the transaction was processed through.
transaction_id int 1-10 Unique ID we generate to identify the transaction.
transaction_type string 1-12 Transaction type, repeated from the request message.
merchant_order_id string 1-50 Unique ID you’ll use to identify each transaction, repeated from the request.
amount string 1-11 Transaction amount.
currency_code_iso3 string 3 Transaction currency, an ISO 4217 3-digit code.
authorization_code string 0-50 Authorisation code returned by the issuing bank.
acquirer_reference_number string 0-50 Value set by the acquirer to track the transaction, when present.
avsaddress string 1-2 AVS check on the first line of the customer’s address, when available.
avszipcode string 1-2 AVS check on the customer’s postcode or zipcode, when available.
cvvresult string 1-2 Result of CVV2 security check.
bank_response_code int 2 Transaction result code communicated by the issuing bank.
bin object
issuing_bank string 0-50 Name of the bank issuing the card used for the transaction.
card_category string 0-30 Category of the card used, for example CREDIT or DEBIT.
card_level string 0-30 Level of the card used, for example CLASSIC.
issuing_country string 0-50 Country issuing the card used for the transaction.
issuing_country_iso2 string 2 Country issuing the card used for the transaction, an ISO2 two-letter code.
response_hash string 64 Verification hash value.
{
"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, the transaction_type parameter gets the value VOID.

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

Parameter Format Length Description
timestamp
Required
date 14 Date and time of transaction submission.
company_id
Required
int 1-11 API Company ID we issue to merchants.
company_pass
Required
string 1-30 API Password we issue to merchants.
request_hash
Required
string 64 Verification hash value.
transaction object
transaction_type
Required
string 1-20 Transaction type is VOID.
original_transaction_id
Required
string 1-10 transaction_id value we generated and returned in the original request.
{
    "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.

Parameter Format Length Description
timestamp date 14 Date and time of transaction submission, in the format yyyymmddhhmmss.
response_code int 1-3 Transaction result code.
response_message string 1-100 Transaction result text.
company_id int 1-11 API Company ID we issue to merchants, repeated from the request message.
mid int 1-11 MID_ID the transaction was processed through.
transaction_id int 1-10 Unique ID we generate to identify the transaction.
response_hash string 64 Verification hash value.
{
    "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.

Parameter Format Length Description
timestamp
Required
date 1-10 Date and time of transaction submission.
company_id
Required
int 1-11 API Company ID we issue to merchants.
company_pass
Required
string 1-30 API Password we issue to merchants.
request_hash
Required
string 64 Verification hash value.
transaction object
transaction_type
Required
string 1-20 Transaction type is CAPTURE.
original_transaction_id
Required
int 1-10 Transaction_id value we generated and returned in the original request.
amount
Required
int 1-11 Transaction amount you want to capture.
{
    "timestamp":"20170612200234",
    "company_id":"133",
    "company_pass":"password",
    "transaction":"":{
        "transaction_type":"VOID",
        "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.

Parameter Format Length Description
timestamp date 14 Date and time of transaction submission.
response_code int 1-3 Transaction result code.
response_message string 1-100 Transaction result text.
company_id int 1-11 API Company ID we issue to merchants, repeated from the request message.
mid int 1-11 Merchant ID the transaction was processed through.
transaction_id int 1-10 Unique ID we generate to identify the transaction.
response_hash string 64 Verification hash value.
{
    "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, some sample code is below too.

Parameter Format Length Description
timestamp
Required
date 14 Date and time of transaction submission.
company_id
Required
int 1-11 API Company ID we issue to merchants.
company_pass
Required
string 1-30 API Password we issue to merchants.
request_hash
Required
string 64 Verification hash value.
transaction object
transaction_type
Required
string 1-20 Transaction type is REFUND.
original_transaction_id
Required
int 1-10 Transaction_id value we generated and returned in the original request.
amount
Required
int 1-11 Transaction amount you want to refund back to the cardholder.
{
    "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.