Dynamic Payment Identifier are one-time use payment identifiers generated from Paga that allow merchants to receive payment via Bank Transfers.

📘
Dynamic Payment Identifier and Persistent Payment Identifier are different
Dynamic Payment Identifier can only be used for a single transaction and expired after a set period or immediately after the designated transaction is completed.
Persistent Payment Identifier are payment identifiers generated for repeat payment. They can be tied to a customer in perpetuity, and they do not expire unless deleted by a merchant.

A payment identifier can be:

Dynamic
A dynamic payment identifier allows payments to be made within a specific period of time.
Static (also called Persistent Payment Identifier)
A static payment identifier allows repeat payments to be made over a long period of time.

Exploring Dynamic Payment Identifier

We’ll be exploring dynamic payment identifier and how you can use it to receive payment from your customers. This request utilizes the payment request endpoint to accomplish its tasks.

-->

How to get paid

Generate a dynamic payment identifier and get paid in 3 simple steps:

Generate a payment identifier via Payment Request endpoint with the BANK_TRANSFER payment method.
Display the payment identifier to your customer and indicate the bank as Paga.
After successful payment, we send you a callback with details of the payment.

With the Payment Identifier, you can query the account name even after it expires which makes it easier to trace payments, verify senders, and keep accurate records.

Step 1: Get all the needed information

Below is the list of parameters required to generate a payment identifier

Argument	Data Type	Description	Required
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 Hashindex-1	True
amount	Float	The amount being requested Hashindex-2	True
currency	String	The currency of the operation, only required if being executed in a foreign currency. Hashindex-3	True
payer	Object	The person/entity from whom we are requesting a payment	True
payer.name	String	Name of the payer.	True
payer.phoneNumber	String	Phone number of the payer. Either one of phone-number or e-mail address must be provided Hashindex-4	True
payer.email	String	E-mail address of the payer. Either one of phone-number or e-mail address must be provided Hashindex-5	False
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	True
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.	True
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.	False
isSuppressMessages	Boolean	Suppress direct messaging to payer and recipient. Default value is false	Yes
payerCollectionFeeShare	Float	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	True
payeeCollectionFeeShare	Float	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	True
isAllowPartialPayments	Boolean	Boolean flag indicating whether or not to accept partial payments for the payment request. Default value is false	False
isAllowOverPayments	Boolean	Boolean flag indicating whether or not to accept payments above the amount set for the payment request. If isAllowOverPayments is set to true, then overpayments will be rejected. If set to true then overpayments will be accepted as before. Default value is true	False
callBackUrl	String	The callback url that will be notified with updates on the payment request status	False
paymentMethods	List	List of permitted payment methods for processing this request. Parse value as BANK_TRANSFER	True

Step 2: Generate a payment identifier

For this step, you’ll need to parse all the param above in a POST request to obtain the payment identifier

POST /paymentRequest HTTP/1.1
Host: collect.paga.com
hash:  51102e0c13fcd67877366147f7a7f5cbf8fbaaec5304edc68126179978e743572b9426975cef0d7ed1863fdda6065b1b254bfdfcf4d0f39ae1ccd8a010cc4382
Authorization: Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==
Content-Type: application/json
Content-Length: 565

{
    "referenceNumber": "246000909797",
    "amount": 50,
    "currency": "NGN",
    "payer": {
        "name": "Mustapha",
        "phoneNumber": "07060823006"
 
    },
    "payee": {
        "name": "Gurner Nigeria Limited"
    },
    "expiryDateTimeUTC": "2022-04-28T16:35:00",
    "isSuppressMessages": true,
    "payerCollectionFeeShare": 1,
    "payeeCollectionFeeShare": 0,
    "isAllowPartialPayments": false,
    "callBackUrl": "https://webhook.site/efda4728-139e-4efa-b5c3-d7fb24e28475?",
    "paymentMethods": [
        "BANK_TRANSFER"
    ]
}

Sample Response

{
    "referenceNumber": "246000909797",
    "statusCode": "0",
    "statusMessage": "success",
    "requestAmount": 50.0,
    "totalPaymentAmount": 50.41,
    "currency": "NGN",
    "paymentMethods": [
        {
            "name": "BANK_TRANSFER",
            "properties": {
                "AccountNumber": "0856712865"
            }
        },
        {
            "name": "MONEY_TRANSFER",
            "properties": {
                "AccountNumber": "0856712865"
            }
        }
    ],
    "expiryDateTimeUTC": "2022-04-28T16:35:00",
    "isPayerPagaAccountHolder": false
}

Step 3: Payment details

Display the payment identifier to your customers on a friendly UI

Payment Identifier: 0856712865
Bank: Paga
Amount: 50.41

Step 4: Callback Notification

After your customer makes the payment, we’ll send a callback notification to the callback URL you provided in your request
More about callback parameters

{
  "event": "PAYMENT_COMPLETE",
  "notificationId": "a12ef82b-14d0-4a67-a08c-162b95154f59",
  "statusCode": "0",
  "statusMessage": "Payment Request has been authorized",
  "externalReferenceNumber": "234447994060953",
  "state": "CONSUMED",
  "outstandingBalance": 0,
  "paymentAmount": 4032.25,
  "cumulativePaymentAmount": 4032.25,
  "collectionFee": 32.25,
  "fundingDetails": {
    "payerAccountNumber": "0980763285",
    "paymentReferenceNumber": null,
    "payerName": "Bello Ramon",
    "payerBankName": null,
    "payerBankAccountNumber": "0980763285"
  },
  "hash": "33f9c9bd0785c2ccfa66ddedfbae7c3b56361250c581a39edad1d2ed08ccfbed845f34b8c30532f7c0ec544483ebee9360c5749bfe5eaa9986ac5553488e058a"
}

Step 5: Check payment status

You’ll need to make a server-to-server call to get the status of the transaction. Your JSON request should look like below

POST /status HTTP/1.1
Host: collect.paga.com
hash: 1f42eb2a076147063285d6321a969376472c2b2710220051c1736386ff01ea0f9c4ff8ddf43cd8e497327760a2faad9139a4a3af38a1e2c2f68b56851a5a99f1

Authorization: Basic e3t1c7VybmFtZX19Ont7cGFzc3dvcmR9fb==
Content-Type: application/json
Content-Length: 51

{
    "referenceNumber": "23534646579650395979"
}

You’ll receive a JSON response like below, the data dictionary will give you the details and status of your request.

{
    "referenceNumber": "2460039509797",
    "statusCode": "0",
    "statusMessage": "success",
    "data": {
        "referenceNumber": "2460039509797",
        "statusCode": "0",
        "statusMessage": "success",
        "requestAmount": 50.0,
        "totalPaymentAmount": 50.41,
        "currency": "NGN",
        "paymentMethods": [
            {
                "name": "REQUEST_MONEY",
                "properties": {
                    "PaymentReference": "0be92b6b-b057-4652-a773-2fc4f886637c",
                    "WebPaymentLink": "https://justpaga.me/0be92b6b-b057-4652-a773-2fc4f886637c"
                }
            }
        ],
        "expiryDateTimeUTC": "2022-04-28T16:35:00",
        "isPayerPagaAccountHolder": true
    }
}

What if payment wasn’t made or completed

Don’t worry, we will send you a conclusive callback once the request expires and the customer didn’t make payment.

We are done!

Other supporting operations

We have few more endpoints available to give you more flexibility

Refund - Refund a payment previously received from customer, support full and partial refund operation
History of all activities - Generate the history of all activities you've performed, requests generated, the payment received, and refund completed among other

📘Dynamic Payment Identifier and Persistent Payment Identifier are different

Exploring Dynamic Payment Identifier

How to get paid

Step 1: Get all the needed information

Step 2: Generate a payment identifier

Step 3: Payment details

Step 4: Callback Notification

Step 5: Check payment status

What if payment wasn’t made or completed

Other supporting operations

📘
Dynamic Payment Identifier and Persistent Payment Identifier are different