Developers Section

This documents the process of integrating Amplify into your existing platform.

Getting started with the API

With the Amplify APIs, you can accept recurring payments, charge one-time payments, verify all transaction responses, create subscription plans and charge a returning customer without having them re-enter their card details again. This documentation takes you through the process of integrating Amplify into your existing platform.


Create Subscription Plans

You can create subcription plans and tie your customers to them via the API. These customers will be billed on a regular interval based on the frequency you set.

Charge Your Customers

Charge your customers from their Credit/Debit cards anywhere in the world or directly from their Nigerian bank account. We accept Visa, Mastercard, Verve and Amex.

Verify Transactions

The API also allows you to spool and/or verify all your customers transactions anytime anyday. Its simple, secure and fast.

All transaction executed via the API is immediately reflected in your Dashboard in realtime.

You can view your transaction history, create recurring plans, view your cutomer details/geolocation, get financial analytics/reports and lots more via your Merchant Dashboard.



Test Details

Use the card and account details below to perform test transactions. You can use your Access Bank account number or your credit/debit Visa, Verve, Mastercard or Amex once you migrate to Live.


PAN = 5060 9905 8000 0217 499
EXPYEAR = 20
EXPMONTH = 04
CVV = 111

If prompted for Amount Validation, Enter 1.10
BANK = Access Bank
ACCT NUM = 0690000000
OTP = 12345
If prompted for OTP, Enter 12345

Initializing the payment gateway - With redirects


If you wish to accept either one-time or recurring payments, the first point of call is to initiate the payment gateway.
The payment gateway page is served via a PCIDSS compliant service provider hosted on a different server.


API Endpoint: https://api.amplifypay.com/merchant/transact
Content Type: application/json
Method: POST

Example Post Request

Note: the parameter names are case sensitive
POST /merchant/transact HTTP/1.1
Host: api.amplifypay.com
Content-Type: application/json
Cache-Control: no-cache

{
"merchantId" : "xxxxxxxxxxxxxx",
"apiKey" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"transID" : "2468563223",
"customerEmail" : "test@tester.com",
"customerName" : "Mr Tester",
"Amount" : "100.00",
"redirectUrl" : "http://domain.com/test",
"paymentDescription" : "Testing The API",
"planId" : "200"
}

Response

Only HTTP Status 200 indicates a successful response
{
"ApiKey" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"StatusCode" : "000",
"StatusDesc" : "Successful Request",
"TransID" : "2468563223",
"TransactionRef" : "1234567890",
"AuthToken" : "xxxxxx",
"PaymentUrl" : "https://amplifypay.com/gateway/xxx",
}

If the Post Request was successful, a json response is received which contains the AuthToken and PaymentUrl.
Redirect to the PaymentUrl to render the secure payment gateway. Note: if you configured a third party gateway, you will be redirected to the secure page of that gateway.

The PaymentUrl is valid for only one transaction cycle. Perform another Post Request to initiate another transaction. Browsing or redirecting to the PaymentUrl will render the secure payment gateway for collecting card details.

After a payment is completed, the transaction reference is sent as a Get parameter to the "redirectUrl" using the parameter name "tran_response". e.g https://merchant_site/response?tran_response={trnref}

With the reference, you should verify the status of the transaction before rendering service. See Transaction Verification



Initializing the payment gateway - Without redirects


The "No Redirect" API makes it very easy for developers to get started. With this feature, you can just "plug and play" the gateway.
Note: The "No Redirect" API is built with pure javascript and does not require Jquery or any other Js framework.


Usage

Note: the parameter names are case sensitive

The callback function onSuccess is optional. This function is initiated with an object parameter which has transaction reference once a payment is completed.

If no callback function is defined, the transaction reference is sent as a Get parameter to the "redirectUrl" using the parameter name "tran_response". e.g http://testdomain.com/response?tran_response={trnref}

Note that the redirectUrl is required but will not be used if a callback function is defined.

With the reference, you should verify the status of the transaction before rendering service. See Transaction Verification



Charge a returning customer

Once a customer has performed at a successful transaction before, you can charge the customer again without them having re-enter their card details every time.

This feature is Deactivated by default and is subject to our Terms and Conditions upon request for activation.
Go to API Settings -> Enable Cardless for more details.

API Endpoint: https://api.amplifypay.com/merchant/returning/charge
Content Type: application/json
Method: POST

Example Post Request

{
"merchantId" : "xxxxxxxxxxxxxx",
"apiKey" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"transactionRef" : "12345",
"authCode": "567890 A",
"Amount": "100.0000",
"paymentDescription": "Charge return customer",
"customerEmail": "test@tester.com"
}

Response

The transactionRef && authCode are curled from a succesfull transaction previously done by the Customer.

Verifying transactions

After the Customer has completed a transaction, it is important that you verify the status of that transaction before rendering service.


API Endpoint: https://api.amplifypay.com/merchant/verify
Content Type: application/json
Method: POST / Get

Example Post/Get Request

POST /merchant/verify HTTP/1.1
Host: api.amplifypay.com
Content-Type: application/json
Cache-Control: no-cache

{
"merchantId" : "xxxxxxxxxxxxxx",
"apiKey" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"transactionRef" : "12345",
}

GET /merchant/verify?transactionRef=xxxxxxxxx&merchantId=xxxxxxxxx HTTP/1.1
Host: api.amplifypay.com
Cache-Control: no-cache
If the Post/Get Request was sent successfully, a response with details of the specified transactionRef is returned. Error Codes Section for more details on possible errors.

Verification Response

Only HTTP Status 200 indicates a successful response
{
"ApiKey": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"TransID" : "2468563223",
"StatusCode": "001",
"StatusDesc": "Approved",
"OrderStatus": "APPROVED",
"TransactionRef": "12345",
"Amount": "100.0000",
"CardNumber": "412345XXXX1234",
"CardType": "VISA",
"AuthCode": "567890 A",
"Currency": "Naira",
"TranDate": "01/01/2013 15:20:18",
"CustomerName": "Mr Tester",
"CustomerEmail": "test@tester.com"
"Plan": {
"PlanId": "200",
"PlanName": "Gold Subscribers",
"Frequency": "2 Day",
"FrequencyDesc": "Occurs Every 2 Days",
"NextDueDate": "2013-01-03"
}
}
IT IS AN IMPORTANT PRACTICE TO ALWAYS VERIFY THE RETURNED APIKEY AGAINST YOURS.
The Plan parameter is only available if the verified transaction is a recurring/subscription payment.

Create Subscription Plans

You can create subscription plans via the API or dashboard. This section gives an overview of both. The Id of the created plans are referenced in the request used to initialize the gateway.


Via the API

API Endpoint: https://api.amplifypay.com/merchant/plan
Content Type: application/json
Method: POST

Example Post/Get Request

POST /merchant/plan HTTP/1.1
Host: api.amplifypay.com
Content-Type: application/json
Cache-Control: no-cache

{
"merchantId" : "xxxxxxxxxxxxxx",
"apiKey" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"planName" : "Silver Members",
"frequency" : "Weekly | Monthly | Three_Months | Six_Months | Annually | Custom",
"param" :
{
"customNum": "[2 - 12]",
"customDay": "Week | Day | Month"
}
}

Response

The frequency is either of "Weekly | Monthly | Three_Months | Six_Months | Annually | Custom".
param is optional only when frequency is not Custom. If frequency is custom then you must specify values for customNum and customDay.
e.g if you want the plan to recur every 5 days
"param" :
{
"customNum": 5,
"customDay": "Day"
}


Via the Dashboard

You can also create subscription plans on your dashboard and reference the PlanId when making a request via the API.



Update a subscription plan

After a plan has been created, you can view and modify details of that plan on your dashboard. If you want to control that experience you can also modify details of a subscription plan via the API

API Endpoint: https://api.amplifypay.com/merchant/plan/?PlanId={planid}
Content Type: application/json
Method: PUT

Request

PUT /merchant/plan?PlanId=123 HTTP/1.1
Host: api.amplifypay.com
Content-Type: application/json
Cache-Control: no-cache

{
"merchantId" : "xxxxxxxxxxxxxx",
"apiKey" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"planName" : "Silver Members",
"frequency" : "Weekly | Monthly | Three_Months | Six_Months | Annually | Custom",
"param" :
{
"customNum": "[2 - 12]",
"customDay": "Week | Day | Month"
}
}

Response

[
{
"PlanId" : 1234,
"PlanName" : "Silver Membership",
"Frequency": "Custom"
"Params":
{
"CustomNum" : 5,
"CustomDay" : "Day"
}, "DateCreated" : "xx-xx-xxxx",
}

...

]

Delete a subscription plan

The API also gives you the control to delete a subscription plan. Once a plan is deleted, all customers tied to that plan will be unsubscribed.

API Endpoint: https://api.amplifypay.com/merchant/plan
Content Type: application/x-www-form-urlencoded
Method: DELETE

Request

DELETE /merchant/plan/?PlanId=123&merchantId=xxxxx&apiKey=xxxxx-xxxxx HTTP/1.1 Host: api.amplifypay.com Cache-Control: no-cache

Response

SAME AS ABOVE


Fetch subscription plans

Get details of one/all subscription plans.

API Endpoint: https://api.amplifypay.com//merchant/plan
Content Type: application/x-www-form-urlencoded
Method: Get

Request

GET /merchant/plan/?PlanId=123 HTTP/1.1 Host: api.amplifypay.com Cache-Control: no-cache
GET /merchant/plan/?merchantId=xxxxxx&apiKey=xxxxxx-xxxx-xx HTTP/1.1 Host: api.amplifypay.com Cache-Control: no-cache

Response

[
{
"PlanId" : 1234,
"PlanName" : "Silver Membership",
"Frequency": "Custom"
"Params":
{
"CustomNum" : 5,
"CustomDay" : "Day"
}, "DateCreated" : "xx-xx-xxxx",
}

...

]

The json response is an array with details of all or one subscription plan as per requested.


Unsubscribe a customer from plan

You can unsubscribe a customer from any plan they had previously subscribed to by consuming the Endpoint below. Note that this can also be done via your dashboard.

API Endpoint: https://api.amplifypay.com/merchant/subscription/cancel
Content Type: application/json
Method: POST

Post Request

{
"merchantId" : "xxxxxxxxxxxxxx",
"apiKey" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"transactionRef" : "12345",
"customerEmail": "test@tester.com",
"planId": "200",
}

Response

{
"apiKey" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
"StatusCode" : "000",
"StatusDesc": "Successfull Request"
}

You can only unsubscribe one customer at a time via this API. You can disable a plan or remove every one on that plan via the dashboard. Support for unsubscribing multiple merchant via the API is underway.


Reference for the request parameters


The following is an explanation of all the request parameters that you will send.

merchantId (Required) Your account authentication Id
apiKey (Required) Your API authentication key
customerEmail The email address of the customer being charged.
Validation: Must be a valid email address
Amount The amount to be charged (specify the exact amount)
Validation: Numeric (Integer or Decimal)
redirectUrl The url to return merchants to after a transaction is completed.
Validation: Must be a valid web url address
customerName The full name of the customer being charged.
Validation: Alphanumeric Charaters with whitespaces (2 - 50)
paymentDescription The description of the service being charged for.
Validation: Alphanumeric Charaters with whitespaces (0 - 200)
planId This is the ID of your pre-created subscription plan. Reference this ID when you want to initiate a recurring transaction. You can create a subscription plan via the API or your dashboard.
Validation: Numeric (Integer)
transactionRef This is the unique reference number for a previous transaction. This is required in requests like charging a returning customer.
authCode This is the Authorization/Approval code for a previously successful transaction. This parameter is required in certain cases like charging a returning customer.


API Error Responses

When a request fails, it could be attributed to a couple of reasons. When this happens the API sends back the error message in the body of the response

NOTE THAT ONLY HTTP STATUS CODE 200 INDICATES A SUCCESSFUL RESPONSE.

Error Codes

401 Unauthorized Invalid Merchant id or API key, Deactivated Merchant Account
404 Not Found No Such Transaction Exists, Query Result was Empty
400 BadRequest Maximum Amount Exceeded, Invalid Plan Referenced, Invalid Request Detected
500 Server/Application Error

Plug-In Our Plugins, Fast and Easy!

We have a wide range of plug-and-play plugins - Woocommerce, Drupal, WHMCS, Opencart and Magento.

Our plugins and APIs are easy to integrate. You can explore our set of plugins below.
With plugins, integration can be done within minutes.


Magento

Integrate with Magento. Magento Plugin

OpenCart

Integrate with OpenCart. OpenCart v1 Plugin

OpenCart v2

Integrate with OpenCart v2. OpenCart v2 Plugin

WHMCS

Integrate with WHMCS. WHMCS Plugin

OpenCart v2 mod

Integrate with OpenCart v2 mod. OpenCart v2 mod Plugin

WooCommerce

Integrate with WooCommerce. WooCommerce Plugin

Uber Cart

Integrate with Uber Cart. UC Plugin

PrestaShop

Integrate with PrestaShop. PrestaShop Plugin