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    

Merchant Service API

📘

NOTE

Please note that the hash parameter must contain the values of those params mentioned in the same order and the Hash key (the key given by Paga) hashed with SHS-512 algorithm ! (excluding the + sign)

Test base-url : https://beta.mypaga.com/
Live base-url: https://www.mypaga.com/

Overview
The following sections provide a more detailed documentation on the Merchant service operations.

1. Get Transaction Details

This service allows the merchant to verify the status and details of an executed process or 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.

Service Method: getTransactionDetails

Request Parameters

Argument Name

Type

Requirement

Description

referenceNumber

String

required

The unique transaction code returned as part of a previously executed transaction

URL:
    https://mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetails
 
Http Headers:
    principal:      publicId (merchant business publicId)
    credentials:    [email protected]
    hash:           hashed with SHA-512 algorithm of the appended params  
                containing(referenceNumber+ apikey)
    Content-Type:   application/json
 
Request Body:  
{  
   "referenceNumber":"242355"
}
{  
   "amount":1500,
   "dateTimeUTC":1564566479963,
   "errorMessage":null,
   "channel":"ONLINE",
   "foreignCurrency":null,
   "foreignCurrencyAmount":0,
   "transactionId":"SB6N9",
   "responseCode":0,
   "byAgent":false,
   "transactionType":"CUSTOMER_BILL_PAY",
   "referenceNumber":"242355",
   "exchangeRate":null,
   "currency":"NGN",
   "merchantReference":"441f4e10-712d-42d6-a5e3-cd97586ae389",
   "status":"SUCCESSFUL"
}

Response Parameters

Argument Name

Type

Requirement

Description

referenceNumber

String

Required

The unique reference number code provided with the request

status

String

Optional

The status of the transaction, if the transaction was found on the system. Note that any status other than UKNOWN means that the transaction was found on the system

merchantReference

String

Optional

The executing customer's reference number on the merchant's system as provided by the customer during transaction processing (eg. customer account number, invoice number etc.)

dateTimeUTC

dateTime

Optional

The transaction date and time provided in UTC standard time

transactionType

String

Optional

An enum representing the type of transaction executed

amount

Double

Optional

Amount used during the transaction. Note that this may be different from the amount remitted to the biller or actually charged to the customer depending on any fees included in the transaction.

transactionId

String

Optional

The common transaction id shared with all parties involved in the transaction

channel

String

Optional

The channel on which the transaction was executed

byAgent

Boolean

Optional

Whether the transaction was executed at an agent (true) or not (false)

currency

String

Optional

The currency used in the transaction, if foreign currency is used. Null otherwise

foreignCurrencyAmount

Double

Optional

The amount used in foreign currency

exchangeRate

Double

Optional

The exchange rate used, if a foreign currency is used. Null otherwise

responseCode

Integer

Optional

If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero).

errorMessage

String

Optional

Describes the status of the request. Whether it succeeds or fails

status

String

Optional

The status of the process, if the transaction was found on the system. Note that any status other than UKNOWN means that the process was found on the system

2. Get Transaction Details by Invoice Number

This service allows the merchant to verify the status and details of an executed process or to determine if a transaction was indeed executed on the system using the pre-shared transaction invoice number. The invoice number used is unique across the platform, so merchant aggregators checking for transactions status across multiple users should use this method.

ServiceMethod: getTransactionDetailsByInvoiceNumber

Request Parameters

Argument Name

Type

Requirement

Description

invoiceNumber

String

Required

The invoice number returned as part of a previously executed transaction

URL:
    https://mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetailsByInvoiceNumber
 
Http Headers:
    principal:      publicId (merchant business publicId)
    credentials:    [email protected]
    hash:           hashed with SHA-512 algorithm of the appended params  
                containing(invoiceNumber+ apikey)
    Content-Type:   application/json
 
Request Body:  
{  
   "invoiceNumber":"242355"
}
{  
   "amount":5000,
   "dateTimeUTC":1564576845597,
   "errorMessage":null,
   "channel":"ONLINE",
   "foreignCurrencyAmount":0,
   "transactionId":"TZHYT",
   "responseCode":0,
   "byAgent":false,
   "transactionType":"CUSTOMER_BILL_PAY",
   "referenceNumber":"1517775",
   "exchangeRate":0,
   "invoiceNumber":"242355",
   "currency":"NGN",
   "merchantReference":"a1ffcb7d-db75-4d8b-ac5c-739b64a95936",
   "status":"SUCCESSFUL"
}

Response parameters

Argument Name

Type

Requirement

Description

referenceNumber

String

Required

The unique reference number code provided with the request

amount

Double

Optional

Amount used during the transaction. Note that this may be different from the amount remitted to the biller or actually charged to the customer depending on any fees included in the transaction.

dateTimeUTC

DateTime

Optional

The transaction date and time provided in UTC standard time

errorMessage

String

Optional

Describes the status of the request. Whether it succeeds or fails

channel

String

Optional

The channel on which the transaction was executed

foreignCurrencyAmount

Double

Optional

The amount used in foreign currency

transactionId

String

Optional

The common transaction id shared with all parties involved in the transaction

responseCode

Integer

Optional

If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero).

byAgent

Boolean

Optional

Whether the transaction was executed at an agent (true) or not (false)

transactionType

String

Optional

An enum representing the type of transaction executed

invoiceNumber

String

Required

The invoice number returned as part of a previously executed transaction

currency

String

Optional

The currency used in the transaction, if foreign currency is used. Null otherwise

merchantReference

String

Optional

The executing customer's reference number on the merchant's system as provided by the customer during transaction processing (eg. customer account number, invoice number etc.)

status

String

The status of the process, if the transaction was found on the system. Note that any status other than UKNOWN means that the process was found on the system

3. Get Process Details

This service allows the merchant to verify the status and details of an executed process or to determine if a process was indeed executed on the system using the pre-shared process code. The process code used is unique by merchant so merchant aggregators checking for transactions stratus across multiple users should use the getTransactionDetails method.

Service Method: getProcessDetails

Request parameters

Argument Name

Type

Requirement

Description

processCode

String

Required

The process code returned as part of a previously executed transaction.

URL:
    https://mypaga.com/paga-webservices/merchant-rest/secured/getProcessDetails
 
Http Headers:
    principal:      publicId (merchant business publicId)
    credentials:    [email protected]
    hash:           hashed with SHA-512 algorithm of the appended params  
                containing(processCode+ apikey)
    Content-Type:   application/json
 
Request Body:  
{  
   "processCode":"242355"
}
{  
   "amount":100,
   "dateTimeUTC":1558316919037,
   "processCode":"1822231066919037",
   "errorMessage":null,
   "processType":"MERCHANT_PAYMENT",
   "customerAccount":"111-2140",
   "responseCode":0,
   "status":"SUCCESSFUL"
}

Response Parameters

Argument Name

Type

Requirement

Description

amount

Double

Optional

The case amount of the transaction. Note that this may be different from the amount remitted to the biller or actually charged to the customer depending on any fees included in the transaction.

dateTimeUTC

DateTime

Optional

The transaction date and time provided in UTC standard time

processCode

String

Required

The process code provided with the request

errorMessage

String

Optional

Describes the status of the request. Whether it succeeds or fails

processType

String

Optional

An enum representing the type of payment process executed

customerAccount

String

Optional

The executing customer's reference number on the merchant's system as provided by the customer during transaction processing (eg. customer account number, invoice number etc.)

responseCode

Integer

Optional

If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero).

status

String

Optional

The status of the process, if the transaction was found on the system. Note that any status other than UKNOWN means that the process was found on the system

4. Reconciliation Report

This service provides the mechanism for Paga to retrieve reconciled reports on the date range provided containing list of processes and transactions.

Service Method: reconciliationReport

Request Parameters

Argument Name

Type

Requirement

Description

periodStartDateTimeUTC

DateTime

Required

The datetime period for the reconciliation report to start

periodEndDateTimeUTC

DateTime

Required

The datetime period for the reconciliation report ends

URL:  
    https://mypaga.com/paga-webservices/merchant-rest/secured/reconciliationReport
 
Http Headers:
    principal: publicId (merchant business publicId)
    credentials: [email protected]
    hash: hashed with SHA-512 algorithm of the appended params          containing(periodEndDateTimeUTC + periodStartDateTimeUTC  + apikey)
    Content-Type: application/json
 
Request Body: 
{  
   "periodStartDateTimeUTC":"242355",
   "periodEndDateTimeUTC":"242355"
}
{  
   "errorMessage":null,
   "responseCode":0,
   "reconciliationItems":[  
      {  
         "pagaProcessCode":0,
         "description":null,
         "transactionDatetimeUTC":0,
         "referenceNumber":"123442",
         "amount":0,
         "status":"SUCCESSFUL"
      }
   ]
}

Response Parameters

Argument Name

Type

Requirement

Description

reconciliationItems

ReconciliationItem

Required

A list of reconciliation items

responseCode

Integer

Optional

If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero).

errorMessage

String

Optional

Describes the status of the request. Whether it succeeds or fails

ReconciliationItem

Argument Name

Type

Requirement

Description

pagaProcessCode

String

Optional

The process code provided with the request

status

String

Optional

The status of the process, if the transaction was found on the system. Note that any status other than UKNOWN means that the process was found on the system

description

String

Optional

Description for the process

transactionDatetimeUTC

DateTime

Optional

The transaction date and time provide in UTC standard time

referenceNumber

String

Optional

The executing customer's reference number on the merchant's system as provided by the customer during transaction processing (eg. customer account number, invoice number etc.)

amount

Double

Optional

The case amount of the transaction. Note that this may be different from the amount remitted to the biller or actually charged to the customer depending on any fees included in the transaction.

5. Get Foreign Exchange Rate

This service provides the mechanism to determine the exchange rate.

Service Method : getForeignExchangeRate

Request Parameters

Argument Name

Type

Requirement

Description

baseCurrency

CurrencyCode (restricted string)

Required

foreignCurrency

CurrencyCode (restricted string)

Required

URL:  
    https://mypaga.com/paga-webservices/merchant-rest/secured/getForeignExchangeRate
 
Http Headers:
    principal: publicId (merchant business publicId)
    credentials: [email protected]
    hash: hashed with SHA-512 algorithm of the appended params            containing(baseCurrency + foreignCurrency + apikey)
    Content-Type: application/json
 
Request Body: 
{  
  "baseCurrency":"242355",
  "foreignCurrency":"242355"
}
{  
   "sellRate":360.00044,
   "errorMessage":null,
   "foreignCurrency":"USD",
   "baseCurrency":"NGN",
   "responseCode":0,
   "buyRate":360.00044
}

Response Parameters

Argument Name

Type

Requirement

Description

baseCurrency

CurrencyCode (restricted string)

Required

foreignCurrency

CurrencyCode (restricted string)

Required

buyRate

Double

Required

The exchange rate at which Paga will buy the foreign currency in exchange for base currency

responseCode

Integer

Optional

If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero).

errorMessage

String

Optional

Describes the status of the request. Whether it succeeds or fails

sellRate

Double

Required

The rate at which Paga will sell the foreign currency in exchange for the base currency

6. Refund Bill Pay

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: refundBillPay

Request Parameters

Argument Name

Type

Requirement

Description

referenceNumber

String

Required

The unique reference number provided as part of the original transaction which identifies the transaction to be refunded.

includesCustomerFee

Boolean

Optional

Indicates whether the refund includes the customer fee (true) or not (false)

fullRefund

Boolean

Required

Indicates whether the refund is full or partial

refundAmount

Double

Required

Only provided for a partial refund, this indicates the amount to be refunded.

currency

CurrencyCode

Optional

The currency used in the transaction.

reason

String

Optional

Human readable reason for refund

customerPhoneNumber

String

Required

The phone number of the customer that performed the operation

URL:  
    https://mypaga.com/paga-webservices/merchant-rest/secured/refundBillPay
 
Http Headers:
    principal: publicId (merchant business publicId)
    credentials: [email protected]
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + refundAmount + customerPhoneNumber + apikey)
    Content-Type: application/json
 
Request Body: 
    { 
        "referenceNumber":"242355", "includesCustomerFee":"242355", 
        "fullRefund":"242355", "refundAmount":"242355", 
        "currency":"242355", "reason":"242355",
        "customerPhoneNumber":"08011111111"
    }
{  
   "exchangeRate":0,
   "refundTransactionId":"K03PD",
   "originalReferenceNumber":"BP-C_20190802114654120_1517873_F400G",
   "errorMessage":null,
   "currency":null,
   "responseCode":0,
   "refundAmount":3000
}

Response Parameters

Argument Name

Type

Requirement

Description

refundTransactionId

String

Required

A short/common transaction id of the refund which is shared with all parties. Note that this may not be unique over a long period of time

refundAmount

Double

Required

Amount refunded if the refund is partial

originalReferenceNumber

String

Required

Reference number of the original transaction as provided with the request

currency currency

CurrencyCode

Optional

The currency used in the refund transaction if a foreign currency is used

exchangeRate

Double

Optional

The exchange rate used if a foreign currency was used

errorMessage

String

Optional

Describes the status of the request. Whether it succeeds or fails

responseCode

Integer

Optional

If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero).

7. Get Transaction Details By Merchant Reference Number

This service allows the merchant to verify the status and details of an executed transaction or to determine if a transaction was indeed executed on the system using the merchant reference number. Merchant aggregators checking for transaction status across multiple users should use this method.

Service Method: getTransactionDetailsByMerchantReference

Request Parameter

Argument Name

Type

Requirement

Description

merchantReference

String

Mandatory

The Merchant unique transaction code used as part of a previously executed transaction

Sample Code

URL:
    https://mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetailsByMerchantReference
 
Http Headers:
    principal:      publicId (merchant business publicId)
    credentials:    [email protected]
    hash:           hashed with SHA-512 algorithm of the appended params  
                containing(merchantReference+ apikey)
    Content-Type:   application/json
 
Request Body: 
{
   "merchantReference":"conn-51452672"
}
{
    "responseCode": 0,
    "errorMessage": null,
    "invoiceNumber": null,
    "referenceNumber": "SCN-C_202004160844079_1524135_JG218",
    "status": "SUCCESSFUL",
    "merchantReference": "conn-51452672",
    "dateTimeUTC": 1587023047010,
    "transactionType": "CUSTOMER_SEND_CASH_TO_CUSTOMER",
    "amount": 8000.0,
    "transactionId": "JG218",
    "channel": "BUSINESS_API",
    "byAgent": false,
    "currency": "NGN",
    "exchangeRate": null,
    "foreignCurrencyAmount": null
}

Response Parameters

Argument Name

Type

Requirement

Description

responseCode

Integer

Mandatory

If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero)

errorMessage

String

Mandatory

Describes the status of the request. Whether it succeeds or fails

referenceNumber

String

Mandatory

The unique reference number code provided with the request

status

String

Mandatory

The status of the transaction, if the transaction was found on the system. Note that any status other than UKNOWN means that the transaction was found on the system

merchantReference

String

Mandatory

The executing customer's reference number on the merchant's system as provided by the customer during transaction processing (eg. customer account number, invoice number etc.)

dateTimeUTC

datetime

Optional

The transaction date and time provided in UTC standard time

transactionType

String

Mandatory

An enum representing the type of transaction executed

amount

Double

Mandatory

Amount used during the transaction. Note that this may be different from the amount remitted to the biller or actually charged to the customer depending on any fees included in the transaction.

transactionId

String

Mandatory

The common transaction id shared with all parties involved in the transaction

channel

String

Mandatory

The channel on which the transaction was executed

byAgent

Boolean

Mandatory

Whether the transaction was executed at an agent (true) or not (false)

currency

String

Optional

The currency used in the transaction, if foreign currency is used. Null otherwise

exchangeRate

Double

Optional

The exchange rate used, if a foreign currency is used. Null otherwise

foreignCurrencyAmount

Double

Optional

The amount used in foreign currency

Updated 11 months ago

Merchant Service API


Suggested Edits are limited on API Reference Pages

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