Business API Operations

Paga Business API operation provides all relevant endpoints needed to complete a debit transaction on the partner's account. If your use case includes Money Transfer to Paga or Bank Account, Cashout at Agent, Value added service (Bill payment, Airtime and Mobile Data) etc.

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/

Please ensure you have whitelisted your IP address by following the instruction provided here before using any of the endpoints provided in Business API Operations


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 NameTypeRequired(Yes/No)Description
referenceNumberStringYesA unique reference number for this request. This same reference number will be returned in the response
customerFirstNameStringYesThe first name of the customer
customerLastNameStringYesThe last name of the customer
customerPhoneNumberStringYesThe phone number of the new customer. This number must not belong to an existing registered customer
customerEmailStringYesThe email of the new customer
customerDateOfBirthStringYesBirth date of the customer
URL:
    https://www.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 NameTypeRequired(Yes/No)Description
responseCodeStringYesStatus code of the response. 0 indicates a successful response
messageStringYesDescribes the status of the request. Whether it succeeds or fails
referenceNumberStringYesThe same unique reference number provided in the request
pagaAccountNumberStringYesThe 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 NameTypeRequired(Yes/No)Description
customerObjectYesThe new customer’s details
customerAccountPhotoFileNoThe customer’s account photograph. Must be a passport-style photo of the customer. Must be one of image types (). Image sze be ⇐ 500kb
customerIdPhotoFileNoThe customer’s identification photograph. Must be one of image types (). Image sze be ⇐ 500kb

Customer Object Fields

Argument NameTypeRequired(Yes/No)Description
referenceNumberStringYesA unique reference number for this request. This same reference number will be returned in the response
customerPhoneNumberStringYesThe phone number of the new customer. This number must not belong to an existing registered customer
customerEmailStringYesThe email of the new customer
customerFirstNameStringYesThe first name of the customer
customerLastNameStringYesThe last name of the customer
customerDateOfBirthStringYesBirth date of the customer
customerGenderStringYesThe gender of the new customer. Must be either (FEMALE, MALE)
customerAddressObjectNoThe address of the new customer
customerAddress.countryStringNoThe country of the address. Must be provided if address is provided
customerAddress.regionStringNoThe region/state of the address. Must be provided if address is provided
customerAddress.countyStringNoThe county/zone of the address.
customerAddress.cityStringNoThe city of the address.
customerAddress.localGovernmentAreaStringNoThe local government area/district of the address.
customerAddress.streetAddressStringNoThe street address of the address
customerAddress.postalCodeStringNoThe postal code of the address
customerAddress.landmarkStringNoA landmark for the the address
customerAddress.freeformAddressStringNoA free-form description of the address
customerMaritalStatusStringNoThe marital status of the new customer. Must be one of (SINGLE, MARRIED, DIVORCED)
customerPreferredLanguageISOCodeStringNoThe 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
customerReferredByPhoneNumberStringNoThe phone number of the person who referred the new customer
customerReferredByFirstNameStringNoThe first name of the person who referred the new customer
customerReferredByLastNameStringNoThe last name of the person who referred the new customer
StringNoThe type of identification captured for the new customer. Must be one of (DRIVERS_LICENCE, NATIONAL_ID, PASSPORT, VOTERS_CARD)
customerIdNumberStringNoThe number of the identification captured for the new customer. This must be provided if customerIdType is provided
customerIdExpirationDateStringNoThe expiration date of the identification captured for th new customer. Format must be YYYY-MM-DD
optinForWalletSavingsBooleanNoIf the customer opted in for transactional savings wallet
customerSupplementaryDetailsObjectNoA name/value map of additional customer details captured
URL:
    https://www.mypaga.com/paga-webservices/business-rest/secured/registerCustomer 
 
Http Headers:
	principal: publicId (business organization pulbicId)
	credentials: p@ssword1 (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 NameTypeRequired(Yes/No)Description
responseCodeIntegerYesStatus code of the response. 0 indicates a successful response
messageStringYesDescribes the status of the request. Whether it succeeds or fails
referenceNumberStringYesThe same unique reference number provided in the request
pagaAccountNumberStringYesThe 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 NameTypeRequired(Yes/No)Description
referenceNumberStringYesA unique reference number for this request. This same reference number will be returned in the response
customerPhoneNumberStringYesThe 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 NameTypeRequired(Yes/No)Description
responseCodeIntegerYesStatus code of the response. 0 indicates a successful response
messageStringYesHuman-readable description about the response e.g. 'Success' for a successful response
referenceNumberStringNoThe 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 NameTypeRequired(Yes/No)Description
customerObjectYesThe customer’s details
customerIdPhotoFileYesPhotograph of the customer identification document Must be one of image types (). Image sze be ⇐ 500kb

Customer Fields

Parameter NameTypeRequired(Yes/No)Description
referenceNumberStringYesA unique reference number for this request. This same reference number will be returned in the response
customerPhoneNumberStringYesThe phone number of the customer. This number must belong to an existing customer the YOU registered
customerIdTypeStringYesThe type of identification captured for the new customer. Must be one of (DRIVERS_LICENCE, NATIONAL_ID, PASSPORT, VOTERS_CARD)
customerIdNumberStringYesThe number of the identification captured for the new customer. This must be provided if customerIdType is provided
customerIdExpirationDateStringYesThe 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 NameTypeRequired(Yes/No)Description
responseCodeIntegerYesStatus code of the response. 0 indicates a successful response
messageStringYesHuman-readable description about the response e.g. 'Success' for a successful response
referenceNumberStringYesThe 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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberStringMA 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
amountdoubleMThe amount of money to transfer to the recipient
currencyStringOThe currency of the operation, if being executed in a foreign currency
destinationAccountStringMThe 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
destinationBankStringOFor money transfers to a bank account, this is the destination bank code
sendWithdrawalCodebooleanOIf 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
sourceOfFundsstringOThe name of a source account for funds. If null, the source sender's Paga account will be used as the funding source.
transferReferencestringOThe name of a source account for funds. If null, the source sender's Paga account will be used as the funding source.
suppressRecipientMessagebooleanOWhether 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)StringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
alternateSenderNameStringOIf 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.
holdingPeriodIntegerOThe 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.
miniRecipentKYCLevelStringOThe minimum target KYC level the money transfer transaction recipient's paga account must have, can be one of KYC1, KYC2, and KYC3
URL:
    https://www.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 NameTypeMandatory(M) / Optional(O)Description
responseCodeStringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
referenceNumberStringMThe same reference number that was passed in the request
withdrawalCodeStringOIf 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.
transactionIdstringOIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
FeedoubleOIf successful, the fee/tariff charged to the sender for the money transfer to this recipient
receiverRegistrationStatusstringOIf 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.
currencydoubleOIf the transaction request was specified in a foreign currency, this is the local (system base) currency to which value is converted for processing
exchangeRatedoubleOIf 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
MessagestringMA human-readable message describing the transaction result (success or fail)

 

6. Airtime and Data Purchase

The Airtime and Data Purchase operation enables an integrated 3rd party to utilize the Paga platform to purchase airtime and Data 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 NameTypeMandatory (M) / Optional (O)Description
referenceNumberstringMA 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
AmountdoubleMThe amount of airtime to purchase
CurrencydoubleOThe currency of the operation, if being executed in a foreign currency
destinationPhoneNumberstringOThe 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
purchaserPrincipalstringOThe 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.
mobileOperatorPublicIdstringMThis is the UUID of the mobile operator you want to purchase. It can be fetched from Get Mobile Operator Endpoint
purchaserCredentialsstringOThe authentication credentials for the user purchasing the airtime if the airtime is being purchased on behalf of a user.
sourceOfFundsStringOThe 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)stringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
mobileOperatorServiceIdStringOThis is the serviceID returned on getDataBundleByOperator endpoint. This identifies the data service you're purchasing.
Note, This is returned from the previous call (Get Data Bundle by Mobile Operators)
isSuppressRecipientMessagesBooleanOWhether 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.
isDataBundleBooleanOThis specifies whether it's a data purchase
URL:
    https://www.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": "00000024",
        "mobileOperatorPublicId": "42419156-DD57-4737-8373-20678CD9AA29",
        "mobileOperatorServiceId": "70",
        "amount": "100",
        "currency": "NGN", 
        "destinationPhoneNumber": "08063332187",
        "locale": "", 						      
        "isSuppressRecipientMessages": true,
        "isDataBundle":true
    }
{  
   "referenceNumber":"+251911314250",
   "message":"Airtime purchase request made successfully",
   "responseCode":0,
   "transactionId":"At34",
   "fee":50.0,
   "currency":null,
   "exchangeRate":null
}

 
Response Parameters

Parameter NameTypeMandatory(M) / Optional(O)Description
responseCodestringMA response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure
referenceNumberstringMThe same reference number that was passed in the request
transactionIdstringOIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
FeedoubleOIf successful, the fee/tariff charged to the sender for the airtime purchase
currencydoubleOIf the transaction request was specified in a foreign currency, this is the local (system base) currency to which value is converted for processing
exchangeRatedoubleOIf 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
MessagestringMA 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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberstringMA 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
amountdoubleMThe amount of the merchant payment
currencydoubleOThe currency of the operation, if being executed in a foreign currency
merchantAccountstringMThe account number identifying the merchant (eg. merchant Id, UUID). Note,
This is returned from the previous call (Get Merchants)
merchantReferenceNumberstringMThe account/reference number identifying the customer on the merchant's system
merchantServiceArray(string[])OThe list of merchant service codes specifying which of the merchant's services are being paid for
purchaserPrincipalstringOThe 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.
purchaserCredentialsstringOThe authentication credentials for the user paying the merchant if the payment is being made on behalf of a user.
sourceOfFundsstringOThe name of a source account for funds. If null, the source purchaser's Paga account will be used as the funding source.
localestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
paymentChannelstringOThis allows the organization to send the payment channel the transaction occurred.
URL:
    https://www.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 NameTypeMandatory(M) / Optional(O)Description
currencydoubleOIf the transaction request was specified in a foreign currency, this is the local (system base) currency to which value is converted for processing
exchangeRatedoubleOIf 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
FeedoubleOIf successful, the fee/tariff charged to the sender for the merchant payment item
merchantTransactionReferencestringOA 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.)
MessagestringMA human-readable message describing the transaction result (success or fail)
referenceNumberstringMThe same reference number that was passed in the request
responseCodestringMA response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure
transactionIdstringOIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
additionalPropertiesObjectOThis contains additional properties returned from merchant.
Note , this might vary across merchants.
integrationStatusStringMIndicates the actual status of the downstream integration call (SUCCESSFUL, FAILED, INCONCLUSIVE).

📘

Merchant payment endpoint is only simulated for DSTV in our test environment. To carry out payment for other merchant services, you are to use our live environment.

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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberstringMA 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
amountdoubleMThe 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.
currencydoubleOThe 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.
destinationBankUUIDstringMThe 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.
destinationBankAccountNumberstringMThe 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.
recipientPhoneNumberstringOThe mobile phone number of the recipient of the deposit to bank transaction.
recipientMobileOperatorCodestringOIgnored 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.
recipientEmailstringOThe email address of the recipient of the deposit to bank transaction.
recipientNamestringOThe name of the recipient. This parameter is currently bot validated.
locale (not presently in use)stringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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 NameTypeMandatory(M) / Optional(O)Description
responseCodestringMA response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure
referenceNumberstringMThe same reference number that was passed in the request
FeedoubleOIf successful, the fee/tariff that would be charged from your Paga account for the deposit to bank to this recipient
destinationAccountHolderNameAtBankstringOIf 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.
messagestringMA human-readable message describing the transaction result (success or fail)

📘

The publicId of Paga can also be used in /validateDepositToBank endpoint. In this case, it is treated as a validating a money transfer to a paga account (as opposed to money transfer to bank): On all environments, the Paga own Bank Public Id should be: AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA. For more information about Paga's PublicId consult the getBanks endpoint.

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 NameTypeMandatory(O) / Optional(O)Description
referenceNumberstringMA 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
amountdoubleMThe 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.
currencystringOThe 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.
destinationBankUUIDstringMThe 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.
destinationBankAccountNumberstringMThe 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.
recipientPhoneNumberstringOThe 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.
recipientMobileOperatorCodestringOIgnored 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.
recipientEmailstringOThe 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.
recipientNamestringOThe name of the recipient. This parameter is currently bot validated.
alternateSenderNamestringOIn 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.
suppressRecipientMessagebooleanOIf 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.
RemarksstringOAdditional 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)stringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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,
   "sessionId": null
}

 
Response Parameter

Parameter NameTypeMandatory(M) / Optional(O)Description
responseCodestringMA response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure
referenceNumberstringMThe same reference number that was passed in the request
transactionIdstringOIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
FeedoubleOIf successful, the fee/tariff that would be charged from your Paga account for the deposit to bank to this recipient
destinationAccountHolderNameAtBankstringOIf 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.
CurrencystringOIf the transaction request was specified in a foreign currency, this is the local (system base) currency to which value is converted for processing
exchangeRatedoubleOIf 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
MessagestringMA human-readable message describing the transaction result (success or fail)
sessionIdstringMSessionId provided for the transaction.

 

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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberstringMA 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
accountPrincipalstringOThe 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.
accountCredentialsstringOThe authentication credentials for the user who's balance is being inquired, if the inquiry is being made on behalf of a user.
sourceOfFundsstringOThe name of a source account on which to check the balance. If null, the Paga account balance with be retrieved.
LocalestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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 NameTypeMandatory(M) / Optional(O)Description
responseCodestringMA response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure
referenceNumberstringMThe same reference number that was passed in the request
totalBalancedoubleMThe total balance in the account
availableBalancedoubleMA current balance in the account available for use
CurrencydoubleMThe currency in which the balances are reported
MessagestringMA human-readable message describing the transaction result (success or fail)
balanceDateTimeUTCdatetimeMThe 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 NameTypeMandatory(M) / Optional(0)Description
referenceNumberstringMA 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
accountPrincipalstringOThe 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.
accountCredentialsstringOThe authentication credentials for the user who's transaction history is being retrieved, if the inquiry is being made on behalf of a user.
startDateUTCdateTimeMThe 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.
endDateUTCdateTimeMThe 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.
LocalestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberstringMThe same reference number that was passed in the request
recordCountintMThe number of transaction history records retrieved
currencydoubleMThe currency in which the balances are reported
responseCodestringMA response code indicating the status (success/fail) of the operation on the Paga platform and if failure, indicating reason for failure
ItemsTransactionHistoryItemMA list of retrieved transaction history items
MessagestringMA human-readable message describing the transaction result (success or fail)

 
TransactionHistoryItem

Parameter NameTypeMandatory(M) / Optional(O)Description
itemNumberintMThe sequential item number count (starts at 1)
dateUTCdateTimeMThe transaction date in UTC time standard
DescriptionstringMThe transaction description
AmountdoubleMThe base transaction amount
StatusstringMThe transaction completion status
transactionIdstringOIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
referenceNumberstringOIf 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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberstringMA 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
accountPrincipalstringOThe 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.
accountCredentialsstringOThe authentication credentials for the user who's transaction history is being retrieved, if the inquiry is being made on behalf of a user.
localestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberstringMThe same reference number that was passed in the request
recordCountintMThe number of transaction history records retrieved
currencydoubleMThe currency in which the balances are reported
responseCodestringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
ItemsTransactionHistoryItemMA list of retrieved transaction history items
MessagestringMA human-readable message describing the transaction result (success or fail)

 
TransactionHistoryItem

Parameter NameTypeMandatory(M) / Optional(O)Description
itemNumberintMThe sequential item number count (starts at 1)
dateUTCdateTimeMThe transaction date in UTC time standard
DescriptionstringMThe transaction description
AmountdoubleMThe base transaction amount
StatusstringMThe transaction completion status
transactionIdstringOIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
referenceNumberstringOIf 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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberstringMA 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
LocalestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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 NameTypeMandatory(M) / Optional(O)Description
responseCodestringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
referenceNumberstringMThe same reference number that was passed in the request
MessagestringMA human-readable message describing the transaction result (success or fail)
merchantsMerchantMThe list of available registered merchants on the Paga platform

 
Merchant

Parameter NameTypeMandatory(O) / Optional(O)Description
NamestringMThe merchant name
UuidstringMA unique identifier which can be used in requests to identify the merchant
IdstringOA short merchant id which can be used in requests to identify the merchant
CodestringOA 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 NameTypeMandatory(O) / Optional(O)Description
referenceNumberstringMA 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
merchantPublicIdstringMThe identifier which uniquely identifies the merchant on the Paga platform. i.e Merchant Public Id. This is returned from the previous call (Get Merchants) *
LocalestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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 NameTypeMandatory(M) / Optional(O)Description
responseCodestringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
referenceNumberstringMThe same reference number that was passed in the request
MessagestringMA human-readable message describing the transaction result (success or fail)
ServicesMerchantServiceMThe list of available merchant services for the provided merchant id

 
MerchantService

Parameter NameTypeMandatory(M) / Optional(O)Description
NamestringMThe service name
CodestringMThe service product code.
PricedoubleOThe service price
shortCodestringOA 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

ParameterTypeMandatory (M) / Optional(O)Description
referenceNumberstringMA 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
localestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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

ParameterTypeMandatory (M) / Optional(O)Description
responseCodestringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
referenceNumberstringMThe same reference number that was passed in the request
messagestringMA human-readable message describing the transaction result (success or fail)
bankBankMThe 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 NameTypeMandatory(M) / Optional(O)Description
referenceNumberstringMThe reference number provided with the original operation for which the status is being queried
LocalestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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 NameTypeMandatory(M) / OptionalDescription
referenceNumberstringMThe same reference number that was passed in the request
FeedoubleOThe fee associated with the original transaction, if any
transactionIdstringOIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
responseCodestringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
MessagestringMA 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

ParameterTypeMandatory(M) / Optional(O)Description
referenceNumberstringMA 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
LocalestringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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

ParameterTypeMandatory (M) / Optional(O)Description
referenceNumberstringMThe same reference number that was passed in the request
responseCodestringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
messagestringMA human-readable message describing the transaction result (success or fail)
mobileOperatorMobileOperatorMThe list of available mobile operators on Paga's platform

 
MobileOperator

ParameterTypeMandatory (M) / Optional(O)Description
NamestringMThe mobile operator name
mobileOperatorCodestringMA unique identifier which should be used to identify the mobile operator in requests

18. Get Data Bundle By Operator

The Get Data Bundle By Operators operation enables an integrated 3rd party to utilize the Paga platform to obtain a list of available data bundles with respect to a particular mobile operator.

Service Method: getDataBundleByOperator

 
Request Parameters

ParameterTypeMandatory(M)/Optional(O)Description
referenceNumberstringMA 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
operatorPublicIdstringMThe identifier which uniquely identifies the mobile operator on the Paga platform. i.e Mobile Operator Public Id. This is returned from the previous call (Get Mobile Operators) *
URL:
    https://www.mypaga.com/paga-webservices/business-rest/secured/getDataBundleByOperator
Http Headers
    principal: publicId (business organization publicId)
    credentials: password
    hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + operatorPublicId + hashkey)
    Content-Type: application/json
 
Request Body:
    { 
        "referenceNumber": "11314250", "operatorPublicId": "42419156-DD57-4737-8373-20678CD9AA29"
    }
{
    "responseCode": 0,
    "message": null,
    "mobileOperatorServices": [
        {
            "mobileOperatorId": 6,
            "servicePrice": 100.0,
            "serviceName": "MTN 10MB 24 HRS (100)",
            "serviceId": 148
        },
        {
            "mobileOperatorId": 6,
            "servicePrice": 150.0,
            "serviceName": "MTN 25MB 24 HRS (150)",
            "serviceId": 153
        }   
        
    ]
}

 
Response Parameters

ParameterTypeMandatory(M)/Optional(O)Description
referenceNumberstringMThe same reference number that was passed in the request
responseCodestringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
messagestringMA human-readable message describing the transaction result (success or fail)
mobileOperatorServicesMobileOperatorServicesMThe list of available mobile operators services on Paga's platform

 
MobileOperatorServices

ParameterTypeMandatory(M)/Optional(O)Description
mobileOperatorIdstringMA unique reference number provided by the business, identifying the mobile operator
servicePricenumberMThe service price
serviceNamestringMThe service name
serviceIdstringMA unique reference number provided by the business, identifying the data service.

19. 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 NameTypeMandatory(M) / OptionalDescription
referencestringMA 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
merchantExternalIdstringMA unique reference number provided by the business, identifying the specific Organization account to be created.
merchantInfojsonMContaining information about the Organization to be created
integrationjsonMContains information about the type of notification to be used for notification of received payments.

Merchant Info

Parameter NameTypeMandatory(M)/Optional(O)
LegalEntityjsonM
LegalEntityRepresentativejsonM
AdditionalParametersjsonM

LegalEntity

Parameter NameTypeMandatory(M)/Optional(O)Description
addressCountryStringOSub merchant country
addressZipStringOSub merchant ZIP address code
nameStringMSub Merchant name
descriptionStringO
addressLine1StringO
addressLine2StringO
addressStateStringOSub Merchant state
addressCityStringOSub Merchant city

LegalEntityRepresentative

Parameter NameTypeMandatory(M)/Optional(O)Description
firstNameStringMThe legal representative first name.
phoneStringMThe legal representative phone number
lastNameStringMThe legal representative last name.
emailStringMThe legal representative email address.
dateOfBirthDateMThe legal representative date of birth

AdditionalParameters

Parameter NameTypeMandatory(M)/Optional(O)Description
displayNameStringMPreferred Merchant display name.
establishedDateStringMDate the merchant organisation was established
websiteUrlStringOMerchant 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://www.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 NameTypeMandatory(M) / Optional(O)Description
responseCodestringMA response code indicating the status (success/fail) of the operation on Paga platform and if failure, indicating reason for failure
onboardingUpdatejsonMThe same reference number that was passed in the request
messagestringMA human-readable message describing the transaction result (success or fail)

20. 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 NameTypeMandatory(M)/Optional(O)Description
itemsMoneyTransferItemMA list of the money transfer items included in this bulk operation
bulkReferenceNumberStringOA 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 NameTypeMandatory(M)/Optional(O)Description
referenceNumberStringMA 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
amountdoubleMThe amount of money to transfer to the recipient
destinationAccountStringMThe 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
currencyCurrencyOThe currency of the operation, if being executed in a foreign currency
destinationBankStringOFor money transfers to a bank account, this is the destination bank code
senderPrincipalStringOThe 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.
senderCredentialsStringOThe authentication credentials for the user sending money if the money is being sent on behalf of a user.
transferReferenceStringOAdditional transfer-specific reference information that may be required for transfer processing
sourceOfFundsStringOThe name of a source account for funds. If null, the source sender's Paga account will be used as the funding source.
sendWithdrawalCodebooleanOIf 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
suppressRecipientMessagebooleanOWhether 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.
alternateSenderNameStringOIf 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.
minRecipentKYCLevelStringOThe minimum target KYC level the money transfer transaction recipient's Paga account must have, can be one of KYC1, KYC2, and KYC3
holdingPeriodNumericOThe 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://www.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",
			"items": [{																																						    "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
}

21. Merchant Account Details

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

Service Method: getMerchantAccountDetails

Request Parameters

Parameter NameTypeMandatory(M)/Optional(O)Description
referenceNumberStringMA 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
merchantAccountStringMThe Organization public ID for which you want to get customer account details
merchantReferenceNumberStringMCustomer account Number at the Organization
merchantServiceProductCodeStringOMerchant service code specifying which of the merchant's services are being paid for

Sample Code

URL:
    https://www.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"
   }
}

22. 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 NameTypeMandatory(M)/Optional(O)Description
referenceNumberStringMA 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
localeStringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
customerPhoneNumberStringMCustomer phone number
amountDoubleMThe amount of money to be cashed out by the customer
withdrawalCodeStringMThe Unique Code that the customer will supply for dispense cash
URL:
    https://www.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 NameMandatory(M)/Optional(O)DescriptionType
responseCodeMA response code indicating the
status (success/fail) of the operation on Paga platform and if failure, indicating
reason for failure.
Strig
messageMA human-readable message describing the transaction
result (success or fail)
String
transactionIdMIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transactionString
agentCommissionMAgent commission for
this transaction
Double
customerNameMPaga registered
customer name using
the provided phone
number
String

23. Transaction Status

The Transaction Status operation allows businesses to check on the status of a previous operation completed within the last 48 hours.

Service Method: transactionStatus

Request Parameters

Parameter NameTypeMandatory(M)/Optional(O)Description
referenceNumberStringMThe Merchant unique transaction code used as part of a previously executed transaction
localeStringOThe language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard
URL:
    https://www.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 NameTypeMandatory(M)/Optional(O)Description
responseCodeNumberMA response code indicating the
status (success/fail) of the operation on Paga platform and if failure, indicating
reason for failure.
messageStringODescribes the status of the request when a transaction fails.
referenceNumberStringMThe unique reference number code provided with the request
currencyStringOThe currency of the operation, if being executed in a foreign currency.
statusStringMThe 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
transactionReferenceStringMA 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.
transactionIdStringMThe common transaction id shared with all parties involved in the transaction.
transactionTypeStringMAn enum representing the type of transaction executed
dateUTCdatetimeOThe transaction date and time provided in UTC standard time
amountDoubleMThe amount of the value of the transaction.
merchantTransactionReferenceStringMA 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.)
additionalPropertiesObjectOThis contains additional properties returned from merchant.
Note , this might vary across merchants.

24. Validate Money Transfer

Validate Money Transfer operation allows businesses to pre-validate a potential money transfer operation using similar parameters that would be provided for the actual money transfer operation. The endpoint takes a reference number, amount, currency, and destination account required for the money transfer transaction. The destination account number provided in the request would be validated. The status of the operation, reference number, the account holder's name, including the fees that would be charged for that transaction would be returned in the response.

Request Parameters

ParameterTypeMandatory(M)/Optional(O)Description
referenceNumberStringMA unique reference number provided by the business, identifying this transaction. This reference number will be preserved on the Paga platform to reconcile the operation across systems and will be returned in the response
AmountDoubleMThe amount of money to be transferred to the destination account.
CurrencyStringMThe currency for the actual money transfer operation.
destinationAccountStringMThe destination account number that would be provided for the original money transfer operation for which the status is being queried.
{ 
  "referenceNumber":"01010101010001",
  "amount":"4053.75",
  "currency":"NGN",
  "destinationAccount":"08055423122"
}
{
    "responseCode": 0,
    "message": "SUCCESS",
    "referenceNumber": "01010101010001",
    "fee": 150.0,
    "vat": 0.0,
    "recipientAccountHolderName": "John Doe",
    "recipientRegistrationStatus": "REGISTERED",
    "recipientKYCLevel": "None"
}

Response Parameter

Parameter NameTypeMandatory(M)/Optional(O)Description
responseCodeNumberMA response code indicating the
status (success/fail) of the operation on Paga platform and if failure, indicating
reason for failure.
messageStringMDescribes the status of the request when a transaction fails.
feeNumberMIf successful, the fee/tariff charged to the sender for the money transfer to this recipient
vatNumberMIf successful, the value added tax charged to the sender for the money transfer to this recipient
recipientAccountHolderNameStringMThe name of the beneficiary of the money transfer transaction.
recipientRegistrationStatusStringMThe registration status of the beneficiary of the money transfer transaction.
recipientKYCLevelStringMThe KYC level of the beneficiary of the money transfer transaction.