Skip to content

API document overview

Getting started

How to read the API Document?

GPayment's ActiveServer API documentation includes the allowed endpoints and the request HTTP method type for each API. For example, /api/v1/auth/3ri is the endpoint url and the allowed HTTP method is POST. api end points

If you want to check the details of the endpoints, click on one of the endpoint box's to open up its details. You will see something similar to the screenshot below. The screenshot explains how to read the API documentation. api end points

Authentication API

The Authentication API allows merchants and payment gateways to integrate the 3D Secure 2 flow into their eCommerce site. All Authentication APIs start from /api/v1/auth/... and follow RESTFul naming conventions. There are 3 main authentication flows available:

  • App-based - Authentication during a transaction on a Consumer Device that originates from an App provided by a registered agent (merchant, digital wallet, etc). For example, an eCommerce transaction originating during a checkout process within a merchant’s App on the Consumer Device.

  • Browser-based - Authentication during a transaction on a Consumer Device or Computer that originates from a website utilising a browser. For example, an eCommerce transaction originating during a checkout process within a website.

  • 3DS Requestor Initiated (3RI) - Confirmation of account information with no direct cardholder present. For example, a subscription-based eCommerce merchant confirming that an account is still valid.

Field Conditions

The following standards are used to identify the conditions of each field.

  • Required - Sender shall include the data element in the identified message; ActiveServer checks for data element presence and validates the data element contents.

  • Conditional - Sender shall include the data element in the identified message if the conditional inclusion requirements are met; ActiveServer checks for data element presence and validates data element contents. When no data is to be sent for a conditional data element, the data element should be absent.

  • Optional - Sender may include the data element in the identified message; ActiveServer validates the data element contents when present. When no data is to be sent for an optional data element, the data element should be absent.

The latest Authentication APIs are available from here.

API Authentication

All authentication API endpoints are secured by X.509 authentication which requires the client and server to be mutually authenticated. This is performed by using a client certificate issued by the ActiveServer.

  1. Make sure the instance is activated by following this guide.

  2. Download the client certificate for the Authentication API from the merchant page in the dashboard. This certificate is in .p12 format.

  3. Download the CA certificate chain from the user profile page. The CA certificate is in .pem format with the first certificate being the server CA, followed by GPayments Intermediate CA and finally the GPayments Root CA.

  4. You can follow the Integration guide to setup a 3DS requestor to call the authentication API with the client certificate.

Warning

You will not see the DOWNLOAD button if your instance is not activated.

Administration API

The Administration API is available to perform select administration tasks such as managing merchants. All Admin APIs start from /api/v1/admin/... and follow RESTFul naming conventions. For example, creating merchant which is described here, can be performed by the POST API endpoint /api/v1/admin/merchants.

The latest Administration APIs are available from here.

API Authentication

API Authentication is performed similar to the Authentication API with a client certificate.

  1. Make sure the instance is activated by following this guide.

  2. Download the client certificate for the Administration API from the user profile page in the administration interface. This certificate is in .p12 format.

  3. Download the CA certificate chain certificate from the same page. The CA certificate is in .pem format with the first certificate being the server CA, followed by GPayments Intermediate CA and finally the GPayments Root CA.

  4. Use the downloaded client certificate and CA bundle for API authentication by including it inside the HTTP client request. Please refer to the HTTP client you are using on how to do this or you can follow the API quick start for testing.

Admin API Certs

Admin API Quick Start

To try out the API using cURL, you need to convert the X.509 certificate to PEM format by using openssl and using the following curl command.

  1. Download and install openssl command line from https://www.openssl.org/.

  2. Download the client certificate and CA certificate following the Admin API Authorisation section above.

  3. Open up a terminal.

  4. Extract the private key from the .p12 file using the following command, entering the password when prompted:

    1
    openssl pkcs12 -in YOUR_P12_FILE_NAME.p12 -nocerts -out key.pem

  5. Extract the certificate from the .p12 file using the following command, entering the password when prompted:

    1
    openssl pkcs12 -in YOUR_P12_FILE_NAME.p12 -clcerts -nokeys -out crt.pem

  6. Perform the cURL request using your AS Admin API entry point. In this case we are getting a list of merchants from /api/v1/admin/merchants:

    1
    curl -k https://your.server.address:7443/api/v1/admin/merchants --cacert cacerts.pem --cert crt.pem -v --key key.pem

  7. You should see the following cURL response:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    < HTTP/1.1 200 OK
< Expires: 0
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< X-XSS-Protection: 1; mode=block
< Pragma: no-cache
< X-Frame-Options: DENY
< Date: Mon, 27 May 2019 09:51:59 GMT
< X-Total-Count: 1
< Connection: keep-alive
< X-Content-Type-Options: nosniff
< Strict-Transport-Security: max-age=31536000 ; includeSubDomains
< Transfer-Encoding: chunked
< Content-Type: application/json;charset=UTF-8
< Link: </api/v1/admin/merchants?page=0&size=20>; rel="last",</api/v1/admin/merchants?page=0&size=20>; rel="first"
< 
* Connection #0 to host your.server.adress left intact
[{"bins":"40001 (Test Acquirer)","merchantId":"123456789012345","name":"Test Merchant","status":"ENABLED","merId":"48f3b030-ed1d-4f7f-aa70-85cda288e0cb"}]%