Overview

Written by ABPAY

You will receive Staging API credentials from ABPAY when the Account get approved. Then you can send any test request to our service.

Using our staging platform allows merchants to easily integrate to ABPAY in a safe environment while not effecting anything live. Once staging is complete and the merchant is satisfied with the results, ABPAY will provide the merchant with Live API credentials where they can begin live tests using real live data.

Please ensure the below has been obtained before starting :

- API Endpoint (Where the POST requests are sent).

- Username

- Password

the merchant will have to supply ABPAY with the IP Address of the server that hosts the application making calls to the ABPAY API. This is to allow ABPAY to 'whitelist' the provided IP, providing clearance to use the web service.

The HTTP Method is POST, all form actions will be POSTED from the merchants website to the API supplied by ABPAY. The supplied username and password API credentials must be used to successfully perform a request

API Request Fields
Below is the required format to access our services from the API:

Requirement	Detail
Content-Type	application/json
HTTP Method	Post
username	Supplied by ABPAY
password	Supplied by ABPAY
APISignature	Varies depending on API to be invoked
messageID	A Unique GUID to identify the API call (e.g bf290f74-14da-400c-bee6- f05f1ecb5434)
data	Varies depending on API to be invoked

The messageID is a global unique identifier (GUID) - a 128 bit hexadecimal number that ensures each request has a unique reference.

The APISignature identifies the type of call/request that is being made to the API. It is literally a one word description of the request type. For example, 'sale' for the Sale call and 'refund' for refunding a payment. It is essential that the appropriate signature word is included in each request.

The data field is where the form details are sent in JSON format. The JSON structure varies depending on the function of the API being executed. All the inputs from the customer facing form must be sent in an JSON as string in the data field, this JSON data must match our listed validations which can be found under each API section.

In each API section and under data required, the type of value and maximum character length expected are indicated in the Field Definition column. The merchant must ensure the form does not return values that exceed these limits in order to avoid error responses from the API. Please ensure all specified fields are validated accordingly to prevent errors.

Field Definition - Explanation :

Data Type		Description
N(int)		A Numeric sequence of up to `int` digits. Accepts: '0-9'.
A(int)		An alpha only string of up to `int` characters. Accepts: 'A–Z' & 'a-z'.
AN(int)		An alphanumeric string of up to `int` characters. Accepts: 'a-z', 'A-Z' & '0–9'.

Sample 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(...) //Data fields required for request															
);															
															
$Response = httpPost($APIURL, $params); //User defined function used to POST data to API and assign the response to `$Response` variable															
echo $response;															
?>

API Responses

The API will always return back JSON as following parameters:

Requirement		Detail
Content-Type	Description
Result	A Numeric sequence of up to `int` digits. Accepts: '0-9'.
MessageID	An alpha only string of up to `int` characters. Accepts: 'A–Z' & 'a-z'.
Code	An alphanumeric string of up to `int` characters. Accepts: 'a-z', 'A-Z' & '0–9'.
Data	Varies depending on API to be responsed

Sample JSON Response

{									
  "result": true,									
  "messageID": "bf290f74-14da-400c-bee6-f05f1ecb5434",									
  "code": 0,									
  "data": { "message": "success" }									
}

Sale, 3D Secure Confirm Diagram

Fund Authorisation process
The Sale and 3D Secure Confirm diagram above shows the process flow for integrating directly with the ABPAY API. This diagram illustrates the sequence of events required to integrate the payment process into a Merchant Site.

Step 1, the details entered by a potential customer in the payment page form on the merchant site is collected and sent to our service via the 'Sale' API call. So in step 1 the customer's payment details are assembled in JSON format and this data is sent to the API by using the HTTP POST method. All requests to the API must be executed using the POST method while ensuring the URL sent is encoded.

Step 2, the `Sale` API will respond back to the merchant site which will include an error code and description, the response may also include other data depending if the provided card is 3D Secure or not. If the entered card is not 3D Secure and the request is successful, the response may include 0 as the error code for Confirmation Received. If the entered card is 3D Secure and the sale request is successful, the response will be 01 as the error code. The following fields in data field will also be made available:

- ACSURL will be included in the R3 field which is used to redirect the customer to the 3D Secure service.
- PAReq which contains the encoded authentication request and is included in the R4 field which is automatically submitted to the 3D Secure service.
- PARes is included in the R5 field which is the reply received from the Issuing Bank after the card holder has been authenticated.

Step 3, the information in the `Sale` Response (step 2) will be used to construct a HTML form with data that will be POSTED to the authentication site. When the authentication site is loaded it requires the customer to provide an extra piece of information to validate themselves. The current method is 3D Secure and requires the customer to enter in a short password. Depending on the card type entered by the customer on the payment page the corresponding authentication will be provided by 'Verified by VISA' or 'MasterCard SecureCode'.

The customer enters the required password and hits submit. This is then processed by the service and when a response is received the customer is returned to the merchant site. The landing page where the customer returns on the merchant site is predetermined by a URL field in the form sent to the authenticator. This page is known as the Term URL (Termination Page).

Step 4, the payment authentication response is sent back to the merchant site. It is the Term URL page that receives the PARes payload.

Step 5, the PARes value returned from the authenticator is now passed onwards to the 'Confirm' API call which confirms the 3D Secure. The PARes is an alpha-numeric string that averages over 3000 characters in length. Included in this POST to the API are the transaction code that was sent in the initial `Sale` request.

Step 6, JSON response of step 5 is received at the Term URL page, this data will include an error code and description like the previous response. If successful, the response may include 0 as the error code for Confirmation Received.
Any other error code represents an error state, please see API Responses for more information regarding responses.

*Step 7, if the merchants setup for send notifications, the results of the completed transaction are sent to the notification URL. The notification URL is one of the form fields in the initial Sale call to the API. The merchant should set up this notification page to read nd parse the JSON data received from the API. This data includes the results of AVS/CV2 checks, 3D Secure checks and confirmation types. Please see Notification Methods for more information.