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/

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 authorise/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

ArgumentTypeDescriptionRequired (Yes/No)
referenceNumberStringA 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 statusYes
amountNumberThe amount being requestedYes
currencyStringThe currency of the operation, only required if being executed in a foreign currency.Yes
payerObjectThe person/entity from whom we are requesting a paymentYes
payer.nameStringName of the payer.Yes
payer.phoneNumberStringPhone number of the payer. Either one of phone-number or e-mail address must be providedNo
payer.emailStringE-mail address of the payer. Either one of phone-number or e-mail address must be providedNo
payer.bankIdStringPublicId/PublicKey representing the payer’s bank. This is used for filtering payment option configuration presented to the payer. Available from the getBanks request.No
payeeObjectThe 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 recipientYes
payee.nameStringName 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.accountNumberStringThe recipient’s Paga account number (NUBAN) for receiving paymentsNo
payee.phoneNumberStringThe 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.bankIdStringPublicId/PublicKey representing the recipient’s bank (if not Paga). Must be provided for non-paga recipient.No
payee.bankAccountNumberStringFor payments to traditional bank accounts. On fulfilment, processed funds will be paid into this account. Must be provided for non-paga recipient.No
payee.financialIdentificationNumberStringBank Verification Number (BVN) of the recipientNo
expiryDateTimeUTCStringTime 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
isSuppressMessagesBooleanSuppress direct messaging to payer and recipient. Default value is falseYes
payerCollectionFeeShareNumberThis 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.0Yes
payeeCollectionFeeShareNumberThis 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.0Yes
isAllowPartialPaymentsBooleanBoolean flag indicating whether or not to accept partial payments for the payment request. Default value is falseNo
callBackUrlStringThe callback url that will be notified with updates on the payment request statusYes
paymentMethodsArrayList of permitted payment methods for processing this request. Available options are listed in the payment methods sectionYes
displayBankDetailToPayerBooleanThis displays the bank details of the payer (bank name and account number) in addition to the payee.name to the payee.No
isAllowOverPaymentsBooleanBoolean flag indicating whether or not to accept payments above the amount set for the payment request. If isAllowOverPayments is set to false, then overpayments will be rejected. If set to true then overpayments will be accepted as before.
Default value is false
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,
  "isAllowOverPayments":true,
  "callBackUrl" : "http://localhost:9091/test-callback",
  "paymentMethods" : ["BANK_TRANSFER","FUNDING_USSD","REQUEST_MONEY"],
  "displayBankDetailToPayer": false
}
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 277

{
  "referenceNumber" : "2353464564565",
  "statusCode" : "0",
  "statusMessage" : null,
  "paymentMethods" :  [
        {
            "name": "BANK_TRANSFER",
            "properties": {
                "AccountNumber": "0442812672"
            }
        },
        {
            "name": "FUNDING_USSD",
            "properties": {
                "USSDShortCode": "*901*000*724+85682363#",
                "PaymentReference": "85682363"
            }
        },
        {
            "name": "MONEY_TRANSFER",
            "properties": {
                "AccountNumber": "0442812672"
            }
        }
    ],
  "expiryDateTimeUTC" : null,
  "isPayerPagaAccountHolder" : false
}

Response Parameter

ArgumentTypeDescription
referenceNumberStringThe reference number that was provided in the request
statusCodeStringThe status of the operation. See Status Codes section for details
statusMessageStringA human readable status message
paymentMethodsArrayDetails of available payment methods for this request
paymentMethods.[].nameStringThe name of the payment method
paymentMethods.[].propertiesObjectThe additional properties for the payment method
paymentMethods.[].properties.paymentCodeStringPayment code for the specified payment method
expiryDateTimeUTCDateThe expiry timestamp of the payment request in UTC
payerPagaAccountHolderBooleanBoolean flag to indicate whether or not the payment was fulfilled from a paga account

📘

if the expiry time provided by the initiator is less than 5 minutes, the USSDShortCode should be used to initiate the payment.

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

ArgumentTypeRequired (Yes/No)Description
referenceNumberStringA unique reference number representing the operation that is being queriedYes

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" : "235346458802",
}
HTTP/1.1 200 OK
Content-Type: application/json


{
    "referenceNumber": "235346458802",
    "statusCode": "0",
    "statusMessage": "success",
    "data": {
        "referenceNumber": "235346458802",
        "statusCode": "0",
        "statusMessage": "success",
        "requestAmount": 7000.0,
        "totalPaymentAmount": 7048.38,
        "currency": "NGN",
        "expiryDateTimeUTC": "2021-09-29T23:00:00"
    }
}

Response Parameter

ArgumentTypeDescription
referenceNumberStringThe reference number that was provided in the request
statusCodeStringThe status of the operation. See Status Codes section for details
statusMessageStringA human readable status message
requestAmountNumberThe amount requested by the payee
totalPaymentAmountNumberThe total amount paid by the payer.
currencyStringThe currency of the operation, only required if being executed in a foreign currency.
expiryDateTimeUTCDateThe expiry timestamp of the payment request in UTC.

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

ArgumentTypeDescriptionRequired (Yes/No)
referenceNumberStringThe unique reference number representing the payment request to be refunded.Yes
refundAmountNumberAmount to be refundedYes
currencyStringThe currency of the operation.Yes
reasonStringReason for the refund requestNo

Sample Request and Sample Response

POST /refund HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: "Basic RkUxRjlCN0YtQkJDRS00NkEwLTk2ODUtMERDQUU5M0FDMjIyOlBhc3N3b3JkMQ=="
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"
}

History / Bank List

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

ArgumentTypeDescriptionRequired (Yes/No)
referenceNumberStringA unique reference number representing a request. If provided, it will restrict results to only those tied to the request with that specific reference numberNo
startDateTimeUTCStringA timestamp representing the start of the transaction history request. Range must be less than or equal to 3 monthsYes
endDateTimeUTCStringA timestamp representing the end of the transaction history request. Range must be less than or equal to 3 monthsNo

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

ArgumentTypeDescription
statusCodeStringThe status of the operation. See Status Codes section for details
statusMessageStringA human readable status message
itemCountIntegerThe number of actions carried out within in the specified start and end date
itemsArrayAn array representing all actions carried out within the time window
items[].datetimeStringTimestamp in local time indicating when the payment request action was performed
items[].referenceNumberStringThe reference number that was provided in the request
items[].operationStringThe operation performed, a category of operation perfomed. See list of different operations here
items[].actionStringThe action performed, a subcategory of operation. see list of actions here
items[].amountDoubleThe amount requested or paid depending of the action carried out.
items.[].statusStringStatus of the action performed. See documentation on different statuses
items[].datetimeUTCStringTimestamp in UTC indicating when the payment request action was performed

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

ArgumentTypeDescriptionRequired (Yes/No)
referenceNumberStringA 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",
    "sortCode": null,
    "ussdCode": null
  }, {
    "name" : "Access Bank",
    "uuid" : "F8F3EFBF-67CB-4C17-A079-B7CFE95F71BE",
    "sortCode": null,
    "ussdCode": null
  } ]
}

Response Parameter

ArgumentTypeDescriptionRequired (Yes/No)
referenceNumberStringThe reference number that was provided in the request
statusCodeStringThe status of the operation. See Status Codes section for details
statusMessageStringA human readable status message
banksArrayAn array representing all payment requests from processor within the time window
banks.[].uuidStringAn id uniquely identifying a Bank on Paga
banks.[].nameStringDisplay name of the identifying bank
banks.[].sortCodeStringCentral Bank of Nigeria(CBN) sort code
banks.[].ussdCodeStringCoralPay USSD code

Persistent Account

6. 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.

ParameterTypeDescriptionRequired?
referenceNumberStringA unique reference number for this request.
This same reference number will be returned in the response.
Yes
phoneNumberStringThe phone number of the customer. This must be provided if the email is not provided.No
accountNameStringThe acountname of the customer.Yes
firstNameStringThe first name of the customerYes
lastNameStringThe last name of the customerYes
financialIdentificationNumberStringThe customer's Bank verification Number (BVN)No
emailStringThe email of your customer. This must be provided if the phoneNumber is not provided.No
accountReferenceStringThis 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 charactersYes
creditBankIdStringIf included, this is the public Id of the bank that you want deposits to be transferred directly to for every payment. You can get bank IDs HERENo
creditBankAccountNumberStringThis 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 creditBankIdNo
callbackUrlStringA 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
fundingTransactionLimitFloatThe maximum amount that can be transferred to the persistent account generated. If an amount greater than the limit is transferred, such transaction will be declined automatically by the senders bankNo

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",
		"fundingTransactionLimit":50000.00
  }
{
    "referenceNumber": "test12345100",
    "statusCode": "0",
    "statusMessage": "success",
    "accountReference": "2222222222222023",
    "accountNumber": "1725110000"
}

Response Parameters

ParameterTypeDescription
referenceNumberStringThe same unique reference number provided in the request
statusCodeNumberStatus code of the response. 0 indicates a successful response
statusMessageStringHuman-readable description about of response. 'Success'for a successful response
accountNumberStringThe persistent payment account number for your customer
accountReferenceStringThis is a unique reference number provided by the Organization which is sent in the original request

👍

Although the financialIdentificationNumber(BVN) is optional, to benefit from our robust security fraud check, it is advisable that you provide it.

7. Delete Persistent Payment Account

This endpoint allows for deleting a persistent payment account.

Request Parameter

ArgumentTypeDescriptionRequired
referenceNumberStringThe unique reference number representing the delete persistent payment account request.Yes
accountIdentifierStringThe accountIdentifier can be either the NUBAN or the accountReference the customer provided when creating the accountYes
reasonStringReason for deleting the accountNo

Sample Request and Response

POST /deletePersistentPaymentAccount HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: "Basic RkUxRjlCN0YtQkJDRS00NkEwLTk2ODUtMERDQUU5M0FDMjIyOlBhc3N3b3JkMQ=="
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"
}
ArgumentTypeDescription
referenceNumberStringThe same unique reference number provided in the request
statusCodeStringStatus code of the response. 0 indicates a successful response
statusMessageStringThe status of the request, this should just be an
acknowledgement that the request was received.

❗️

CAUTION

This operation cannot be reversed!

8. 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

ArgumentTypeDescriptionRequired (Yes/No)
referenceNumberStringThe unique reference number representing the update persistent payment account request.Yes
accountIdentifierStringThe accountIdentifier can be either the NUBAN or the accountReference that was provided when creating the persistent payment accountYes
phoneNumberStringThe customer's phone number.No
firstNameStringThe first name of the customerNo
lastNameStringThe last name of the customerNo
accountNameStringThe acountname of the customer.No
financialIdentificationNumberStringThe customer's Bank verification Number (BVN)No
callbackUrlStringA 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
creditBankIdStringIf 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 HERENo
creditBankAccountNumberStringThis 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 creditBankIdNo

ArgumentTypeDescription
referenceNumberStringThe same unique reference number provided in the request
statusCodeStringStatus code of the response. 0 indicates a successful response
statusMessageStringThe 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
Authorization: "Basic RkUxRjlCN0YtQkJDRS00NkEwLTk2ODUtMERDQUU5M0FDMjIyOlBhc3N3b3JkMQ=="
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"
}

10. Get Persistent Payment Account

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

ParameterTypeDescriptionRequired(Yes/No)
referenceNumberStringThe unique reference number representing the update persistent payment account request.Yes
accountIdentifierStringThe accountIdentifier can be either the NUBAN or the accountReference the customer provided when creating the accountYes

Sample Request and Response

POST /getPersistentPaymentAccount HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: "Basic RkUxRjlCN0YtQkJDRS00NkEwLTk2ODUtMERDQUU5M0FDMjIyOlBhc3N3b3JkMQ=="
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"
}
ParameterTypeDescription
referenceNumberStringThe same unique reference number provided in the request
statusCodeStringStatus code of the response. 0 indicates a successful response
statusMessageStringA human readable status message.
accountReferenceStringThis 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.
accountNameStringThe name of the customer
that made the transaction.
phoneNumberStringThe phone number of the customer.
firstNameStringThe firstName of the customer.
lastNameStringThe lastName of the customer
financialIdentificationNumberStringThe customer's Bank verification Number (BVN)
creditBankIdStringThis is the public Id of the bank that was provided while creating the persistent payment account. You can check up creditBankIds HERE
creditBankAccountNumberStringThis 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
callbackUrlStringA custom callback URL for the payment webhook notifications for this specific account to be sent to.

Callback Sample

11. 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).

ParameterTypeDescription
statusCodeNumberStatus code of the response. 0 indicates a successful response
statusMessageStringHuman-readable description
about of response. 'Success'
for a successful response
accountNumberStringThe persistent payment
account number for your customer.
accountNameStringThe name of the customer
that made the transaction
financialIdentificationNumberStringThe customer's Bank verification Number (BVN)
amountStringThe total amount of the transaction
clearingFeeAmountStringThe fee for receiving a payment into a persistent payment account
transferFeeAmountStringThe additional fee for transferring received payment to an external bank account
transferBankNameStringThe name of the bank to transfer payment to
transferBankAccountNumberStringThe account number of the bank account to transfer payment to
transactionReferenceStringThe referenceNumber of the transaction
fundingPaymentReferenceStringThe payment reference from the original transfer/payment into the persistent payment account (Only available for NIP transfers).
payerDetails.paymentReferenceNumberStringThis represents the unique reference number of a transaction associated with funding a persistent payment account.
payerDetails.paymentMethodStringThis represents the payment method used to fund the persistent payment account.
payerDetails.payerNameStringThis represents the name of the payer funding the persistent payment account.
payerDetails.payerBankNameStringThis represents the bank name of the payer funding the persistent payment account for payments done via bank transfer.
payerDetails.payerBankAccountNumberStringThis represents the bank account number of the payer funding the persistent payment account for payments done via bank transfer.
hashStringThe 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": "success",
    "transactionReference": "DFB-U_20211007201411657_2467458_9CNLC",
    "fundingPaymentReference": "PAGA|280418|0000000021",
    "accountNumber": "2468505842",
    "accountName": "Fortieth Customer",
    "financialIdentificationNumber": null,
    "amount": "700.00",
    "clearingFeeAmount": "50.00",
    "transferFeeAmount": "50.00",
    "transferBankName": "Access Bank",
    "transferBankAccountNumber": "0000000000",
    "payerDetails": {
        "paymentReferenceNumber": "PAGA|280418|0000000021",
        "paymentMethod": "BANK_TRANSFER",
        "payerName": null,
        "payerBankName": "Access Bank",
        "payerBankAccountNumber": null
    },
    "hash": "d6ec130666a76c8e9b72c01ee066518daa6a59c136ef5f13043d05a78bd90c35974eac42834fc8b225a59ba393624a7ae16325658d4af03fde30f2dcd4d8ab95"
}
{
		"status":"SUCCESS",
}
ParameterTypeDescription
statusStringThe status of the request, this should just be an
acknowledgement that the request was received.

12. 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).

Request Parameters

ArgumentTypeDescription
notificationIdStringA 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.
statusCodeStringThe status of the operation. See Status Codes section for details
statusMessageStringA human readable status message
externalReferenceNumberStringThe reference number that was provided for the payment request
fundingPaymentReferenceStringThe payment reference from the original transfer/payment (Only available for NIP transfers).
stateStringThe current state of the payment request. See Payment Request State section for details of the possible states.
outstandingBalanceNumberOutstanding amount to be paid by the payer if the money paid to the payee by the payer was less than the actual amount in the payment request.
cumulativePaymentAmountNumberTotal amount paid to fulfil a particular payment request.
paymentAmountNumberAmount paid by the payee.
eventStringThe current state of the payment.
See Callback Events for more details.
collectionFeeNumberThis represents the payment request fee that was charged to either payee or payer depending on the payment request . For more details, see payerCollectionFeeShare and payeeCollectionFeeShare in payment request
transferBankNameStringThis represent the bank account name that the payment request funds should be sent onwards to, whenever received. This is optional
transferAccountNumberStringThis represent the bank account number that the payment request funds should be sent onwards to, whenever received. This is optional
transferFeeStringThis represents the fee charged for transferring the payment request fund to a particular bank account.
fundingDetails.payerAccountNumberStringThis represents the source account number (eg. Paga account number) details for the payer if they carried out money transfer from a non-bank account (eg. from Paga)
fundingDetails.paymentReferenceNumberStringThis represents the unique reference number associated with the bank transfer associated with fulfilling a particular payment request.
fundingDetails.payerNameStringThis represents the source bank account name of the payer if the fulfilment of the payment request was via transfer from a bank account.
fundingDetails.payerBankNameStringThis represents the source bank name of the payer if the fulfilment of the payment request was via transfer from a bank account.
fundingDetails.payerBankAccountNumberStringThis represents the source bank account number of the payer if the fulfilment of the payment request was via transfer from a bank account.
hashStringThe 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”).

Sample Request and Response

{
    "event": "PAYMENT_COMPLETE",
    "notificationId": "e68545b8-358c-4b72-9ac1-0471008617e7",
    "statusCode": "0",
    "statusMessage": "Payment Request has been authorized",
    "externalReferenceNumber": "235346458807",
    "state": "CONSUMED",
    "outstandingBalance": 0,
    "paymentAmount": 7048.38,
    "cumulativePaymentAmount": 7048.38,
    "collectionFee": 53.75,
    "transferBankName": "Access Bank",
    "transferBankAccountNumber": "0000000000",
    "transferFee": 0,
    "fundingDetails": {
        "payerAccountNumber": null,
        "paymentReferenceNumber": "PAGA|280418|0000000010",
        "payerName": null,
        "payerBankName": "Access Bank",
        "payerBankAccountNumber": null
    },
    "hash": "e1f12b4dfcc399eb17fad29e676914c0d7f15420e82a384de2676cf473aa9e27aa744fbd2aa2bb2ff33b615ff38d4f6e970ad12648cf67ec613d0ec81fad9f1f"
}