Organizations integrating Paga-checkout have the option to create a notification API that we can call for notification purposes as described below. This enables Paga to process automated real-time transaction notifications with the organization's systems using secured RestFul Web Services. This specification describes the RestFul web-services that the organization must implement for automated real-time notification.

Paga has created a standard set of web-services for organizations to implement to enable
further integration for the persistent payment account Service. Implementing the API would
enable the organization to benefit from the following:

Paga to notify, in real-time, the organization of a successful checkout transaction.
Paga to notify, in real-time, the errors that occur during a checkout transaction

Hosting and Configuration

The organization may host their web-service on any publicly accessible URL which they will
share with Paga for configuration on the Paga platform.

Security

The organization's web-service must implement the following security features in order to help ensure secured communications between the Paga's platform and the organizations's systems. These security specifications are required for successful integration.

SSL : All communications between the Paga platform and the organization must be
performed over a secure sockets layer (SSL) HTTP communication channel. This means
that the organization must provide an encrypted SSL HTTP address (HTTPS URL).

Checkout Success Notification

This allows Paga to send to organization success notifications that occur on a checkout transaction.

Parameter	Type	Description	Required
statusCode	Number	Status code of the response. 0 indicates a successful response	Yes
statusMessage	String	Human-readable description about of response. 'Success' for a successful response	Yes
paymentReference	String	Unique reference number supplied by the Organization which identifies the checkout transaction	Yes
amount	Number	The total amount of the transaction	Yes
currency	String	The currency used in the successful transaction	Yes
timeStamp	Date	This is the date and time of the transaction	Yes
customerPhoneNumber	String	The customer's phone number which is supplied by the Organization	No
customerEmail	String	The customer's email which is supplied by the Organization	No
description	String	This is the description set by the Organization for the transaction	No
data-callback_url	String	The callback url that will be notified with updates on the payment carried via checkout	No

{
  Http Headers:
        Content-Type: application/json;
  
  Request Body:
    "statusCode": 0,
    "statusMessage": "success",
    "paymentReference": "Randm=1",
    "amount": 500,
    "currency": "NGN",
    "timeStamp": "2021-03-08T15:52:13.000Z",
    "description": "Gelly Giraffe",
    "customerEmail": "[email protected]",
        "customerPhoneNumber": "+23456788910"
}

Checkout Failed Notification

Parameter	Type	Description	Required?
statusCode	Number	Status code of the response. this indicates the type of error encountered	Yes
statusMessage	String	Human-readable description about of response. This indicates the error that occurred during the transaction	Yes
paymentReference	String	Unique reference number supplied by the Organization which identifies the checkout transaction	Yes
currency	String	The currency used in the transaction	Yes
timeStamp	Date	This is the date and time of the failed transaction	Yes
amount	Number	This indicates the total amount of the transaction	Yes
errorCategory	Error Category	This indicates the error category.	Yes

Error Category

Category	Description
USER_ERROR	This indicates a user error
SYSTEM_ERROR	This indicates a system error
RISK_ERROR	This indicates a fraud or risk error

{
        Http Headers:
        Content-Type: application/json;
  
    Request Body:
    "statusCode": 10102,
    "statusMessage": "Insufficient available balance in Paga Account.",
    "paymentReference": "Randm=1",
    "amount": 999999999,
    "currency": "NGN",
    "timeStamp": "2021-03-02T23:02:04.000Z",
    "errorCategory": "USER_ERROR",
}

Error Codes

Here is a list of possible error codes.

Status Code	Error Message	Error Category
0	Success	NULL
10102	Insufficient available balance in Paga Account.	USER_ERROR
10103	Invalid OTP code	USER_ERROR
10105	No Account with this number exists at the bank.	USER_ERROR
11101	An error occurred - Payment not processed.	SYSTEM_ERROR
11104	Payment not processed: Error processing card charge Transaction failed. Card processing error.	SYSTEM_ERROR
11107	NIBSS bank integration error. No bank sort code configured for organization.	SYSTEM_ERROR
12106	Maximum OTP attempts exceeded.	RISK_ERROR