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

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:

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



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