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    

Business API Operations

Below are the details of the services exposed via the Paga Business services 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/


1. Register Customer

The Register Customer operation allows third Parties to register customers on Paga. New customers will be contacted to setup their authentication credentials.

Service Method: registerCustomer

Request Parameters

Argument Name

Type

Required(Yes/No)

Description

referenceNumber

String

Yes

A unique reference number for this request. This same reference number will be returned in the response

customerFirstName

String

Yes

The first name of the customer

customerLastName

String

Yes

The last name of the customer

customerPhoneNumber

String

Yes

The phone number of the new customer. This number must not belong to an existing registered customer

customerEmail

String

Yes

The email of the new customer

customerDateOfBirth

String

Yes

Birth date of the customer

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/registerCustomer 
 
Http Headers:
    principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of business organization)
    credentials: password1
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + customerPhoneNumber + customerFirstName+ customerLastName + hashkey)
    Content-Type: application/json
Request Body : 
{
   "referenceNumber":"2348979834916",
   "customerFirstName":"customerFirstName",
   "customerLastName":"customerLastName",
   "customerPhoneNumber":"+2348189321305",
   "customerEmail":"[email protected]",
   "customerDateOfBirth":"1989-10-02"
}
{
    "responseCode": 0,
    "message": "Customer account registered. Customer should dial *242# or visit http://beta.mypaga.com to activate account",
    "referenceNumber": "2348979834916",
    "pagaAccountNumber": "2958312888"
}

Response Parameters

Argument Name

Type

Required(Yes/No)

Description

responseCode

String

Yes

Status code of the response. 0 indicates a successful response

message

String

Yes

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

referenceNumber

String

Yes

The same unique reference number provided in the request

pagaAccountNumber

String

Yes

The Paga account number fo the newly registered account.

2. Register Customer With KYC

An operation for businesses to register a new customer on Paga along with additional customer details necessary to KYC the customer

Service Method: registerCustomerWithKYC

Request Parameters

Argument Name

Type

Required(Yes/No)

Description

customer

Object

Yes

The new customer’s details

customerAccountPhoto

File

No

The customer’s account photograph. Must be a passport-style photo of the customer. Must be one of image types (). Image sze be ⇐ 500kb

customerIdPhoto

File

No

The customer’s identification photograph. Must be one of image types (). Image sze be ⇐ 500kb

Customer Object Fields

Argument Name

Type

Required(Yes/No)

Description

referenceNumber

String

Yes

A unique reference number for this request. This same reference number will be returned in the response

customerPhoneNumber

String

Yes

The phone number of the new customer. This number must not belong to an existing registered customer

customerEmail

String

Yes

The email of the new customer

customerFirstName

String

Yes

The first name of the customer

customerLastName

String

Yes

The last name of the customer

customerDateOfBirth

String

Yes

Birth date of the customer

customerGender

String

Yes

The gender of the new customer. Must be either (FEMALE, MALE)

customerAddress

Object

No

The address of the new customer

customerAddress.country

String

No

The country of the address. Must be provided if address is provided

customerAddress.region

String

No

The region/state of the address. Must be provided if address is provided

customerAddress.county

String

No

The county/zone of the address.

customerAddress.city

String

No

The city of the address.

customerAddress.localGovernmentArea

String

No

The local government area/district of the address.

customerAddress.streetAddress

String

No

The street address of the address

customerAddress.postalCode

String

No

The postal code of the address

customerAddress.landmark

String

No

A landmark for the the address

customerAddress.freeformAddress

String

No

A free-form description of the address

customerMaritalStatus

String

No

The marital status of the new customer. Must be one of (SINGLE, MARRIED, DIVORCED)

customerPreferredLanguageISOCode

String

No

The ISO 639-1 code of the new customer’s preferred language. Must be a valid ISO 639-1 code. See: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

customerReferredByPhoneNumber

String

No

The phone number of the person who referred the new customer

customerReferredByFirstName

String

No

The first name of the person who referred the new customer

customerReferredByLastName

String

No

The last name of the person who referred the new customer

String

No

The type of identification captured for the new customer. Must be one of (DRIVERS_LICENCE, NATIONAL_ID, PASSPORT, VOTERS_CARD)

customerIdNumber

String

No

The number of the identification captured for the new customer. This must be provided if customerIdType is provided

customerIdExpirationDate

String

No

The expiration date of the identification captured for th new customer. Format must be YYYY-MM-DD

optinForWalletSavings

Boolean

No

If the customer opted in for transactional savings wallet

customerSupplementaryDetails

Object

No

A name/value map of additional customer details captured

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/registerCustomer 
 
Http Headers:
    principal: publicId (business organization pulbicId)
    credentials: [email protected] (business organization password)
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + customerPhoneNumber + customerFirstName + customerLastName + hashkey)

Content-Type: multipart/form-data; boundary="TEIJNCQ5bVQ6ocfU4BSpKzMEZ2nN7t"; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=customer; filename=file
Content-Type: application/json
Accept: application/json
 

Request Body: 
    { 
   "referenceNumber":"b1d6162d-587f-4508-a2ed-232d4af61b26",
   "customerPhoneNumber":"+251923139709",
   "customerFirstName":"John",
   "customerLastName":"Doe",
   "customerEmail":"[email protected]",
   "customerDateOfBirth":"1985-05-13T00:00:00",
   "customerGender":"MALE",
   "customerAddress":{ 
      "country":"Nigeria",
      "region":"Abia",
      "localGovernmentArea":"Arochukwu",
      "streetAddress":"2 Isimkpu Road",
      "landmark":"Green and White Walls",
      "freeformAddress":"2 Isimkpu Road, Arochukwu, Arochukwu LGA, Abia State, Nigeria"
   },
   "customerMaritalStatus":"SINGLE",
   "customerPreferredLanguageISOCode":"en",
   "customerReferredByFirstName":"Beste",
   "customerReferredByLastName":"Buddy",
   "customerReferredByPhoneNumber":"+251985434361",
   "customerIdType":"NATIONAL_ID",
   "customerIdNumber":"12345567890",
   "customerIdExpirationDate":"2023-01-03T00:00:00",
   "optinForWalletSavings":false,
   "customerSupplementaryDetails":{ 
      "NextOfKinLastName":"Doe",
      "NextOfKinFirstName":"James",
      "NextOfKinType":"Brother",
      "NextOfKinPhoneNumber":"+251934230001"
   }
}

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=customerAccountPhoto; filename=passportPhoto.jpg
Content-Type: image/jpeg
<!-- Image Data...-->
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=customerIdPhoto; filename=idPhoto.jpg
Content-Type: image/jpeg
<!-- Image Data...-->
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
{
  "responseCode" : 0,
  "message" : "Customer account registered. Customer should dial *242# or visit http://localhost:8080 to activate account. Id photo under review. User's transaction limit will be increased if approved",
  "referenceNumber" : "b1d6162d-587f-4508-a2ed-232d4af61b26",
  "pagaAccountNumber" : "0863580891"
}

**Response Parameters

Argument Name

Type

Required(Yes/No)

Description

responseCode

Integer

Yes

Status code of the response. 0 indicates a successful response

message

String

Yes

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

referenceNumber

String

Yes

The same unique reference number provided in the request

pagaAccountNumber

String

Yes

The Paga account number fo the newly registered account.

3. Register customer Account Photo

An operation for a business to upload an account photo for a customer account that it has registered. This is useful in case the account photo is not available or the upload fails or is rejected during the initial registration attempt.

Service Method: registerCustomerAccountPhoto

Request Parameters

Parameter Name

Type

Required(Yes/No)

Description

referenceNumber

String

Yes

A unique reference number for this request. This same reference number will be returned in the response

customerPhoneNumber

String

Yes

The phone number of the customer. This number must belong to an existing customer that was registered

POST /paga-webservices/business-rest/secured/registerCustomerAccountPhoto HTTP/1.1
Accept: application/json
principal: FE1F9B7F-BBCE-46A0-9685-0DCAE93AC222
credentials: Password1
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + customerPhoneNumber + hashkey)

Content-Type: multipart/form-data; boundary="hqAXjGenC7xagi5giYJYhNo11DSMh9yK"; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=customer; filename=file
Content-Type: application/json

{ 
   "referenceNumber":"8dbd4a62-a5d4-4607-8e51-18338c43efc3",
   "customerPhoneNumber":"+251943292465"
}

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=customerAccountPhoto; filename=passportPhoto.jpg
Content-Type: image/jpeg
<!-- Image Data...-->
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
{
  "responseCode" : 0,
  "message" : "Photo upload failed: User account photo has already been set",
  "referenceNumber" : null
}

Response Parameters

Parameter Name

Type

Required(Yes/No)

Description

responseCode

Integer

Yes

Status code of the response. 0 indicates a successful response

message

String

Yes

Human-readable description about the response e.g. 'Success' for a successful response

referenceNumber

String

No

The same unique reference number provided in the request

4. Register customer Identification

An operation for a business to upload an identification photo for a customer account that it has registered.

Service Method: registerCustomerIdentification

Request Parameters

Parameter Name

Type

Required(Yes/No)

Description

customer

Object

Yes

The customer’s details

customerIdPhoto

File

Yes

Photograph of the customer identification document Must be one of image types (). Image sze be ⇐ 500kb

Customer Fields

Parameter Name

Type

Required(Yes/No)

Description

referenceNumber

String

Yes

A unique reference number for this request. This same reference number will be returned in the response

customerPhoneNumber

String

Yes

The phone number of the customer. This number must belong to an existing customer the YOU registered

customerIdType

String

Yes

The type of identification captured for the new customer. Must be one of (DRIVERS_LICENCE, NATIONAL_ID, PASSPORT, VOTERS_CARD)

customerIdNumber

String

Yes

The number of the identification captured for the new customer. This must be provided if customerIdType is provided

customerIdExpirationDate

String

Yes

The expiration date of the identification captured for the new customer. Format must be YYYY-MM-DD

POST /paga-webservices/business-rest/secured/registerCustomerIdentification HTTP/1.1
Accept: application/json
principal: FE1F9B7F-BBCE-46A0-9685-0DCAE93AC222
credentials: Password1;
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + customerPhoneNumber + customerIdType + customerIdNumber + customerIdExpirationDate + hashkey)

Content-Type: multipart/form-data; boundary="lluzJAuxmYVmaRo2AaNM0_d8uy7qebIE3"; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=customer; filename=file
Content-Type: application/json

{"referenceNumber":"323776ad-ec3c-4851-a3da-571fbc205f1c","customerPhoneNumber":"+251943292465","customerIdType":"NATIONAL_ID","customerIdNumber":"12345567890","customerIdExpirationDate":"2023-01-03T00:00:00"}
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=customerIdPhoto; filename=idPhoto.jpg
Content-Type: image/jpeg
<!-- Image Data...-->
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
{
  "responseCode" : 0,
  "message" : "Photo upload failed: User id photo has already been set",
  "referenceNumber" : "323776ad-ec3c-4851-a3da-571fbc205f1c
}

Response Parameters

Parameter Name

Type

Required(Yes/No)

Description

responseCode

Integer

Yes

Status code of the response. 0 indicates a successful response

message

String

Yes

Human-readable description about the response e.g. 'Success' for a successful response

referenceNumber

String

Yes

The same unique reference number provided in the request

5. Money Transfer

The Money Transfer operation enables an integrated 3rd party to utilize the Paga platform to transfer funds from a variety of sources to another party. The funds transfer may be executed from the accounts of the integrated 3rd party themselves, or on behalf of another customer with the appropriate authentication. The source of funds may be the sender's Paga account or another source that the sender has pre-registered on the Paga platform.

Service Method: moneyTransfer

Request Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

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

amount

double

M

The amount of money to transfer to the recipient

currency

String

O

The currency of the operation, if being executed in a foreign currency

destinationAccount

String

M

The account identifier for the recipient receiving the money transfer. This account identifier may be a phone number, account nickname, or any other unique account identifier supported by the Paga platform. If destinationBank is specified, this is the bank account number

destinationBank

String

O

For money transfers to a bank account, this is the destination bank code

sendWithdrawalCode

boolean

O

If the cash is being sent on behalf of the third party itself (i.e. sender principal is null), then this indicates whether confirmation messages for funds sent to non Paga customers will include the withdrawal code in the message (true) or omit it (false). If false, then the withdrawal code will be returned in the withdrawalCode response parameter. For funds sent to Paga customers, the funds are deposited directly into the customer's account so no withdrawal code is necessary. Defaults to true

sourceOfFunds

string

O

The name of a source account for funds. If null, the source sender's Paga account will be used as the funding source.

transferReference

string

O

The name of a source account for funds. If null, the source sender's Paga account will be used as the funding source.

suppressRecipientMessage

boolean

O

Whether to prevent sending an SMS to the recipient of the money transfer. This can be used in cases where the business wishes to perform their own messaging. Defaults to false, meaning that messages are NOT suppressed.

locale (not presently in use)

String

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

alternateSenderName

String

O

If the cash is being sent on behalf of the third party itself (i.e. sender principal is null), then an alternative name-of-sender can be specified here for use in the message sent to the money transfer recipient. This field is ignored if money transfer is sent on behalf of another user. This can be 16 characters in length.

holdingPeriod

Integer

O

The number of days with which the recipient's KYC must have before it is reverted back to the sender. It is only valid if the minKYCLevel is set and it's default to 120 days. If minKYCLevel is set and the recipient?s KYC is below it, then this will be the number of days it should wait to meet the minKYC Level provided. If the target KYC is not upgraded within this period the fund will be returned back to the sender?s account.

miniRecipentKYCLevel

String

O

The minimum target KYC level the money transfer transaction recipient's paga account must have, can be one of KYC1, KYC2, and KYC3

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/moneyTransfer 
 
Http Headers:
    principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of business organization)
    credentials: password1
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + destinationAccount + hashkey)
    Content-Type: application/json
 
Request Body : 
    {  
   "referenceNumber":"mer-1566227777706",
   "amount":3000.0,
   "currency":"NGN",
   "destinationAccount":"07037299643",
   "destinationBank":"",
   "withdrawalCode":false,
   "sourceOfFunds":"PAGA",
   "transferReference":"mer-1566227777706",
   "suppressRecipientMsg":true,
   "locale":"NG",
   "alternateSenderName":"",
   "minRecipientKYCLevel":"KYC1",
   "holdingPeriod":31
}
{  
   "referenceNumber":"2345",
   "withdrawalCode":null,
   "exchangeRate":null,
   "fee":50,
   "receiverRegistrationStatus":"REGISTERED",
   "currency":"NGN",
   "message":"You have successfully sent N10,000.00 to 12345. Paga Txn ID: MG3TZ. Thank you for using Paga!",
   "transactionId":"MG3TZ",
   "responseCode":0
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

responseCode

String

M

A response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure

referenceNumber

String

M

The same reference number that was passed in the request

withdrawalCode

String

O

If funds are sent on behalf of the organization itself, and the sendWithdrawalCode request parameter is false, this will include the withdrawal code for funds sent to a non Paga customer. For funds sent to Paga customers, the funds are deposited directly into the customer's account so no withdrawal code is necessary.

transactionId

string

O

If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction

Fee

double

O

If successful, the fee/tariff charged to the sender for the money transfer to this recipient

receiverRegistrationStatus

string

O

If successful, the registration status of the receiver of the funds. This will be either REGISTERED (for funds sent to a registered Paga customer), or UNREGISTERED (for funds sent to a non-Paga customer.

currency

double

O

If the transaction request was specified in a foreign currency, this is the local (system base) currency to which value is converted for processing

exchangeRate

double

O

If the transaction request was specified in a foreign currency, this is the exchange rate which is used in converting the funds to the local (system base) currency

Message

string

M

A human-readable message describing the transaction result (success or fail)

 

6. Airtime Purchase

The Airtime Purchase operation enables an integrated 3rd party to utilize the Paga platform to purchase airtime for any phone number on any of the major networks. The purchase can be funded by the integrated 3rd party themselves, or on behalf of another customer with the appropriate authentication. The source of funds may be the purchaser's Paga account or another source that the sender has pre-registered on the Paga platform.

Service Method: airtimePurchase

 
Request Parameters

Parameter Name

Type

Mandatory (M) / Optional (O)

Description

referenceNumber

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

Amount

double

M

The amount of airtime to purchase

Currency

double

O

The currency of the operation, if being executed in a foreign currency

destinationPhoneNumber

string

O

The phone number for which airtime is being purchased. If null, and ­­­­Principal is specified, then the airtime will be purchased for the phone number of the purchaserPrincipal. Must be provided if the purchaserPrincipal is null

purchaserPrincipal

string

O

The authentication principal for the user purchasing airtime if the airtime is being purchased on behalf of a user. If null, the airtime will be processed from the 3rd parties own account.

purchaserCredentials

string

O

The authentication credentials for the user purchasing the airtime if the airtime is being purchased on behalf of a user.

sourceOfFunds

String

O

The name of a source account for funds. If null, the source purchaser's Paga account will be used as the funding source.

Locale (not presently in use)

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

mobileOperatorPublicId

String

M

The mobile operator
unique public
organization id. Note, This is returned from the previous call (Get Mobile Operators)

isSuppressRecipientMessages

Boolean

O

Whether to prevent sending an SMS to the recipient of the money transfer. This can be used in cases where the business wishes to perform their own messaging. Defaults to false, meaning that messages are NOT suppressed.

isDataBundle

Boolean

O

This specifies whether it's a data purchase

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/airtimePurchase 
 
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount+ destinationPhoneNumber + hashkey)
    Content-Type: application/json
 
Request Body 
    { 
        "referenceNumber": "",
        "mobileOperatorPublicId": "", 
        "amount": "",
        "currency": "", 
        "destinationPhoneNumber": "", 
        "purchaserPrincipal": "", 
        "purchaserCredentials": "", 
        "sourceOfFunds": "",
        "locale": "",                             
        "isSuppressRecipientMessages": ""
    }
{  
   "referenceNumber":"+251911314250",
   "message":"Airtime purchase request made successfully",
   "responseCode":0,
   "transactionId":"At34",
   "fee":50.0,
   "currency":null,
   "exchangeRate":null
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

responseCode

string

M

A response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure

referenceNumber

string

M

The same reference number that was passed in the request

transactionId

string

O

If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction

Fee

double

O

If successful, the fee/tariff charged to the sender for the airtime purchase

currency

double

O

If the transaction request was specified in a foreign currency, this is the local (system base) currency to which value is converted for processing

exchangeRate

double

O

If the transaction request was specified in a foreign currency, this is the exchange rate which is used in converting the funds to the local (system base) currency

Message

string

M

A human-readable message describing the transaction result (success or fail)

 

7. Merchant Payment

The Merchant Payment operation enables an integrated 3rd party to utilize the Paga platform to make payments to registered merchants. The purchase can be funded by the integrated 3rd party themselves, or on behalf of another customer with the appropriate authentication. The source of funds may be the purchaser's Paga account or another source that the sender has pre-registered on the Paga platform.

Service Method: merchantPayment

 
Request Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

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

amount

double

M

The amount of the merchant payment

currency

double

O

The currency of the operation, if being executed in a foreign currency

merchantAccount

string

M

The account number identifying the merchant (eg. merchant Id, UUID). Note,
This is returned from the previous call (Get Merchants)

merchantReferenceNumber

string

M

The account/reference number identifying the customer on the merchant's system

merchantService

Array(string[])

O

The list of merchant service codes specifying which of the merchant's services are being paid for

purchaserPrincipal

string

O

The authentication principal for the user paying the merchant if the payment is being made on behalf of a user. If null, the airtime will be processed from the 3rd parties own account.

purchaserCredentials

string

O

The authentication credentials for the user paying the merchant if the payment is being made on behalf of a user.

sourceOfFunds

string

O

The name of a source account for funds. If null, the source purchaser's Paga account will be used as the funding source.

locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

paymentChannel

string

O

This allows the organization to send the payment channel the transaction occurred.

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/merchantPayment 
 
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + merchantAccount + merchantReferenceNumber + hashkey)
    Content-Type: application/json
 
Request Body:
   {  
   "merchantReferenceNumber":"1234567891",
   "amount":1500.0,
   "merchantAccount":"A3878DC1-F07D-48E7-AA59-8276C3C26647",
   "referenceNumber":"mer-1568801867898",
   "currency":"NGN",
   "merchantService":[  
      "ACCACC101"
   ],
   "locale":"NG"
}
{
    "responseCode": 0,
    "message": "You have successfully paid N600.00 to  for acct 13B5041B-7143-46B1-9A88-F355AD7EA1EC. Token: 217938588. Paga TxnID: DWV0P",
    "referenceNumber": "liveTest111000",
    "merchantTransactionReference": "217938588",
    "transactionId": "DWV0P",
    "currency": "NGN",
    "exchangeRate": null,
    "fee": 0.0,
    "commissionEarned": 12.0,
    "integrationStatus":"SUCCESSFUL",  
    "additionalProperties": {
        "unitType": "",
        "totalPayment": "",
        "debtBefore": "",
        "customerAccountNumber": "",
        "units": "",
        "debtPayment": "",
        "paymentDate": "",
        "meterSerial": "",
        "customerName": "",
        "receiptNumber": "",
        "vat":"",
        "token": ""
    }
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

currency

double

O

If the transaction request was specified in a foreign currency, this is the local (system base) currency to which value is converted for processing

exchangeRate

double

O

If the transaction request was specified in a foreign currency, this is the exchange rate which is used in converting the funds to the local (system base) currency

Fee

double

O

If successful, the fee/tariff charged to the sender for the merchant payment item

merchantTransactionReference

string

O

A code returned by the merchant in response to the transaction, typically intended for the payer (eg. A confirmation code, token, voucher number, receipt/invoice number etc.)

Message

string

M

A human-readable message describing the transaction result (success or fail)

referenceNumber

string

M

The same reference number that was passed in the request

responseCode

string

M

A response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure

transactionId

string

O

If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction

additionalProperties

Object

O

This contains additional properties returned from merchant.
Note , this might vary across merchants.

integrationStatus

String

M

Indicates the actual status of the downstream integration call (SUCCESSFUL, FAILED, INCONCLUSIVE).

8. Validate Deposit to Bank

The Validate Deposit To Bank operation enables an integrated 3rd party to pre-validate a potential deposit to bank operation using similar parameters that would be provided for the actual deposit to bank operation. This will return a result indicating whether the actual deposit to bank operation using the same parameters is likely to be successful or not, and if not, why not. This will also validate the bank account number for the bank provided and return the account holder name for that account as stored at the bank. This will also return any fees that would be charged as part of the actual deposit to bank operation.

Service Method: validateDepositToBank

 
Request Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

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

amount

double

M

The amount of money to deposit to the destination bank and bank account provided. Your Paga account must contain sufficient funds to cover this amount plus any fees.

currency

double

O

The currency of the operation, if being executed in a foreign currency. The currency must be one of the currencies supported by the platform. For supported currencies, check with Paga integration operations support.

destinationBankUUID

string

M

The Paga bank UUID identifying the bank to which the deposit will be made. In order to get the list of supported banks and bank UUIDs, execute the getBanks operation defined in this document. Bank codes will not change though additional banks may be added to the list in the future.

destinationBankAccountNumber

string

M

The ten digit NUBAN bank account number for the account to which the deposit will be made. This number should be a valid account number for the destination bank as specified by the destinationBankCode parameter above. Executing operation will validate this number and if valid, return the account holder name as stored at the bank for this account.

recipientPhoneNumber

string

O

The mobile phone number of the recipient of the deposit to bank transaction. Either one or both of this parameter and the recipientEmail parameter must be provided. If this parameter is provided, this operation will validate that it is a valid phone number.

recipientMobileOperatorCode

string

O

Ignored if recipientPhoneNumber parameter is not provided. This describes the mobile operator that the recipientPhoneNumber belongs to. If recipientPhoneNumber is provided, but this parameter is not, a default mobile operator will selected based on the phone number pattern, but this may not be correct due to number portability of mobile phone numbers and may result in delayed or failed delivery of any SMS messages to the recipient.

recipientEmail

string

O

The email address of the recipient of the deposit to bank transaction. Either one or both of this parameter and the recipientPhoneNumber parameter must be provided. If this parameter is provided, this operation will validate that it is a valid email address format.

recipientName

string

O

The name of the recipient. This parameter is currently bot validated.

locale (not presently in use)

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/validateDepositToBank 
 
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + destinationBankUUID + destinationBankAccountNumber  + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "6278333993", "amount": "", "currency": "", 
        "destinationBankUUID": "","destinationBankAccountNumber": "", 
        "recipientPhoneNumber": "",  "recipientMobileOperatorCode": "", 
        "recipientEmail": "", "recipientName": "", "locale": ""
    }
{  
   "referenceNumber":"6278333993",
   "destinationAccountHolderNameAtBank":"Test Customer",
   "fee":50,
   "vat":2.5,
   "message":null,
   "responseCode":0
}

 
Response Parameter

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

responseCode

string

M

A response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure

referenceNumber

string

M

The same reference number that was passed in the request

Fee

double

O

If successful, the fee/tariff that would be charged from your Paga account for the deposit to bank to this recipient

destinationAccountHolderNameAtBank

string

O

If successful, this will return the name of the account holder for the destination bank and bank account provided as it is reported by the destination bank.

message

string

M

A human-readable message describing the transaction result (success or fail)

9. Deposit To Bank

The Deposit To Bank operation enables an integrated 3rd party to utilize the Paga platform to deposit funds to any bank account. The funds will be deposited from the businesses Paga account to the bank and bank account specified in the operation parameters.

Service Method: depositToBank

 
Request Parameter

Parameter Name

Type

Mandatory(O) / Optional(O)

Description

referenceNumber

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

amount

double

M

The amount of money to deposit to the destination bank and bank account provided. Your Paga account must contain sufficient funds to cover this amount plus any fees.

currency

string

O

The currency of the operation, if being executed in a foreign currency. The currency must be one of the currencies supported by the platform. For supported currencies, check with Paga integration operations support.

destinationBankUUID

string

M

The Paga bank UUID identifying the bank to which the deposit will be made. In order to get the list of supported banks and bank UUIDs, execute the getBanks operation defined in this document. Bank codes will not change though additional banks may be added to the list in the future.

destinationBankAccountNumber

string

M

The ten digit NUBAN bank account number for the account to which the deposit will be made. This number should be a valid account number for the destination bank as specified by the destinationBankCode parameter above. Executing operation will validate this number and if valid, return the account holder name as stored at the bank for this account.

recipientPhoneNumber

string

O

The mobile phone number of the recipient of the deposit to bank transaction. Either one or both of this parameter and the recipientEmail parameter must be provided. If this parameter is provided, this operation will validate that it is a valid phone number.

recipientMobileOperatorCode

string

O

Ignored if recipientPhoneNumber parameter is not provided. This describes the mobile operator that the recipientPhoneNumber belongs to. If recipientPhoneNumber is provided, but this parameter is not, a default mobile operator will selected based on the phone number pattern, but this may not be correct due to number portability of mobile phone numbers and may result in delayed or failed delivery of any SMS messages to the recipient.

recipientEmail

string

O

The email address of the recipient of the deposit to bank transaction. Either one or both of this parameter and the recipientPhoneNumber parameter must be provided. If this parameter is provided, this operation will validate that it is a valid email address format.

recipientName

string

O

The name of the recipient. This parameter is currently bot validated.

alternateSenderName

string

O

In notifications sent to the recipient, your business display name (if set), or business name (if display name not set) is included. If you wish notifications to indicate the deposit to bank as coming from an alternate name, you may set the alternate name in this parameter. This parameter length is limited to 20 characters and will be truncated if longer.

suppressRecipientMessage

boolean

O

If this field is set to true, no notification message (SMS or email) will be sent to the recipient. IF omitted or set to false, an email or SMS will be sent to recipient as described above.

Remarks

string

O

Additional bank transfer remarks that you may wish to appear on your bank statement record for this transaction. Remarks are limited to 30 characters and will be truncated if longer.

locale (not presently in use)

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/depositToBank 
 
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + destinationBankUUID + destinationBankAccountNumber  + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "62789233993", "amount": "5000.00", "currency": "NGN", 
        "destinationBankUUID": "","destinationBankAccountNumber": "", 
        "recipientPhoneNumber": "",  "recipientMobileOperatorCode": "", 
        "recipientEmail": "", "recipientName": "", "suppressRecipientMessage": "", 
        "remarks": "", "locale": ""
    }
{  
   "referenceNumber":"62789233993",
   "exchangeRate":null,
   "destinationAccountHolderNameAtBank":"Test Customer",
   "fee":50,
   "vat":2.5,
   "currency":"NGN",
   "message":"Successfully deposited N5,000.00 to bank account ******8830.        Transaction Id: RP658.",
   "transactionId":"RP658",
   "responseCode":0
}

 
Response Parameter

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

responseCode

string

M

A response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure

referenceNumber

string

M

The same reference number that was passed in the request

transactionId

string

O

If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction

Fee

double

O

If successful, the fee/tariff that would be charged from your Paga account for the deposit to bank to this recipient

destinationAccountHolderNameAtBank

string

O

If successful, this will return the name of the account holder for the destination bank and bank account provided as it is reported by the destination bank.

Currency

string

O

If the transaction request was specified in a foreign currency, this is the local (system base) currency to which value is converted for processing

exchangeRate

double

O

If the transaction request was specified in a foreign currency, this is the exchange rate which is used in converting the funds to the local (system base) currency

Message

string

M

A human-readable message describing the transaction result (success or fail)

 

10. Account Balance

The Account Balance operation enables an integrated 3rd party to utilize the Paga platform to check the balance of a Paga account or any other account type pre-registered on the Paga platform, which support balance inquiries. The account balance check may be executed for the account(s) of the integrated 3rd party themselves, or on behalf of another customer with the appropriate authentication.

Service Method: accountBalance

 
Request Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

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

accountPrincipal

string

O

The authentication principal for the user who's balance is being inquired, if the inquiry is being made on behalf of a user. If null, the balance inquiry will be processed from the 3rd parties own account.

accountCredentials

string

O

The authentication credentials for the user who's balance is being inquired, if the inquiry is being made on behalf of a user.

sourceOfFunds

string

O

The name of a source account on which to check the balance. If null, the Paga account balance with be retrieved.

Locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/accountBalance
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber +  hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "", "accountPrincipal": "", 
        "sourceOfFunds": "", "accountCredentials": "", "locale": ""
    }
{  
   "referenceNumber":"+251911314250",
   "message":"",
   "responseCode":0,
   "totalBalance":"100.0",
   "availableBalance":50.0,
   "currency":null,
   "balanceDateTimeUTC":null
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

responseCode

string

M

A response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure

referenceNumber

string

M

The same reference number that was passed in the request

totalBalance

double

M

The total balance in the account

availableBalance

double

M

A current balance in the account available for use

Currency

double

M

The currency in which the balances are reported

Message

string

M

A human-readable message describing the transaction result (success or fail)

balanceDateTimeUTC

datetime

M

The date and time stamp for which the balance shown is retrieved

 

11. Transaction History

The Transaction History operation enables an integrated 3rd party to utilize the Paga platform to check the transaction history of their Paga account between selected date ranges. The account balance check may be executed for the account(s) of the integrated 3rd party themselves, or on behalf of another customer with the appropriate authentication. Transactions results are limited to them most recent 10,000 results

Service Method: transactionHistory

Parameter Name

Type

Mandatory(M) / Optional(0)

Description

referenceNumber

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

accountPrincipal

string

O

The authentication principal for the user who's transaction history is being retrieved, if the inquiry is being made on behalf of a user. If null, the balance inquiry will be processed from the 3rd parties own account.

accountCredentials

string

O

The authentication credentials for the user who's transaction history is being retrieved, if the inquiry is being made on behalf of a user.

startDateUTC

dateTime

M

The start date of the interval for which transaction history results should be returned. The results are inclusive of this date and it should include hour, minute and second values in addition to the date.

endDateUTC

dateTime

M

The start date of the interval for which transaction history results should be returned. The results are exclusive of this date and it should include hour, minute and second values in addition to the date.

Locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/transactionHistory 
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "", accountPrincipal: "", 
        "accountCredentials":  "",  "startDateUTC": "", 
        "endDateUTC": "", "locale": ""
    }
{
    "referenceNumber":"+251911314250", "message":"Success",
    "responseCode":0, "recordCount": 0, 
    items: 
        [{
            "itemNumber": "", "dateUTC": "",
            "description": "", "amount": "", "status": "", 
            "referenceNumber": "+251911314250", "transactionId": "At34",
            "currency":null, "exchangeRate":null 
        }], 
    "currency": ""
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

string

M

The same reference number that was passed in the request

recordCount

int

M

The number of transaction history records retrieved

currency

double

M

The currency in which the balances are reported

responseCode

string

M

A response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure

Items

TransactionHistoryItem

M

A list of retrieved transaction history items

Message

string

M

A human-readable message describing the transaction result (success or fail)

 
TransactionHistoryItem

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

itemNumber

int

M

The sequential item number count (starts at 1)

dateUTC

dateTime

M

The transaction date in UTC time standard

Description

string

M

The transaction description

Amount

double

M

The base transaction amount

Status

string

M

The transaction completion status

transactionId

string

O

If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction

referenceNumber

string

O

If applicable, the original reference number for the transaction provided by the third-party initiating the transaction – note that many transactions may not have been executed by a third party and will not have a reference number

 

12. Recent Transaction History

The Recent Transaction History operation enables an integrated 3rd party to utilize the Paga platform to check the last 5 transactions on their Paga account. The account balance check may be executed for the account(s) of the integrated 3rd party themselves or on behalf of another customer with the appropriate authentication.

Service Method: recentTransactionHistory


**Request Parameters**

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

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

accountPrincipal

string

O

The authentication principal for the user who's transaction history is being retrieved, if the inquiry is being made on behalf of a user. If null, the balance inquiry will be processed from the 3rd parties own account.

accountCredentials

string

O

The authentication credentials for the user who's transaction history is being retrieved, if the inquiry is being made on behalf of a user.

locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/recentTransactionHistory
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "", accountPrincipal: "", "accountCredentials":  "",  "locale": ""
    }
{
    "referenceNumber":"+251911314250", "message":"Success",
    "responseCode":0, "recordCount": 0, 
    items: 
        [{
            "itemNumber": "", "dateUTC": "",
            "description": "", "amount": "", "status": "", 
            "referenceNumber": "+251911314250", "transactionId": "At34",
            "currency":null, "exchangeRate":null 
        }], 
    "currency": ""
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

string

M

The same reference number that was passed in the request

recordCount

int

M

The number of transaction history records retrieved

currency

double

M

The currency in which the balances are reported

responseCode

string

M

A response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure

Items

TransactionHistoryItem

M

A list of retrieved transaction history items

Message

string

M

A human-readable message describing the transaction result (success or fail)

 
TransactionHistoryItem

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

itemNumber

int

M

The sequential item number count (starts at 1)

dateUTC

dateTime

M

The transaction date in UTC time standard

Description

string

M

The transaction description

Amount

double

M

The base transaction amount

Status

string

M

The transaction completion status

transactionId

string

O

If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction

referenceNumber

string

O

If applicable, the original reference number for the transaction provided by the third-party initiating the transaction – note that many transactions may not have been executed by a third party and will not have a reference number

 

13. Get Merchants

The Get Merchants operation enables an integrated 3rd party to utilize the Paga platform to obtain a list of registered merchants on the Paga platform, typically for use in parameterizing the merchant payment operation.

Service Method: getMerchants

 
Request Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

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

Locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/getMerchants
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "", "locale": ""
    }
{  
   "referenceNumber":"14563672",
   "message":"Success",
   "merchants":[  
      {  
         "displayName":"",
         "name":"",
         "description":"",
         "uuid":""
      }
   ],
   "responseCode":0
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

responseCode

string

M

A response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure

referenceNumber

string

M

The same reference number that was passed in the request

Message

string

M

A human-readable message describing the transaction result (success or fail)

merchants

Merchant

M

The list of available registered merchants on the Paga platform

 
Merchant

Parameter Name

Type

Mandatory(O) / Optional(O)

Description

Name

string

M

The merchant name

Uuid

string

M

A unique identifier which can be used in requests to identify the merchant

Id

string

O

A short merchant id which can be used in requests to identify the merchant

Code

string

O

A merchant code which can be used in requests to identify the merchant

14. Get Merchant Services

The Get Merchants Services operation enables an integrated 3rd party to utilize the Paga platform to obtain a list of registered services and service details for a given registered merchant on the Paga platform, typically for use in parameterizing the merchant payment operation.

Service Method: getMerchantServices

 
Request Parameters

Parameter Name

Type

Mandatory(O) / Optional(O)

Description

referenceNumber

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

merchantPublicId

string

M

The identifier which uniquely identifies the merchant on the Paga platform. i.e Merchant Public Id. This is returned from the previous call (Get Merchants) *

Locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/getMerchantServices
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + merchantPublicId + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "", "merchantPublicId" : "", "locale": ""
    }
{
    "referenceNumber":"+251911314250", 
    "message":"Success",
    "responseCode":0, 
    "services": 
        [{
            "name": "", "price": "", "shortCode": "", "code": ""
        }] 
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

responseCode

string

M

A response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure

referenceNumber

string

M

The same reference number that was passed in the request

Message

string

M

A human-readable message describing the transaction result (success or fail)

Services

MerchantService

M

The list of available merchant services for the provided merchant id

 
MerchantService

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

Name

string

M

The service name

Code

string

M

The service product code

Price

double

O

The service price

shortCode

string

O

A short code for the service

15. Get Banks

The Get Banks operation enables an integrated 3rd party to utilize the Paga platform to obtain a list of available banks on the Paga platform, typically for use in parameterizing the deposit to bank operation.

Service Method: getBanks

 
Request Parameters

Parameter

Type

Mandatory (M) / Optional(O)

Description

referenceNumber

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

locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/getBanks
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "", "locale": ""
    }
{
    "referenceNumber":"+251911314250", 
    "message":"Success",
    "responseCode":0, 
    "bank": 
        [{"name": "", "uuid": "" }] 
}

 
Request Parameters

Parameter

Type

Mandatory (M) / Optional(O)

Description

responseCode

string

M

A response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure

referenceNumber

string

M

The same reference number that was passed in the request

message

string

M

A human-readable message describing the transaction result (success or fail)

bank

Bank

M

The list of available banks on the Paga platform

 

16. Get Operation Status

The Get Operation Status operation allows an integrated 3rd party to check on the status of a previous operation using the operation's reference number.

Service Method: getOperationStatus

 
Request Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

string

M

The reference number provided with the original operation for which the status is being queried

Locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/getOperationStatus
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "", "locale": ""
    }
{  
   "referenceNumber":"62789233993",
   "transactionStatus":"SUCCESSFUL",
   "fee":50,
   "message":"Transaction completed successfully",
   "transactionId":"RP658",
   "responseCode":0
}

 
Response Parameter

Parameter Name

Type

Mandatory(M) / Optional

Description

referenceNumber

string

M

The same reference number that was passed in the request

Fee

double

O

The fee associated with the original transaction, if any

transactionId

string

O

If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction

responseCode

string

M

A response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure

Message

string

M

A human-readable message describing the transaction result (success or fail)

17. Get Mobile Operators

The Get Mobile Operators operation enables an integrated 3rd party to utilize the Paga platform to obtain a list of available mobile operators on the Paga platform, typically for use in parameterizing the various operations of the business api.

Service Method: getMobileOperators

 
Request Parameters

Parameter

Type

Mandatory(M) / Optional(O)

Description

referenceNumber

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

Locale

string

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/getMobileOperators
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "11314250", "locale": ""
    }
{
    "referenceNumber":"11314250", 
    "message":"Success",
    "responseCode":0, 
    "mobileOperator": 
        [{"name": "", " mobileOperatorCode ": "" }] 
}

 
Response Parameters

Parameter

Type

Mandatory (M) / Optional(O)

Description

referenceNumber

string

M

The same reference number that was passed in the request

responseCode

string

M

A response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure

message

string

M

A human-readable message describing the transaction result (success or fail)

mobileOperator

MobileOperator

M

The list of available banks on the Paga platform

 
MobileOperator

Parameter

Type

Mandatory (M) / Optional(O)

Description

Name

string

M

The bank name

mobileOperatorCode

string

M

A unique identifier which should be used to identify the bank in requests

18. Onboard Merchant

The Onboard Merchant operation, allows Aggregator Organizations to create sub organizations on the paga platform.

Service Method: onboardMerchant

🚧

This operation is only available to Merchant aggregators on the Paga platform.

 
Request Parameters

Parameter Name

Type

Mandatory(M) / Optional

Description

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

merchantExternalId

string

M

A unique reference number provided by the business, identifying the specific Organization account to be created.

merchantInfo

json

M

Containing information about the Organization to be created

integration

json

M

Contains information about the type of notification to be used for notification of received payments.

Merchant Info

Parameter Name

Type

Mandatory(M)/Optional(O)

LegalEntity

json

M

LegalEntityRepresentative

json

M

AdditionalParameters

json

M

LegalEntity

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

addressCountry

String

O

Sub merchant country

addressZip

String

O

Sub merchant ZIP address code

name

String

M

Sub Merchant name

description

String

O

addressLine1

String

O

addressLine2

String

O

addressState

String

O

Sub Merchant state

addressCity

String

O

Sub Merchant city

LegalEntityRepresentative

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

firstName

String

M

The legal representative first name.

phone

String

M

The legal representative phone number

lastName

String

M

The legal representative last name.

email

String

M

The legal representative email address.

dateOfBirth

Date

M

The legal representative date of birth

AdditionalParameters

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

displayName

String

M

Preferred Merchant display name.

establishedDate

String

M

Date the merchant organisation was established

websiteUrl

String

O

Merchant website URL

🚧

Integration Types

There are 2 integration types. EMAIL_NOTIFICATION and MERCHANT_NOTIFICATION_REVERSE_API. Each integration type requires a different set of parameters. See The Merchant Notification API Document for more details on the Reverse Notification API.

"integration": {
        "type" : "EMAIL_NOTIFICATION",
        "financeAdminEmail": "[email protected]"
   }
"integration": {
        "type" : "MERCHANT_NOTIFICATION_REVERSE_API",
        "callbackUrl": "https://mywebhook.com/callback",
        "username": "username",
        "password": "password"
   }
URL:
    https://mypaga.com/paga-webservices/business-rest/secured/onboardMerchant
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + merchantExternalId + name + phone + email + hashkey)
    Content-Type: application/json
 
Request Body:
    {
    "reference": "52a54d49-6971-401b-9aa0-95cb5b23ddf2",
    "merchantExternalId": "27791fe3-47b9-4080-8d3f-20a37e81bb24",
    "merchantInfo": {
          "legalEntity": {
                "name" : "Example Sub Merchant 1",
                "description": "business",
                "addressLine1": "35 Yabas Road",
                "addressLine2": "Somewhere",
                "addressCity": "Lagos",
                "addressState": "Lagos",
                "addressZip": "xxxx",
                "addressCountry": "Nigeria"
      },
      "legalEntityRepresentative": {
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "1995-05-02T07:45:37.726+03:00",
            "phone": "+2348188215379",
            "email": "[email protected]"
      },
        "additionalParameters": {
        "establishedDate": "2014-03-13T19:53:37.726+03:00",
        "websiteUrl": "http://www.example.com",
        "displayName": "Life is Good"
      }
   },
   "integration": {
        "type" : "EMAIL_NOTIFICATION",
        "financeAdminEmail": "[email protected]"
   }
}
{
  "responseCode": 0,
  "onboardingUpdate": {
    "status": "succeeded",
    "credentials": {
      "merchantPublicId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXXX",
      "merchantSecretKey": "xxxxxxxxxxxxxxxx",
      "merchantHmac": "b3c15a3b8xxxxxxxxc06c86e2394xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0fc374d898aed5a3a86xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx9e67c1c969f1b8"
    }
  }
}

 
Response Parameters

Parameter Name

Type

Mandatory(M) / Optional(O)

Description

responseCode

string

M

A response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure

onboardingUpdate

json

M

The same reference number that was passed in the request

message

string

M

A human-readable message describing the transaction result (success or fail)

19. Bulk Money Transfer

The Bulk Money Transfer operation enables an integrated 3rd party to utilize the Paga platform to execute the money transfer operation described above to multiple recipients simultaneously. This is limited to 300 payment items per bulk operation.

Service Method: moneyTransferBulk

 

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

moneyTransferItems

MoneyTransferItem

M

A list of the money transfer items included in this bulk operation

bulkReferenceNumber

String

O

A unique bulk 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

MoneyTransferItem

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

referenceNumber

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

amount

double

M

The amount of money to transfer to the recipient

destinationAccount

String

M

The account identifier for the recipient receiving the money transfer. This account identifier may be a phone number, account nickname, or any other unique account identifier supported by the Paga platform

currency

Currency

O

The currency of the operation, if being executed in a foreign currency

destinationBank

String

O

For money transfers to a bank account, this is the destination bank code

senderPrincipal

String

O

The authentication principal for the user sending money if the money is being sent on behalf of a user. If null, the money transfer will be processed from the 3rd parties own account.

senderCredentials

String

O

The authentication credentials for the user sending money if the money is being sent on behalf of a user.

transferReference

String

O

Additional transfer-specific reference information that may be required for transfer processing

sourceOfFunds

String

O

The name of a source account for funds. If null, the source sender's Paga account will be used as the funding source.

sendWithdrawalCode

boolean

O

If the cash is being sent on behalf of the third party itself (i.e. sender principal is null), then this indicates whether confirmation messages for funds sent to non Paga customers will include the withdrawal code in the message (true) or omit it (false). If false, then the withdrawal code will be returned in the withdrawalCode response parameter. For funds sent to Paga customers, the funds are deposited directly into the customer's account so no withdrawal code is necessary. Defaults to true

suppressRecipientMessage

boolean

O

Whether to prevent sending an SMS to the recipient of the money transfer. This can be used in cases where the business wishes to perform their own messaging. Defaults to false, meaning that messages are NOT suppressed.

alternateSenderName

String

O

If the cash is being sent on behalf of the third party itself (i.e. sender principal is null), then an alternative name-of-sender can be specified here for use in the message sent to the money transfer recipient. This field is ignored if money transfer is sent on behalf of another user. This can be 16 characters in length.

minRecipentKYCLevel

String

O

The minimum target KYC level the money transfer transaction recipient's Paga account must have, can be one of KYC1, KYC2, and KYC3

holdingPeriod

Numeric

O

The number of days with which the recipient's KYC must have before it is reverted back to the sender. It is only valid if the minKYCLevel is set and it's default to 120 days. If minKYCLevel is set and the recipient's KYC is below it, the this will be the number of days it should wait to meet the minKYC Level provided. If the target KYC is not upgraded within this period the fund will be returned back to th sender's account.

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/moneyTransferBulk 
 
Http Headers
    principal: publicId
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing((referenceNumber + amount + destinationAccount) of the first item in the MoneyTransfer items list + no of total items count + hashkey)
    Content-Type: application/json
 
Request Body 
    {
       "bulkReferenceNumber": "bulk-1571745578618",
            "moneyTransferItems": [{                                                                                                                                                            "referenceNumber": "4356738930303",
                              "amount": "3000",
                              "currency": "NGN",
                              "destinationAccount": "08030408527",
                              "destinationBank": "",
                              "transferReference": "1571745578617",
                              "sourceOfFunds": "PAGA",
                              "sendWithdrawalCode": false,
                              "suppressRecipientMessage": true,
                              "minRecipentKYCLevel": "KYC1",
                              "holdingPeriod": 31   
        },
        {
        "referenceNumber": "ref-1571745578617",
        "amount": "3000",
        "currency": "NGN",
        "destinationAccount": "08060075922",
        "destinationBank": "",
        "transferReference": "1571745578617",
        "sourceOfFunds": "PAGA",
        "sendWithdrawalCode": false,
        "suppressRecipientMessage": true,
        "minRecipentKYCLevel": "KYC1",
        "holdingPeriod": 31
        }]
    }
{  
   "bulkReferenceNumber":"1232452525",
   "message":"Successful bulk money transfer. 1 of 1 items successful",
   "results":[  
      {  
         "referenceNumber":"2345",
         "withdrawalCode":null,
         "exchangeRate":null,
         "fee":50,
         "receiverRegistrationStatus":"REGISTERED",
         "currency":"AED",
         "message":"You have successfully sent N3,000.00 to 12345. Paga Txn ID: MSGHB. Thank you for using Paga!",
         "transactionId":"MSGHB",
         "responseCode":0
      }
   ],
   "responseCode":0
}

20. Merchant Account Details

This Operation allows Businesses to query account details for customer for bill pay

Service Method: getMerchantAccountDetails

Request Parameters

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

referenceNumber

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

merchantAccount

String

M

The Organization public ID for which you want to get customer account details

merchantReferenceNumber

String

M

Customer account Number at the Organization

merchantServiceProductCode

String

O

Merchant service code specifying which of the merchant's services are being paid for

Sample Code

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/getMerchantAccountDetails 
 
Http Headers
    principal: publicId
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing((referenceNumber
                  + merchantAccount
                  + merchantReferenceNumber
                  + merchantServiceProductCode + hashkey)
    Content-Type: application/json
 
Request Body
{ 
"referenceNumber":"jone1578908284333",
"merchantAccount":"13B5041B-7143-46B1-9A88-F355AD7EA1EC",
"merchantReferenceNumber":"07085173842",
"merchantServiceProductCode":"MY003"
}
{
   "responseCode":0,
   "message":"Success",
   "customerName":"Mock User",
   "phoneNumber":null,
   "accountNumber":"Mock User",
   "details":{
      "First Name":"Mock",
      "details":"Mock User",
      "Last Name":"User",
      "customerName":"Mock User",
      "merchantAccountDetails":"Mock User"
   }
}

21. Dispense Cash

The dispense cash operation enables an integrated Affiliates to utilize the Paga platform to dispense cash out of Paga for a customer.

Service Method: dispenseCash

Request Parameters

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

referenceNumber

String

M

A unique reference
number provided by the
agent, 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

locale

String

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

customerPhoneNumber

String

M

Customer phone number

amount

Double

M

The amount of money to be cashed out by the customer

withdrawalCode

String

M

The Unique Code that the customer will supply for dispense cash

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/dispenseCash
 
Http Headers
    principal: publicId
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing((referenceNumber
                  + customerPhoneNumber
                  + amount
                  + withdrawalCode + hashkey)
    Content-Type: application/json
 
Request Body

{
   "referenceNumber":"13451172",
   "locale":"",
   "customerPhoneNumber":"07040090090",
   "amount":2000.0,
   "withdrawalCode":"99377"
}
{
   "responseCode":0,
   "message":"Withdraw cash request from customer phone number 07037299643 for amount ₦5000.0",
   "transactionId":"B26R1",
   "agentCommission":50.0,
   "customerName":"Peter Philips"
}

Response Parameters

Parameter Name

Mandatory(M)/Optional(O)

Description

Type

responseCode

M

A response code indicating the
status (success/fail) of the operation on Paga platform and if failure, indicating
reason for failure.

Strig

message

M

A human-readable message describing the transaction
result (success or fail)

String

transactionId

M

If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction

String

agentCommission

M

Agent commission for
this transaction

Double

customerName

M

Paga registered
customer name using
the provided phone
number

String

22. Transaction Status

The Transaction Status operation allows businesses to check on the status of a previous operation.

Service Method: transactionStatus

Request Parameters

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

referenceNumber

String

M

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

locale

String

O

The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard

URL:
    https://mypaga.com/paga-webservices/business-rest/secured/transactionStatus
 
Http Headers
    principal: publicId
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
    Content-Type: application/json
 
Request Body
{  
   "referenceNumber":"TEST-452671-673",
   "locale":"en"
}
{
   "responseCode":0,
   "message":null,
   "referenceNumber":"TEST-452671-673",
   "currency":"NGN",
   "status":"SUCCESSFUL",
   "transactionReference":"BPS-A_20201123142801278_260668151_M3YBK",
   "transactionId":"M3YBK",
   "transactionType":"AGENT_BILL_PAY_FROM_STOCK",
   "dateUTC":1606138081277,
   "amount":600.0,
   "merchantTransactionReference":"2179385887899937738"
}

Response Parameters

Parameter Name

Type

Mandatory(M)/Optional(O)

Description

responseCode

Number

M

A response code indicating the
status (success/fail) of the operation on Paga platform and if failure, indicating
reason for failure.

message

String

O

Describes the status of the request when a transaction fails.

referenceNumber

String

M

The unique reference number code provided with the request

currency

String

O

The currency of the operation, if being executed in a foreign currency.

status

String

M

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

transactionReference

String

M

A unique transaction reference identifying the transaction on the Paga System. this may be provided by the merchant in response to a transaction submission in order to provide a reference to Paga for the transaction.

transactionId

String

M

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

transactionType

String

M

An enum representing the type of transaction executed

dateUTC

datetime

O

The transaction date and time provided in UTC standard time

amount

Double

M

The amount of the value of the transaction.

merchantTransactionReference

String

M

A code returned by the merchant in response to the transaction, typically intended for the payer (eg. A confirmation code, token, voucher number, receipt/invoice number etc.)

additionalProperties

Object

O

This contains additional properties returned from merchant.
Note , this might vary across merchants.

Updated 14 days ago

Business API Operations


Suggested Edits are limited on API Reference Pages

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