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 URL |
---|
https://collect.paga.com/paymentRequest |
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 |
isAllowOverPayments | Boolean | Boolean 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
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 expiry timestamp of the payment request in UTC |
payerPagaAccountHolder | Boolean | Boolean 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.
2. 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 URL |
---|
https://collect.paga.com/status |
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" : "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
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 |
requestAmount | Number | The amount requested by the payee |
totalPaymentAmount | Number | The total amount paid by the payer. |
currency | String | The currency of the operation, only required if being executed in a foreign currency. |
expiryDateTimeUTC | Date | The 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 URL |
---|
https://collect.paga.com/refund |
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
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 URL |
---|
https://collect.paga.com/history |
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[].datetime | String | Timestamp in local time indicating when the payment request action was performed |
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 |
items[].datetimeUTC | String | Timestamp 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 URL |
---|
https://collect.paga.com/banks |
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",
"sortCode": null,
"ussdCode": null
}, {
"name" : "Access Bank",
"uuid" : "F8F3EFBF-67CB-4C17-A079-B7CFE95F71BE",
"sortCode": null,
"ussdCode": null
} ]
}
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 | |
banks.[].sortCode | String | Central Bank of Nigeria(CBN) sort code | |
banks.[].ussdCode | String | CoralPay 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.
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. This must be provided if the email is not provided. | No |
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) | No |
String | The email of your customer. This must be provided if the phoneNumber is not provided. | No | |
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 for 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 |
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 |
fundingTransactionLimit | Float | The 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 bank | No |
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
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 |
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
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
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"
}
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!
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
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 phone number. | 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
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.
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
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"
}
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. |
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).
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). |
payerDetails.paymentReferenceNumber | String | This represents the unique reference number of a transaction associated with funding a persistent payment account. |
payerDetails.paymentMethod | String | This represents the payment method used to fund the persistent payment account. |
payerDetails.payerName | String | This represents the name of the payer funding the persistent payment account. |
payerDetails.payerBankName | String | This represents the bank name of the payer funding the persistent payment account for payments done via bank transfer. |
payerDetails.payerBankAccountNumber | String | This represents the bank account number of the payer funding the persistent payment account for payments done via bank transfer. |
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": "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",
}
Parameter | Type | Description |
---|---|---|
status | String | The 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
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. |
outstandingBalance | Number | Outstanding 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. |
cumulativePaymentAmount | Number | Total amount paid to fulfil a particular payment request. |
paymentAmount | Number | Amount paid by the payee. |
event | String | The current state of the payment. See Callback Events for more details. |
collectionFee | Number | This 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 |
transferBankName | String | This represent the bank account name that the payment request funds should be sent onwards to, whenever received. This is optional |
transferAccountNumber | String | This represent the bank account number that the payment request funds should be sent onwards to, whenever received. This is optional |
transferFee | String | This represents the fee charged for transferring the payment request fund to a particular bank account. |
fundingDetails.payerAccountNumber | String | This 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.paymentReferenceNumber | String | This represents the unique reference number associated with the bank transfer associated with fulfilling a particular payment request. |
fundingDetails.payerName | String | This represents the source bank account name of the payer if the fulfilment of the payment request was via transfer from a bank account. |
fundingDetails.payerBankName | String | This represents the source bank name of the payer if the fulfilment of the payment request was via transfer from a bank account. |
fundingDetails.payerBankAccountNumber | String | This represents the source bank account number of the payer if the fulfilment of the payment request was via transfer from a bank account. |
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”). |
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"
}
Updated 4 months ago