Sale API

Written by

The Sale API allows the merchant to fully control the flow over the entire payment process allowing the merchant to provide a unique experience by designing their own payments page while also handling the payments process.

Making The Request
HTTP is used as the request-response protocol between a merchants site and the ABPAY API. In the back end, a merchant submits a HTTP POST request to the ABPAY server, the server will then return an JSON document where the merchant must then cater for the action listed, which could be either 3D Secure, Declined or A Successful Transaction. The response contains key information about the request and also contains the requested content.

The request string that is sent for the `Sale` call must be composed of the following information:
1. username = someName
2. password = somePassword
3. messageID = *GUID (e.g. f8caeef6-0b5f-4044-bc3f-3514f52fd8d2)
4. APISignature = Register
5. data = Form data in JSON format

The above parameters are required when sending HTTP POST data to our API in order to receive a successful response. The data parameter must be composed of the collected information the merchant gathered from the customer while using our Available Form Data fields.

Sample `Sale` Request

<?php															
function httpPost($url, $params) //Post method															
{															
  $params = json_encode($params); //Convert array of params into json string															
  															
  $ch = curl_init($url); //create a new cURL resource															
  															
  //set appropriate options															
  curl_setopt($ch, CURLOPT_POST, 1);															
  curl_setopt($ch, CURLOPT_POSTFIELDS, $params);															
  curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);															
  curl_setopt($ch, CURLOPT_HEADER, 0);															
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);															
  curl_setopt($ch, CURLOPT_HTTPHEADER ,array(															
    "Content-Type: application/json"															
  );															
															
  $response = curl_exec($ch); //grab URL and pass it to the browser while assigning the response to `$response`															
  curl_close($ch); //close cURL resource, and free up system resources															
  return $response;															
}															
															
															
$APIURL = "http://acquirer-stage.myabpay.com/merchant/service"; //Set API URL to ABPAY staging environment															
$params = array(															
"APISignature" => "sale", //API Signature															
"messageID" => GUID(), //A new GUID is required for every new API Call															
"username" => "tester", //API Username															
"password" => "testsersystem", //API Password															
"data" => array(															
  "amount" => "5200",															
  "cardType" => "Debit",															
  "cardnumber" => "4120000000000001",															
  "cardName" => "Mark hile",															
  "cardCVV" => "255",															
  "cardMonth" => "12",															
  "cardYear" => "2020",															
  "transactionCode" => "A2tcj25lfz5tUuFgdh",															
  "currency" => "GBP",															
  "ipaddress" => "124.133.0.1",															
  "agentHeader" => "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)",															
  ) //Data fields required for request "sale" API															
);															
															
$response= httpPost($APIURL, $params); //User defined function used to POST data to API and assign the response to `$response` variable															
echo $response;															
															
// More code...															
?>

 

 
 
Data Required
Below is a table containing all the available fields for passing POST data into the data parameter within the `Sale` request. These fields should be filled using collected data from the consumer on a Form Level.
 
  FieldsName Description Required Required
  amount Total Transaction Amount (Without Decimals). E.g: €100.00 = [10000], €123.67 = [12367], €0.99 = [99]. Y N(20)
  cardType Type of Card (Debit, Credit) Y A(6)
  cardnumber Card Number Y N(19)
  cardName Card Holder Name Y AN(100)
  cardCVV Card Cvv Y N(3)
  cardMonth Card Expiration Month (MM) Y N(2)
  cardYear Card Expiration Year (YYYY) Y N(4)
  transactionCode Transaction Code. The merchant should provide a unique Transaction Code for each transaction. Y AN(40)
  currency Currency of payment (GBP/EUR) Y A(3)
  ipaddress Consumer IP Address. Format NNN.NNN.NNN.NNN. Y AN(15)
  agentHeader The Exact Content Of The HTTP User Agent Header Y AN(500)

Fields Validation
Below is a table containing all the available fields for the data parameter within the `Sale` request including its validation. These are used when constructing the merchants request data.

  FieldsName Description Validation
  amount Total Transaction Amount ^[0-9]{0,20}$
  cardType Type of Card ^(Credit|Debit)$
  cardnumber Card Number Luhn Algorithm
  cardName Card Holder Name ^[a-zA-Z0-9 ,'._-]{0,100}$
  cardCVV Card Cvv ^[0-9]{3}$
  cardMonth Card Expiration Month (MM) ^((0[1-9])|(1[0-2]))$
  cardYear Card Expiration Year (YYYY) ^(20)?(([1-2][0-9]))$
  transactionCode Transaction Code. ^[-_0-9A-Za-z]{0,40}$
  currency Currency of payment ^(GBP|EUR)$
  ipaddress Consumer IP Address. ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$
  agentHeader HTTP User Agent Header ^[a-zA-Z0-9\s,()./*+'\[\]_:;=-]{1,400}$
 

Sample `Sale` JSON Document
The below sample demonstrates what is expected when passing POST data into the data parameter. When forming the data parameter, please refer to our guidelines above.

{									
  "amount": "5200",									
  "cardType": "Debit",									
  "cardnumber": "4120000000000001",									
  "cardName": "Mark hile",									
  "cardCVV": "255",									
  "cardMonth": "12",									
  "cardYear": "2020",									
  "transactionCode": "A2tcj25lfz5tUuFgdh",									
  "currency": "GBP",									
  "ipaddress": "124.133.0.1",									
  "agentHeader": "Mozilla\/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)"									
}		

Data Returned
Below are the expected JSON fields returned from the merchants request, depending on what way the merchant has requested the notification method to be setup & if the provided card is 3D Secure, will determine what type of data is returned.

The merchant will receive 0 - Confirmation received in response for confirm. But If the provided card is 3D Secure, the merchant will receive 01- Successful within the server response after the request has been made. The merchant must now cater for 3D secure, please see Overview for more information.

Sample JSON Response if the Card is 3D Secure 

{															
  "result": true,															
  "messageID": "bf290f74-14da-400c-bee6-f05f1ecb5434",															
  "code": "01",															
  "data": { 															
    "message": "Successful",															
    "PaReq": "2nL3k7NnAy8ogjpcoK4McZlgU4htbKrlph+ywSxYTX+6D3tviWT+tPrw2h2gU45bDplwhMs1Zx+v4QE+Q2BFGroQuOQi5vZ3OOfODsNu77gM9EgRSNNPxn0SDCWiRIo8M5kIlrYnSQkslNq0lmp2SCLTOE5BZpUtz4P3QA3oCBCqz4auyzIeU5s2Mr9OIoplQdGSWAnWFBOhFaVS5qLAG7FXC5+NJN0njOF4/rnE88982k+jzp8zeX0Y3QF0FgUSUyH2P9b2B320xNgyDYbcHtOYJiNSp4vevMfOuPKvySBDI3VOjBjHPpf4ydrfKGNTywAfOmDMigPs802hrrNvn2G5x0X734DyXpbM2CMKBz5zlNa7blXWJ9VnTr2rLqOuhx5PS4/Vt9O9X/AIlllLC",															
    "MD": "eNpVUttSwjAQfc9XMDw7pGkLArNmBkVGdMBSvIynnV0lSNOStgz8vUnLRd",															
    "ACSURL": "https://3DSecureSite.com/Page.aspx"															
  }															
}​
 
Sample JSON Response if the Card is NOT 3D Secure
 
{									
  "result": true,									
  "messageID": "bf290f74-14da-400c-bee6-f05f1ecb5434",									
  "code": "0",									
  "data": { 									
    "message": "Confirmation received"									
  }									
}	
 
Please see Appendix for a list of available error codes if you facing with any error code instead of "0" and "01"
 

  
Slide background

Let's start a

conversation

Let's work together to reach your goals. Contact us at the links below and a representative will be in touch.

EMAIL US

HEAD OFFICE

CALL US

STAY CONNECTED

UK +44 (0) 7557434709

A&B General (UK) LTD.

Pepys House, 10 Greenwich Quay, Clarence Rd, Greenwich, London SE8 3EY

DE +49 (0) 800 724 3923

Get in touch

We are here to help you and your business. Contact us using the button below.

More in this category: « Overview 3D Secure Auth »