Checkout Payment Notification Guide
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 | 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. | Yes |
statusMessage | String | Human-readable description | 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 |
Updated 5 months ago