The Paga Developer Documentation

Welcome to the Paga API documentation. Our APIs and libraries are written to help you integrate payment in your products in matter of minutes. We have step by step guides to enable you get started.

Get Started    

Collect API Operations

HTTP Basic Authentication

For the requests, you will need to supply authentication credentials, using the HTTP Basic authentication (HTTP basic authentication requires an encoded HTTP header). The authentication credentials are your public key and secret key. Almost all web frameworks will provide a mechanism for supplying HTTP basic authentication credentials per the standard HTTP basic authentication header. See the following articles below for more information

HTTP Basic Authentication (Wikipedia)
HTTP Authentication: Basic and Digest Access Authentication (Specification)


📘

Test Base URL: https://beta-collect.paga.com/
Live Base URL: https://collect.paga.com/

1. Request Payment

Register a new request for payment between a payer and a payee. Once a payment request is initiated successfully, the payer is notified by the platform (this can be suppressed) and can proceed to authorize/execute the payment. Once the payment is fulfilled, a notification is sent to the supplied callback URL. See the callback notification section for more details.


Request Parameter

Argument

Type

Description

Required (Yes/No)

referenceNumber

String

A unique reference number representing this request. The same reference number will be returned in the response and can be used to query the payment request status

Yes

amount

Number

The amount being requested

Yes

currency

String

The currency of the operation, only required if being executed in a foreign currency.

Yes

payer

Object

The person/entity from whom we are requesting a payment

Yes

payer.name

String

Name of the payer.

Yes

payer.phoneNumber

String

Phone number of the payer. Either one of phone-number or e-mail address must be provided

No

payer.email

String

E-mail address of the payer. Either one of phone-number or e-mail address must be provided

No

payer.bankId

String

PublicId/PublicKey representing the payer’s bank. This is used for filtering payment option configuration presented to the payer. Available from the getBanks request.

No

payee

Object

The person/entity to receive the payment, if the payee identifier (eg. phone number, email, etc.) is not supplied, the payment request processor is automatically selected as recipient

Yes

payee.name

String

Name of the recipient
It would be important to note that the name that shows up for the Payer (eg. when doing a name enquiry at a bank), is what you provide in the payee.name parameter by default.

Yes

payee.accountNumber

String

The recipient’s Paga account number (NUBAN) for receiving payments

No

payee.phoneNumber

String

The recipient’s registered phone-number on Paga. Either is value of the account number (NUBAN) must be provided for processing payment into a paga account.

No

payee.bankId

String

PublicId/PublicKey representing the recipient’s bank (if not Paga). Must be provided for non-paga recipient.

No

payee.bankAccountNumber

String

For payments to traditional bank accounts. On fulfilment, processed funds will be paid into this account. Must be provided for non-paga recipient.

No

payee.financialIdentificationNumber

String

Bank Verification Number (BVN) of the recipient

No

expiryDateTimeUTC

String

Time limit for the payment request to be fulfilled otherwise it will be automatically expired, this must be with one week of requesting payment. If not provided the default expiry window value is applied.

No

isSuppressMessages

Boolean

Suppress direct messaging to payer and recipient. Default value is false

Yes

payerCollectionFeeShare

Number

This represents the percentage of the payment request fee that will be charged to the payer. The combination of payerCollectionFeeShare and recipientCollectionFeeShare must be less than 1.0

Yes

payeeCollectionFeeShare

Number

This represents the percentage of the payment request fee that will be charged to the payee. The combination of payerCollectionFeeShare and payeeCollectionFeeShare must be less than 1.0

Yes

isAllowPartialPayments

Boolean

Boolean flag indicating whether or not to accept partial payments for the payment request. Default value is false

No

callBackUrl

String

The callback url that will be notified with updates on the payment request status

Yes

paymentMethods

Array

List of permitted payment methods for processing this request. Available options are listed in the payment methods section

Yes

displayBankDetailToPayer

Boolean

This displays the bank details of the payer (bank name and account number) in addition to the payee.name to the payee.

No

Sample Request and Response

POST /paymentRequest HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + currency + payer.phoneNumber + payer.email + payee.accountNumber + payee.phoneNumber + payee.bankId + payee.bankAccountNumber + hashkey)

{
  "referenceNumber" : "2353464564565",
  "amount" : 2000.0,
  "currency" : "NGN",
  "payer" : {
    "name" : "Payer One",
    "phoneNumber" : "08011111111",
    "email" : "[email protected]",
    "bankId" : "40090E2F-7446-4217-9345-7BBAB7043C4C"
  },
  "payee" : {
    "name" : "Recipient One",
    "accountNumber" : "3233737367",
    "phoneNumber" : "08022222222",
    "bankId" : "40090E2F-7446-4217-9345-7BBAB7043C4C",
    "bankAccountNumber" : "0000000000",
    "financialIdentificationNumber" : "03595843212"
  },
  "expiryDateTimeUTC" : "2021-04-15T00:00:00",
  "isSuppressMessages" : false,
  "payerCollectionFeeShare" : 1.0,
  "payeeCollectionFeeShare" : 0.0,
  "isAllowPartialPayments" : false,
  "callBackUrl" : "http://localhost:9091/test-callback",
  "paymentMethods" : ["BANK_TRANSFER","USSD"]
}
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 277

{
  "referenceNumber" : "2353464564565",
  "statusCode" : "0",
  "statusMessage" : null,
  "paymentMethods" : [ {
    "name" : "BANK_TRANSFER",
    "properties" : {
      "paymentCode" : "12345678"
    }
  } ],
  "expiryDateTimeUTC" : null,
  "payerPagaAccountHolder" : false
}

Response Parameter

Argument

Type

Description

referenceNumber

String

The reference number that was provided in the request

statusCode

String

The status of the operation. See Status Codes section for details

statusMessage

String

A human readable status message

paymentMethods

Array

Details of available payment methods for this request

paymentMethods.[].name

String

The name of the payment method

paymentMethods.[].properties

Object

The additional properties for the payment method

paymentMethods.[].properties.paymentCode

String

Payment code for the specified payment method

expiryDateTimeUTC

Null

The array of account information items for this account (if requested)

payerPagaAccountHolder

Boolean

Boolean flag to indicate whether or not the payment was fulfilled from a paga account


2. Create Persistent Account Number

An operation for business to create Persistent Payment Account Numbers that can be assigned to their customers for payment collection. These account numbers belong to the organization and are assigned to their customers to make payments anytime via Bank or Paga transfers.

Service Method: registerPersistentPaymentAccount


Request Parameters

Parameter

Type

Description

Required?

referenceNumber

String

A unique reference number for this request.
This same reference number will be returned in the response.

Yes

phoneNumber

String

The phone number of the customer.

Yes

accountName

String

The acountname of the customer.

Yes

firstName

String

The first name of the customer

Yes

lastName

String

The last name of the customer

Yes

financialIdentificationNumber

String

The customer's Bank verification Number (BVN)

Yes

email

String

The email of your customer.

Yes

accountReference

String

This is a unique reference number provided by the Organization which identifies the persistent account Number. It should have a minimum length of 12 characters and a maximum length of 30 characters

Yes

creditBankId

String

If included, this is the public Id of the bank that you want deposits to be transferred directly to fo every payment. You can get bank IDs HERE

Optional

creditBankAccountNumber

String

This must be provided if creditBankId is included in the request payload. It is the bank account number of the bank that you want deposits to be transferred to. This must be a valid account number for the bank specified by creditBankId

Optional

callbackUrl

String

A custom callback URL for the payment webhook notifications for this specific account to be sent to. If provided, requests are sent to this URL exactly as provided. This allows you to set custom query parameters to the URL which you will be provided during webhook notifications for this specific account.

Optional

Sample Request and Response

URL: https://collect.paga.com/registerPersistentPaymentAccount
Content-Type: application/json
Accept: application/json
Authorization: "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + accountReference + financialIdentificationNumber + creditBankId + creditBankAccountNumber + callbackUrl + hashKey)

Request Body:
  {
    "referenceNumber":"0053459875439143453000",
    "phoneNumber":"08048276159",
    "firstName":"Bellview",
    "lastName": "Walker",
    "accountName": "Bellview Walker",
    "financialIdentificationNumber": "12345454326",
    "accountReference": "123467891334",
    "creditBankId": "3E94C4BC-6F9A-442F-8F1A-8214478D5D86",
    "creditBankAccountNumber":"0000000000",
    "callbackUrl":"http://localhost:9091/test-callback"
  }
{
    "referenceNumber": "test12345100",
    "statusCode": "0",
    "statusMessage": "success",
    "accountReference": "2222222222222023",
    "accountNumber": "1725110000"
}

Response Parameters

Parameter

Type

Description

referenceNumber

String

The same unique reference number provided in the request

statusCode

Number

Status code of the response. 0 indicates a successful response

statusMessage

String

Human-readable description about of response. 'Success'for a successful response

accountNumber

String

The persistent payment account number for your customer

accountReference

String

This is a unique reference number provided by the Organization which is sent in the original request


3. Status

Query the status of a submitted request. The endpoint takes a reference number and will return the status of the operation with that reference number, which could be a persistent payment account creation operation or a payment request.

Request Parameter

Argument

Type

Required (Yes/No)

Description

referenceNumber

String

A unique reference number representing the operation that is being queried

Yes

Sample Request and Response

POST /status HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)

{
  "referenceNumber" : "12345",
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "referenceNumber" : "2353464564565",
  "statusCode" : "0",
  "statusMessage" : null,
  "paymentMethods" : [ {
    "name" : "BANK_TRANSFER",
    "properties" : {
      "paymentCode" : "12345678"
    }
  } ],
  "expiryDateTimeUTC" : null,
  "payerPagaAccountHolder" : false
}

Response Parameter

Argument

Type

Description

referenceNumber

String

The reference number that was provided in the request

statusCode

String

The status of the operation. See Status Codes section for details

statusMessage

String

A human readable status message

paymentMethods

Array

Details of available payment methods for this request

paymentMethods.[].name

String

The name of the payment method

paymentMethods.[].properties

Object

The additional properties for the payment method

paymentMethods.[].properties.paymentCode

String

Payment code for the specified payment method

expiryDateTimeUTC

Date

The array of account information items for this account (if requested)

payerPagaAccountHolder

Boolean

Boolean flag to indicate whether or not the payment was fulfilled from a paga account


4. History

Get history of all activities for a period between to give start and end dates. The period window should not exceed 1 month.

For persistent payment accounts - /history the referenceNumber parameter is optional, but if provided, it can be: a request referenceNumber, a persistent payment account accountReference or a persistent payment account accountNumber.
If referenceNumber parameter is NOT provided, it will just return all operations in the given time frame (both persistent payment account and payment request operations), including payments to those accounts
If referenceNumber parameter IS provided
— if the referenceNumber is the actual referenceNumber parameter provided for a /registerPersistentPaymentAccount request, then it will just return the single operation tied to that reference if it is in the selected date range.
— if the referenceNumber is the accountReference or accountNumber of a persistent payment account then it will just return the operations (registration and payments) for that persistent payment account in the selected date range

Request Parameter

Argument

Type

Description

Required (Yes/No)

referenceNumber

String

A unique reference number representing a request. If provided, it will restrict results to only those tied to the request with that specific reference number

No

startDateTimeUTC

String

A timestamp representing the start of the transaction history request. Range must be less than or equal to 3 months

Yes

endDateTimeUTC

String

A timestamp representing the end of the transaction history request. Range must be less than or equal to 3 months

No

Sample Request and Response

POST /history HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)

{
  "referenceNumber" : "12345",
  "startDateTimeUTC" : "2021-01-13T19:15:22",
  "endDateTimeUTC" : "2021-04-13T19:15:22"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "statusCode": "0",
    "statusMessage": "success",
    "itemCount": 5,
    "items": [       
        {
            "datetime": "2021-09-04T15:51:01.417",
            "referenceNumber": "235346458804",
            "accountNumber": "0515545692",
            "accountReference": null,
            "operation": "PAYMENT_REQUEST",
            "action": "CREATE_REQUEST",
            "amount": 7048.38,
            "status": "SUCCESSFUL"
        },
        {
            "datetime": "2021-09-08T12:26:57.147",
            "referenceNumber": "2340235987988000",
            "accountNumber": "0301657073",
            "accountReference": "000000000014",
            "operation": "PERSISTENT_PAYMENT_ACCOUNT",
            "action": "CREATE",
            "amount": 0.0,
            "status": "SUCCESSFUL"
        },
        {
            "datetime": "2021-09-08T12:29:16.25",
            "referenceNumber": "2340235987988002",
            "accountNumber": "0301657073",
            "accountReference": "000000000014",
            "operation": "PERSISTENT_PAYMENT_ACCOUNT",
            "action": "UPDATE",
            "amount": 0.0,
            "status": "SUCCESSFUL"
        },
        {
            "datetime": "2021-09-08T12:29:35.817",
            "referenceNumber": "2340235987988003",
            "accountNumber": "0301657073",
            "accountReference": "000000000014",
            "operation": "PERSISTENT_PAYMENT_ACCOUNT",
            "action": "DELETE",
            "amount": 0.0,
            "status": "SUCCESSFUL"
        },
        {
            "datetime": "2021-09-08T13:15:20.053",
            "referenceNumber": "2340235987998000",
            "accountNumber": "2806605308",
            "accountReference": "000000000039",
            "operation": "PERSISTENT_PAYMENT_ACCOUNT",
            "action": "CREATE",
            "amount": 0.0,
            "status": "SUCCESSFUL"
        }
    ]
}

Response Parameter

Argument

Type

Description

statusCode

String

The status of the operation. See Status Codes section for details

statusMessage

String

A human readable status message

itemCount

Integer

The number of actions carried out within in the specified start and end date

items

Array

An array representing all actions carried out within the time window

items[].datatime

String

Timestamp in UTC indicating when the payment request action was perform

items[].referenceNumber

String

The reference number that was provided in the request

items[].operation

String

The operation performed, a category of operation perfomed. See list of different operations here

items[].action

String

The action performed, a subcategory of operation. see list of actions here

items[].amount

Double

The amount requested or paid depending of the action carried out.

items.[].status

String

Status of the action performed. See documentation on different statuses


5. Get Banks

Retrieve a list of supported banks and their complementary unique ids on the bank. This is required for populating the payer (optional) and payee objects in the payment request model.

Request Parameter

Argument

Type

Description

Required (Yes/No)

referenceNumber

String

A unique reference number representing this request. The same reference number will be returned in the response.

Yes

Sample Request

POST /banks HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)

{
  "referenceNumber" : "12345"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "referenceNumber" : "12345",
  "statusCode" : "0",
  "statusMessage" : null,
  "banks" : [ {
    "name" : "GT Bank",
    "uuid" : "3E94C4BC-6F9A-442F-8F1A-8214478D5D86"
  }, {
    "name" : "Access Bank",
    "uuid" : "F8F3EFBF-67CB-4C17-A079-B7CFE95F71BE"
  } ]
}

Response Parameter

Argument

Type

Description

Required (Yes/No)

referenceNumber

String

The reference number that was provided in the request

statusCode

String

The status of the operation. See Status Codes section for details

statusMessage

String

A human readable status message

banks

Array

An array representing all payment requests from processor within the time window

banks.[].uuid

String

An id uniquely identifying a Bank on Paga

banks.[].name

String

Display name of the identifying bank


5. Payment Request Refund

This end-point can be used to either cancel or initiate a refund if we were unable to fulfill the request for one reason or the other. Do note that refund requests for successfully completed payment requests will be honoured.

❗️

Please Note

Refund on Persistent payment account is only available for NIP transfers for now.

Request Parameter

Argument

Type

Description

Required (Yes/No)

referenceNumber

String

The unique reference number representing the payment request to be refunded.

Yes

refundAmount

Number

Amount to be refunded

Yes

currency

String

The currency of the operation.

Yes

reason

String

Reason for the refund request

No

Sample Request and Sample Response

POST /refund HTTP/1.1
Content-Type: application/json
Accept: application/json
principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of developer)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + refundAmount + hashkey)

{
  "referenceNumber" : "12345",
  "refundAmount" : 1000.0,
  "currency" : "NGN",
  "reason" : "no particular reason"
}
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 181

{
  "referenceNumber" : "12345",
  "statusCode" : "0",
  "statusMessage" : "success",
  "refundAmount" : 1000.0,
  "currency" : "NGN",
  "refundDestination" : "Paga | 00012346433"
}

6. Delete Persistent Payment Account

This endpoint allows for deleting a persistent payment account.

Request Parameter

Argument

Type

Description

Required

referenceNumber

String

The unique reference number representing the delete persistent payment account request.

Yes

accountIdentifier

String

The accountIdentifier can be either the NUBAN or the accountReference the customer provided when creating the account

Yes

reason

String

Reason for deleting the account

No

Sample Request and Response

POST /deletePersistentPaymentAccount HTTP/1.1
Content-Type: application/json
Accept: application/json
principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of developer)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + accountIdentifier + hashkey)
{
  "referenceNumber":"23402359879879997",
  "accountIdentifier":"0830202843",
  "reason":"off-boarded account"
 }
{
    "referenceNumber": "23402359879879997",
    "statusCode": "0",
    "statusMessage": "success"
}

Argument

Type

Description

referenceNumber

String

The same unique reference number provided in the request

statusCode

String

Status code of the response. 0 indicates a successful response

statusMessage

String

The status of the request, this should just be an
acknowledgement that the request was received.

❗️

CAUTION

This operation cannot be reversed!

7. Update Persistent Payment Account

This endpoint allows for changing any of the account properties except the accountNumber (NUBAN) and the accounReference properties which cannot be changed.
Parameters (account properties) other than referenceNumber and accountIdentifier are optional. Any property provided will be updated. Omitted properties will remain as they were.
The accountIdentifier can be either the NUBAN or the accountReference they provided when creating the account.

Request Parameter

Argument

Type

Description

Required (Yes/No)

referenceNumber

String

The unique reference number representing the update persistent payment account request.

Yes

accountIdentifier

String

The accountIdentifier can be either the NUBAN or the accountReference that was provided when creating the persistent payment account

Yes

phoneNumber

String

The customer's Bank verification Number (BVN)

No

firstName

String

The first name of the customer

No

lastName

String

The last name of the customer

No

accountName

String

The acountname of the customer.

No

financialIdentificationNumber

String

The customer's Bank verification Number (BVN)

No

callbackUrl

String

A custom callback URL for the payment webhook notifications for this specific account to be sent to. If provided, requests are sent to this URL exactly as provided. This allows you to set custom query parameters to the URL which you will be provided during webhook notifications for this specific account.

No

creditBankId

String

If included, this is the public Id of the bank that you want deposits to be transferred directly to fo every payment. You can get bank IDs HERE

No

creditBankAccountNumber

String

This must be provided if creditBankId is included in the request payload. It is the bank account number of the bank that you want deposits to be transferred to. This must be a valid account number for the bank specified by creditBankId

No


Argument

Type

Description

referenceNumber

String

The same unique reference number provided in the request

statusCode

String

Status code of the response. 0 indicates a successful response

statusMessage

String

The status of the request, this should just be an
acknowledgement that the request was received.

Sample Request and Response

POST /updatePersistentPaymentAccount HTTP/1.1
Content-Type: application/json
Accept: application/json
principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of developer)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + accountIdentifier + financialIdentificationNumber + creditBankId + creditBankAccountNumber + callbackUrl + hashkey)

{
  "referenceNumber":"23402359879879996",
  "accountIdentifier":"0830202843",
  "phoneNumber":"0910220042",
  "firstName":"Renamed",
  "lastName": "Customer",
  "accountName": "Renamed Customer",
  "financialIdentificationNumber": "12345454666",
  "callbackUrl": "http://77d761893689.ngrok.io/persistent/000000000009/Password6",
  "creditBankId":"40090E2F-7446-4217-9345-7BBAB7043C4C",
  "creditBankAccountNumber":"0000000031"
 }
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 181
{
    "referenceNumber": "23402359879879996",
    "statusCode": "0",
    "statusMessage": "success"
}

8. Payment Request Callback notifications

Call back notifications are triggered when there is a change in the state of the payment request. Each notification will be retried a maximum of three retries until a 200 status response is received from the remote server or the retry limit is reached. The call back also includes the reference number for the original payment request. To retrieve the payment request status after the notification retry limit is reached, use the Collect API status end-point.

📘

Please take note.

The callback notification includes a hash parameter that is hashed using the pre-shared hash-key, so by verifying the hash, you can authenticate that the request came from us (as well as authenticating that the hashed parameters haven’t been tampered with).

Argument

Type

Description

notificationId

String

A unique reference number assigned to each notification request. Where a notification is not immediately acknowledged with a 200 status response, the notifcation is resent using the same unique identifier.

statusCode

String

The status of the operation. See Status Codes section for details

statusMessage

String

A human readable status message

externalReferenceNumber

String

The reference number that was provided for the payment request

fundingPaymentReference

String

The payment reference from the original transfer/payment (Only available for NIP transfers).

state

String

The current state of the payment request. See Payment Request State section for details of the possible states.

hash

String

The hash is formed as the SHA-512 hash. For example,
notificationId + statusCode + externalReferenceNumber + state + outstandingBalance + hashKey
It is important to note that the ‘outstandingBalance’ can be null in which case it is omitted, but if provided it is formatted with two decimal places and no commas (pattern: “#.00”).

{
  "notificationId" : "12345",
  "statusCode" : "0",
  "statusMessage" : "success",
  "externalReferenceNumber" : "1232123212323",
  "state" : "CONSUMED",
  "hash" : "d01b26a2106d481da6aef9c8c19cc56d56aa81e7352f42178f2711669bf715adb1ebe145c4bc4fff820c3786326d93b73dd61cc2b0f4432aae67434b57b55c03"
}

9. Get Persistent Payment Account

A method to query the properties associated with an existing persistent payment account.

Parameter

Type

Description

Required(Yes/No)

referenceNumber

String

The unique reference number representing the update persistent payment account request.

Yes

accountIdentifier

String

The accountIdentifier can be either the NUBAN or the accountReference the customer provided when creating the account

Yes

Sample Request and Response

POST /getPersistentPaymentAccount HTTP/1.1
Content-Type: application/json
Accept: application/json
principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of developer)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + accountIdentifier+ hashkey)

{
  "referenceNumber":"23402359879879997",
  "accountIdentifier":"2806605308"
 }
{
    "referenceNumber": "23402359879879997",
    "statusCode": "0",
    "statusMessage": "success",
    "accountReference": "000000000039",
    "accountNumber": "2806605308",
    "accountName": "Jermey Doe",
    "phoneNumber": "08163232123",
    "firstName": "Jermey",
    "lastName": "Doe",
    "financialIdentificationNumber": "12345454325",
    "creditBankId": "1",
    "creditBankAccountNumber": "0000000000",
    "callbackUrl": "http://www.example.com/persistent/000000000008/Password10"
}

Parameter

Type

Description

referenceNumber

String

The same unique reference number provided in the request

statusCode

String

Status code of the response. 0 indicates a successful response

statusMessage

String

A human readable status message.

accountReference

String

This is a unique reference number provided by the Organization which identifies the persistent account Number. It should have a minimum length of 12 characters and a maximum length of 30 characters.

accountName

String

The name of the customer
that made the transaction.

phoneNumber

String

The phone number of the customer.

firstName

String

The firstName of the customer.

lastName

String

The lastName of the customer

financialIdentificationNumber

String

The customer's Bank verification Number (BVN)

creditBankId

String

This is the public Id of the bank that was provided while creating the persistent payment account. You can check up creditBankIds HERE

creditBankAccountNumber

String

This would be provided if the creditBankId is included in the request payload. It is the bank account number of the bank that you want deposits to be transferred to. This must be a valid account number for the bank specified by creditBankId

callbackUrl

String

A custom callback URL for the payment webhook notifications for this specific account to be sent to.

10. Persistent Payment Account Callback Notification

This allows Paga to send to you deposit notifications that occur on a particular account. Execution of this service should trigger payment logic in your system and provide a response including success/fail result to Paga system.

📘

Please take note

The callback notification includes a hash parameter that is hashed using the pre-shared hash-key, so by verifying the hash, you can authenticate that the request came from us (as well as authenticating that the hashed parameters haven’t been tampered with).

Parameter

Type

Description

statusCode

Number

Status code of the response. 0 indicates a successful response

statusMessage

String

Human-readable description
about of response. 'Success'
for a successful response

accountNumber

String

The persistent payment
account number for your customer.

accountName

String

The name of the customer
that made the transaction

financialIdentificationNumber

String

The customer's Bank verification Number (BVN)

amount

String

The total amount of the transaction

clearingFeeAmount

String

The fee for receiving a payment into a persistent payment account

transferFeeAmount

String

The additional fee for transferring received payment to an external bank account

transferBankName

String

The name of the bank to transfer payment to

transferBankAccountNumber

String

The account number of the bank account to transfer payment to

transactionReference

String

The referenceNumber of the transaction

fundingPaymentReference

String

The payment reference from the original transfer/payment into the persistent payment account (Only available for NIP transfers).

hash

String

The hash is formed as the SHA-512 hash consisting of the following parameters:
statusCode + accountNumber + amount + clearingFeeAmount + transferFeeAmount + hashKey

Sample Request and Response

{
    "statusCode":"0",
    "statusMessage":"Successful",
    "accountNumber":"0209900232",
    "accountName":"John Doe",
    "financialIdentificationNumber":"0999999222222",
    "amount":"5000",
    "clearingFeeAmount":"50",
    "transferFeeAmount":"100",
    "transferBankName":"Access Bank",
    "transferBankAccountNumber":"3200012121",
    "transactionReference": "test0000000",
    "hash" : "qbe000fgad481mef9c8c9c00c5zz6d56aa81e7352f42178f2711669b15adb1ebe145c4bc4fff820c3786326d93b73dd61cc2b0f4432aae67434b57b55c03"
}
{
        "status":"SUCCESS",
}

Parameter

Type

Description

status

String

The status of the request, this should just be an
acknowledgement that the request was received.

Updated 25 minutes ago

Collect API Operations


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.