Paga Checkout
Introduction
The Paga Checkout payment gateway provides an easy-to-integrate payments collection tool for any online merchant to collect payments on their website for customers using a number of different payment methods.
The tool supports multiple customer payment methods (funding sources) including:
- Cards
- Bank accounts
- Paga
The gateway renders easily and non-invasively on any device: desktop, tab, mobile.


Quick Start: How to Use
You can quickly embed the Checkout request tool within your Page by adding an HTML form tag containing a script element as follows:
Note: To get your Paga acccount principal which needs to be set in the
data-public_key
script parameter in the script age as shown below, you need to register for a Paga business account
<form action="https://mymarket/payment/complete" method="POST">
<script src="https://beta.mypaga.com/checkout/?w=150&h=40"
data-charge_url="https://mymarket/payment/complete"
data-redirect_url_method ="GET"
data-public_key="<ENTER_YOUR_ACCOUNT_PRINCIPAL_HERE>"
data-amount="1000.00"
data-currency="NGN"
data-payment_reference="JHX-18743567"
data-account_number="41007258779"
data-product_description="Gelly Giraffe"
data-phone_number="+251911514855"
data-email="[email protected]"
data-product_codes="XBR-652394"
data-display_image="https://mymarket/cdn//img/icon.png"
data-display_name="Shem’s Shoes"
data-display_tagline="Walk the Talk"
data-button_label="Pay With Paga"
data-width="200"
data-callback_url="http://localhost:8080/checkout/notify"
data-funding_sources="BANK,CARD,PAGA">
</script>
</form>
- This will render a "Pay with Paga" button within your Page at the location of the tag (the button can be customized to show your own image as is covered later)
- When the button is clicked, the checkout widget will be loaded within an iFrame where all subsequent
transactions and redirects will take place.
Widget Parameters
There are the parameters that may be set in the <script>
tag above to control the behavior of the Checkout tool
Argument Name | Type | Mandatory(M)/Optional(O) | Description |
---|---|---|---|
data-public_key | String | M | Business organization publicId (eg. B63F8C7E-D453-4B89-AC5C-40843AD3FA1E). |
data-amount | double | M | The amount of money to transfer to the recipient. |
data-payment_reference | String | M | A unique reference number provided by the business, identifying the transaction. This reference number will be preserved on the Paga platform to reconcile the operation across systems and will be returned in the response. |
data-phone_number | String | O | The phone number of the customer. |
data-email | String | O | The email of the customer. |
data-account_number | String | O | The account number identifying the customer on the merchant's system. |
name | String | O | The name of the customer. |
data-product_codes | String | O | Code identifying the product the customer is purchasing. |
data-product_description | String | O | A description of the product |
data-currency | String | O | The currency of the operation, if being executed in a foreign currency |
data-display_image | String | O | Logo image url to be shown on checkout dialog |
data-display_name | String | O | Merchant display name to be shown on checkout dialog |
data-display_tagline | String | O | Merchant display tagline to be shown on checkout dialog |
data-button_label | String | O | Text to be displayed on checkout button |
data-charge_url | String | O | Url to redirect after successful transaction. |
data-redirect_url_method | String | O | The redirect url method is an Optional Parameter. This can either be POST or GET. If not specified, it will default to POST. |
allowRememberMe | Boolean | O | To enable remember me feature |
data-funding_sources | String | O | Comma separated list of funding sources. Available options are CARD, BANK and PAGA. If not set, it'll display all three options |
data-callback_url | String | O | The callback url that will be notified with updates on the payment carried via checkout |
w | String | O | Width of the button to be displayed |
h | String | O | Height of the button to be displayed |
NOTE
Test base-url : https://beta.mypaga.com/
Live base-url: https://www.mypaga.com/
Customizing the Checkout Button
The button can be customizable and you’ll be able to use your customized button/link instead of the default “Pay with paga” button. On the src data element in the script tag above, observe the following parameters as shown in the example below:
w=width of a button, h=height of a button, url=link to your button image stored on a CDN or your host server


The form parameters are:
- The form action or data-charge_url (only one required) is the URL to your endpoint which will be called upon completion of processing.
- data-payment_reference must be unique for each distinct payment
- data-public_key is your public API key
- data-account_number is the customer’s “account number” with you
Resolving a completed payment
After payment is initiated within the checkout widget, a redirect is triggered automatically to point to the data-charge_url element which has been provided in the script tag. Provide a charge_url where you’ll be able to receive the reference and amount values passed as path parameters. See below a sample charge-url format;
https://myshop.com/payment/complete/{data-payment_reference}/{data-amount}
Obtain the passed path parameters, i.e reference and amount, and use them to validate the payment asynchronously. You can display a loader to indicate that verification is ongoing.
Depending on the nature of the response, you can redirect your customers to a payment complete success screen or a payment complete failure/pending screen on the frontend for feedback and a better user experience.
Verify Charge Customer
This service allows the merchant to verify the status and details of an executed process to determine if a transaction was indeed executed on the system using the pre-shared transaction reference number. The transaction reference number used is unique across the platform, so merchant aggregators checking for transaction status across multiple users should use this method.
Upon receipt of a request to the form action URL endpoint, you should verify the transaction by calling a method at: https://www.mypaga.com/checkout/transaction/verify with the following JSON content:
URL:
https://www.mypaga.com/checkout/transaction/verify
{
publicKey:<public_key>,
secretKey:<credential>,
paymentReference:<payment_reference>,
amount:<amount>,
currency:<currency>,
hash (optional): <SHA512 hash of public_key + password + payment_reference + amount + currency + hash_key>
}
- The values above should match the values sent in the form.
- The secretKey is your business organization credential.
- The hash value is optional, the hash_key for the hash is your pre-shared hash-key/hmac.
The response will be in the format:
{
status_code: <status code>
status_message: <status message>
}
- status_code 0 means success
Request Parameters
Argument Name | Type | Mandatory(M)/ Optional(0) | Description |
---|---|---|---|
publicKey | String | M | Business organization publicId.(https://developer-docs.paga.com/docs/overview#2-paga-authentication-details) (eg. B63F8C7E-D453-4B89-AC5C-40843AD3FA1E). |
secretKey | String | M | Business organization password/ apiKey on Paga’s platform |
amount | Double | M | The amount used to execute original transaction. |
currency | String | M | The currency of the operation, if being executed in a foreign currency |
paymentReference | String | M | A unique reference number provided by the business, identifying the transaction. This reference number will be preserved on the Paga platform to reconcile the operation across systems and will be returned in the response. |
Response Parameters
Argument Name | Type | Mandatory(M)/Optional(0) | Description |
---|---|---|---|
status_code | String | M | A status code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure |
status_message | String | M | A human-readable message describing the transaction result (success or fail) |
chargeId | String | M | The unique reference number code provided with the request |
Refund
This service allows merchants to fully or partially refund bill payment previously made to them by a customer. The refund specified may be in full or a partial amount. Full refunds may include or exclude customer fee.
Argument Name | Type | Mandatory(M)/Optional(0) | Description |
---|---|---|---|
publicKey | String | M | Business organization publicId.(https://developer-docs.paga.com/docs/overview#2-paga-authentication-details) (eg. B63F8C7E-D453-4B89-AC5C-40843AD3FA1E). |
secretKey | String | M | Business organization password/ apiKey on Paga’s platform |
amount | Number | M | this indicates the amount to be refunded. |
currency | String | M | The currency used in the transaction. |
paymentReference | String | M | This indicates the payment reference of the initial transaction |
includeCustomerFee | Boolean | M | Indicates whether the refund includes the customer fee (true) or not (false) |
reason | String | M | Human readable reason for refund. Reasons are limited to 300 characters and will be truncated if longer. |
DestinationBankAccount | DestinationBankAccountObject | M | This object contains details of the bank account the amount should be refunded to |
Service Method: refund
Argument name | Type | Mandatory(M)/Optional(0) | Description |
---|---|---|---|
Bank Key | String | M | The bank key identifies the bank to which the refund will be made. In order to get the list of supported banks and bank keys, execute the getBanks(Business API) operation defined in this document. Bank codes will not change though additional banks may be added to the list in the future. |
AccountNumber | String | M | The ten digit NUBAN bank account number for the account to which the refund will be made. This number should be a valid account number for the destination bank as specified by the Bank key parameter above. Executing operation will validate this number and if valid, return the account holder name as stored at the bank for this account. |
TransferRemarks | Strings | M | Additional bank transfer remarks that may appear on your bank statement record for this transaction. Remarks are limited to 50 characters and will be truncated if longer. |
URL:
https://mypaga.com/checkout/transaction/refund
{
"publicKey":"<publicKey>",
"secretKey":"<secretKey>",
"amount":200.00,
"currency":"NGN",
"paymentReference":"Jmgtbi",
"includeCustomerFee": false,
"reason": "Tran failed",
"destinationBankAccount":{
"bankKey": "40090E2F-7446-4217-9345-7BBAB7043C4C",
"accountNumber": "0000000000",
"transferRemarks": "refund"
}
{
"status_code": 0,
"status_message": "success",
"refundAmount": 500,
"paymentReference": "<paymentReference>"
"transactionReference": "<transactionReference>"
}
Arguement Name | Type | Description |
---|---|---|
status_code | Number | If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero). |
status_message | String | This indicates a human readable message. |
refundAmount | Number | This indicates the amount refunded |
paymentReference | String | This indicates the payment reference of the original transaction. |
transactionReference | String | A short/common transaction reference of the refund |
Process Flow
There are three types of users that can make use of the Paga Express Checkout:
- Full Authenticated Paga User
- Remember-Me User
- Unknown User
1. Fully Authenticated User
A Fully Authenticated user is someone who has an active Paga account and can log in to pay from existing, saved funding sources and their Paga account balance. Below is the process flow for a fully authenticated user.
Below is the process flow for Fully Authentication User:


When the user clicks on pay with paga button:


-
Enters email on the email field
If the user’s client device is not recognized by Paga, the user will be sent an SMS verification code to their registered phone and will be asked to enter it in the next step (this step is skipped if the user is using a recognized device): -
The user enters the device verification code
-
User is prompted to enter Paga password and click Login


The user now has full access to their funding sources and can select any of the funding sources with which to pay.


2. Remember-Me User
A remember-me user is a user that has previously saved their funding details by providing and verifying a remember-me phone number. The user can retrieve their saved funding sources by confirming a code sent to their “remember-me” phone number.
Below is the process flow for Remember-Me User.
- User clicks on paga button (pay with paga)


- The user enters the email address


- Then the user is directed to OTP page, to enter the code sent via SMS to use the payment details already stored with Paga Checkout.


The user now has access to multiple customer funding sources except Paga funding source. User can select on any of the funding sources to pay.


3. Unknown User
An unknown user is a user who hasn't registered on Paga nor setup a remember-me phone number. The user is required to enter the full details for their chosen card of bank account funding source for each payment.
Below is the process flow for Unknown User.
- User clicks on the paga button (pay with paga).


- User enters an email address


- User will get basic non-authenticated funding source options (card & bank account). User can then proceed to pay with any of the available options. User can also decide to click on Remember me on checkout, to save his/her payment details on Express Checkout.
Remember-me User
Below is the process flow for Remember me on checkout:
- The user enters an email address.


If the user wants to have their account details securely stored for the future, the user selects the remember-me toggle:


- User is required to enter phone number to save details for faster future payments --
Anywhere you see the Paga Checkout button, payment is just a click away. Simply
log in with your email address, enter the code that would be sent to your phone, and click 'Pay'.
Updated 7 months ago