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 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://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 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://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 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://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 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 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 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. |
mobileOperatorPublicId | string | M | This is the UUID of the mobile operator you want to purchase. It can be fetched from Get Mobile Operator Endpoint |
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 |
mobileOperatorServiceId | String | O | This 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) |
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://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 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://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 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). |
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 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. |
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. |
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://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 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) |
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 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://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 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) |
sessionId | string | M | SessionId 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 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://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 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://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 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://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 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://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 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://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 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://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
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://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 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://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
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 mobile operators on Paga's platform |
MobileOperator
Parameter | Type | Mandatory (M) / Optional(O) | Description |
---|---|---|---|
Name | string | M | The mobile operator name |
mobileOperatorCode | string | M | A 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
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 |
operatorPublicId | string | M | The 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
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) |
mobileOperatorServices | MobileOperatorServices | M | The list of available mobile operators services on Paga's platform |
MobileOperatorServices
Parameter | Type | Mandatory(M)/Optional(O) | Description |
---|---|---|---|
mobileOperatorId | string | M | A unique reference number provided by the business, identifying the mobile operator |
servicePrice | number | M | The service price |
serviceName | string | M | The service name |
serviceId | string | M | A 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 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. |
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://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 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) |
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 Name | Type | Mandatory(M)/Optional(O) | Description |
---|---|---|---|
items | 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://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 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://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 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://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 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 |
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 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://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 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. |
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
Parameter | Type | Mandatory(M)/Optional(O) | Description |
---|---|---|---|
referenceNumber | String | M | A 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 |
Amount | Double | M | The amount of money to be transferred to the destination account. |
Currency | String | M | The currency for the actual money transfer operation. |
destinationAccount | String | M | The destination account number that would be provided for the original money transfer operation for which the status is being queried. |
URL:
https://www.mypaga.com/paga-webservices/business-rest/secured/validateMoneyTransfer
Http Headers:
principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of business organization)
credentials: password1 (Secrete Key of business organization)
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + destinationAccount + hashkey)
Content-Type: application/json
Request Body :
{
"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 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 | M | Describes the status of the request when a transaction fails. |
fee | Number | M | If successful, the fee/tariff charged to the sender for the money transfer to this recipient |
vat | Number | M | If successful, the value added tax charged to the sender for the money transfer to this recipient |
recipientAccountHolderName | String | M | The name of the beneficiary of the money transfer transaction. |
recipientRegistrationStatus | String | M | The registration status of the beneficiary of the money transfer transaction. |
recipientKYCLevel | String | M | The KYC level of the beneficiary of the money transfer transaction. |
Updated over 1 year ago