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

📘

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

Response Parameters

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.

Service Method: refund

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

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:

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