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

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

3. Payment Request Fund

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
principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of developer)
Authorization: "Basic RkUxRjlCN0YtQkJDRS00NkEwLTk2ODUtMERDQUU5M0FDMjIyOlBhc3N3b3JkMQ=="
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"
}

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

Request URL
https://collect.paga.com/registerPersistentPaymentAccount

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
email	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 URL
https://collect.paga.com/deletePersistentPaymentAccount

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)
Authorization: "Basic RkUxRjlCN0YtQkJDRS00NkEwLTk2ODUtMERDQUU5M0FDMjIyOlBhc3N3b3JkMQ=="
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!

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 URL
https://collect.paga.com/updatePersistentPaymentAccount

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
principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of developer)
Authorization: "Basic RkUxRjlCN0YtQkJDRS00NkEwLTk2ODUtMERDQUU5M0FDMjIyOlBhc3N3b3JkMQ=="
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"
}

10. Get Persistent Payment Account

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

Request URL
https://collect.paga.com/getPersistentPaymentAccount

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)
Authorization: "Basic RkUxRjlCN0YtQkJDRS00NkEwLTk2ODUtMERDQUU5M0FDMjIyOlBhc3N3b3JkMQ=="
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.

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"
}

Collect API Operations

HTTP Basic Authentication

📘

Request Payment

1. Request Payment

📘

2. Status

3. Payment Request Fund

❗️
Please Note

History / Bank List

4. History

5. Get Banks

Persistent Account

6. Create Persistent Account Number

👍

7. Delete Persistent Payment Account

❗️
CAUTION

8. Update Persistent Payment Account

10. Get Persistent Payment Account

Callback Sample

11. Persistent Payment Account Callback Notification

📘
Please take note

12. Payment Request Callback notifications

📘
Please take note.

HTTP Basic Authentication

📘

Request Payment

1. Request Payment

📘

2. Status

3. Payment Request Fund

❗️Please Note

History / Bank List

4. History

5. Get Banks

Persistent Account

6. Create Persistent Account Number

👍

7. Delete Persistent Payment Account

❗️CAUTION

8. Update Persistent Payment Account

10. Get Persistent Payment Account

Callback Sample

11. Persistent Payment Account Callback Notification

📘Please take note

12. Payment Request Callback notifications

📘Please take note.

❗️
Please Note

❗️
CAUTION

📘
Please take note

📘
Please take note.