The Paga Developer Documentation

Welcome to the Paga API documentation. Our APIs and libraries are written to help you integrate payment in your products in matter of minutes. We have step by step guides to enable you get started.

Get Started    

Paga Checkout

Introduction

The Paga Checkout payment gateway provides an easy-to-integrate payments collection tool for any online merchant.
The tool supports multiple customer funding sources including:

  • Cards
  • Bank accounts
  • Paga
    The gateway renders easily and noninvasively on any device: desktop, tab, mobile.

Usage

Embed a “Pay with Paga” button into your page (button will be customizable and you will be able to use your own button/link etc.) by adding an HTML form tag containing a script element as follows:

<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="B63F8C7E-D453-4B89-AC5C-40843AD3FA1E"
    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-funding_sources="BANK,CARD,PAGA">
  </script>
</form>

Request Parameter

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

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 be defaulted 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

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/

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

Upon receipt of a request to the form action URL endpoint, you should verify the transaction by calling a method at: https://beta.mypaga.com/checkout/transaction/verify with the following JSON content:

{
  publicKey:<public_key>,
  secretKey:<password>,
  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 password.
  • 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

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

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.

URL:
   https://mypaga.com/checkout/transaction/verify
 
{
   "publicKey":"<publicId>",
   "secretKey":"<secret key>",
   "amount":500.00,
   "currency":"NGN",
   "paymentReference":"ereZzaeDNDNrtaabswdEIx"
}
curl --location --request POST 'https://beta.mypaga.com/checkout/transaction/verify' \
--header 'Content-Type: application/json' \
--data-raw '{
   "publicKey":"<publicId>",
   "secretKey":"<secretKey>",
   "amount":500.00,
   "currency":"NGN",
   "paymentReference":"ereZzaeDNDNrtaabswdEIx"
}'
{
    "status_code": 0,
    "status_message": "success",
    "chargeId": "ereZzaeDNDNrtaabswdEIx"
}

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

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

Updated 2 months ago

Paga Checkout


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.