Documentation
Documentation

Persistent Wallet Account

Generate a Paga Persistent Account for your customers

Suggest Edits

Persistent accounts are static account numbers (NUBAN) generated from Paga that allow merchants to receive payment via Bank Transfers. This account number does not expire and allows merchants to receive payment in perpetuity from the customer unless deleted or deactivated by the merchant

📘

Persistent Account and Dynamic Virtual Account are different

Persistent Account are account numbers generated for repeat payment. They can be tied to a customer in perpetuity, and they do not expire unless deleted by a merchant.

Dynamic Virtual Account can only be used for a single transaction and expired after a set period or immediately after the designated transaction is completed.

How to get paid

Generate a persistent account and get paid in 3 simple steps:

  1. Generate and allocate unique Persistent account numbers to your customers
  2. Display the account number to your customer and indicate the bank as Paga.
  3. After successful payment, we will send you a callback with details of the payment.

Step 1: Get all the needed information

Below is the list of parameters required to generate account number

ArgumentData TypeDescriptionRequired
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 status
hashIndex-1		True
phoneNumberStringThe phone number of the customer. This must be provided if the email is not provided.True
accountNameStringThe acountname of the customer.True
firstNameStringThe first name of the customerTrue
lastNameStringThe last name of the customerTrue
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
hashIndex-2		True
financialIdentificationNumberStringBVN of the customer
hashIndex-3		False
emailStringThe email of your customer. This must be provided if the phoneNumber is not provided.False
creditBankIdStringIf included, this is the UUID of the bank that you want deposits to be transferred directly to for every payment. You can get destination bank UUID from getBank Endpoint
hashIndex-4		False
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 creditBankId
hashIndex-5		False
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.
hashIndex-6		False

Step 2: Generate a Persistent

For this step, you’ll need to parse all relevant param from above in a POST request to obtain the payment bank account number

POST /registerPersistentPaymentAccount HTTP/1.1
Host: collect.paga.com
hash:  69cdcaaee22e0491d83602e8ab15ebb2a70c3657803af0bd7e786cf529c5f9a210f1a5bfdefa2d3bbcbc786b1b65a5b29a65acfdea8b062fc91f3f689db41640
Authorization: Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==
Content-Type: application/json

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

#PIP install Paga collect library if you've not done so already
#pip install pagacollect

from pagacollect.paga_collect import Collect

principal = "public_key"
credentials = "Secret/Credential"
hash_key = "HMAC"

collect = Collect(principal, credentials, hash_key, False)

register_persistent_payment_account_payload = {
    "referenceNumber": "test123451",
    "phoneNumber": "07022222222",
    "accountName": "Joh Doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "accountReference": "22222222222220",
    "financialIdentificationNumber": "22182799077",
    "creditBankId": "3E94C4BC-6F9A-442F-8F1A-8214478D5D86",
    "creditBankAccountNumber":"00000000000",
    "callbackUrl": "http://localhost:9091/test-callback"
}

response = collect.register_persistent_payment_account(register_persistent_payment_account_payload)

//install Paga collect client if you've not done so already
//npm install paga-collect

const PagaCollectClient = require('paga-collect');

const pagaCollectClient = new PagaCollectClient()
    .setClientId("6BD06E93-52A1-496E-AC46-3A486E04A83B")
    .setPassword("tQ4*%WRxb=hPD24")
    .setApiKey("ea596e10e018402c91ee65b11060ab6f3008afcf5b1148288e4281973fd7e2529d152e5fec1d4ed8b577c500ad890ad2f1a708e8b7fe470fa54e194c356a91bc")
    .setTest(true)
    .build();


let data = {
    "referenceNumber": "0053459875439143453000",
    "phoneNumber": "08048276159",
    "firstName": "Bellview",
    "lastName": "Walker",
    "accountName": "Bellview Walker",
    "accountReference": "123467891334",
    "callBackUrl": "http://localhost:5000/core/webhook/paga"
}

pagaCollectClient.registerPersistentPaymentAccount(data).then(resp => {
    console.log(JSON.stringify(resp))
});

Sample Response 

{
    "referenceNumber": "0053459875439143453000",
    "statusCode": "0",
    "statusMessage": "success",
    "accountReference": "123467891334",
    "accountNumber": "1061871576"
}

Step 3: Share the Persistent account Number

Display the account number to your customers on a friendly UI

Account Number: 1061871576
Bank: Paga

Step 4: Callback Notification for successful payment

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

{
  "statusCode": "0",
  "statusMessage": "success",
  "transactionReference": "SC-C_20220915113942190_4293418_ND8K0_6dg5g",
  "fundingPaymentReference": null,
  "accountNumber": "2830163290",
  "accountName": "Bellview Walker",
  "financialIdentificationNumber": null,
  "amount": "200.00",
  "clearingFeeAmount": "1.50",
  "payerDetails": {
    "payerAccountNumber": "0745089449",
    "paymentReferenceNumber": null,
    "paymentMethod": "MONEY_TRANSFER",
    "payerName": "Bello Ramon"
  },
  "hash": "0d57b7d8d1a21a94eec7edd951aaeaeb5e8597672d05fb732f146e93e79ac7caa520ff86ed069f28c3322e469af4898a7d72f3e0c83d919d61c535140b4eef8e"
}

📘

Is callback retry available? Yes

The persistent account callback retries as follows:

  • At the initial time when the payment is made, it tries three times in succession to notify your endpoint with the following intervals: immediately, 1 second later, 5 seconds later, 15 seconds later

  • If none is successful, it gets added to a queue for intermittent retries every 5 minutes for the next 30 minutes or until a callback is successful

With the above, there shouldn't be any case where you do not receive the notification callback unless your callback endpoint is offline for more than 30 minutes

We have few more endpoint available to give you more flexibilty

Updated over 2 years ago

What’s Next