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
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": "₦",
    "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

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