Paga Business Services API
- Umoh Bassey-Duke
5. Bulk Money Transfer (not yet available)
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
https://mypaga.com/paga-webservices/business-rest/secured/moneyTransferBulk
Request Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
Items | MoneyTransferItem | M | A list of the money transfer items included in this bulk operation |
sendWithdrawalCode | string | 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 |
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 |
currency | double | 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 |
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. |
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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/moneyTransferBulk
Http Headers
principal: publicId
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing((referenceNumber + amount + destinationAccount) of the first item in the MoneyTransfer items list + no of total items count + hashkey)
Content-Type: application/json
Request Body
{
"items":[{
"referenceNumber":"2345","amount":"10000","currency":"AED",
"destinationAccount":"12345", "destinationBank": "",
"senderPrincipal": "","senderCrendetials": "", "transferReference": "",
"sourceOfFunds" : "", "sendWithdrawalCode": ""
}],
"sendWithdrawalCode":null
}
Response Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
items | MoneyTransferResponeItem | M | A list of response items, corresponding to the items sent in the bulk operation request, providing the operations status for each request item |
responseCode | String | M | A response code indicating the status (success/partial-success/fail) of the overall bulk operation on the Paga platform. |
message | String | M | A human-readable message describing the transaction result (success or fail) for the overall bulk operation. Indicates the number of successful and failed transactions. |
MoneyTransferResponseItem
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 |
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 |
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 item 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) |
Sample Response
{
"items":
[{
"message":"Thank for registering to paga. We will send SMS to +251911010862 with a registeration code. Please use www.mypaga.com or dial 636 to set up your user PIN.",
"responseCode":0, "referenceNumber": "","withdrawalCode": "",
"transactionId": "", "fee": "", "receiverRegistrationStatus": "",
"currency": "", "exchangeRate": ""
}],
"message": "", "responseCode":""
}
6. Bulk Money Transfer Status (not yet available)
The Bulk Money Transfer Status operation enables an integrated 3rd party to utilize the Paga platform to query the status of multiple previously executed money transfer operations at one time. This can be useful for asynchronous processing of bulk many transfer executions, for which a synchronous wait for response may not be feasible due to long execution durations or network failure of the bulk operation. This is limited to 10,000 items per bulk operation.
Service Method: moneyTransferStatusBulk
https://mypaga.com/paga-webservices/business-rest/secured/moneyTransferStatusBulk
Request Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
bulkReferenceNumber | string | O | A bulk reference number identifying a previously submitted bulk money transfer set. If this number is provided, the individual item reference numbers are ignored and all transfer items contained in this bulk are retrieved. |
items | MoneyTransferStatusItem | O | A list of money transfer items included in this bulk operation. Not required if a bulkReferenceNumber is porived. |
MoneyTransferStatusItem
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
referenceNumber | string | O | The unique reference number provided by the business as part of the original money transfer request, identifying the money transfer item transaction. This is only used if the bulkReferenceNumber is omitted. |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/moneyTransferStatusBulk
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing((referenceNumber) of the first item in the MoneyTransferStatus items list + no of total items count + hashkey)
Content-Type: application/json
Request Body
{
"bulkReferenceNumber": "", "items":
[{
"referenceNumber":"008833
}]
}
Response Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
bulkReferenceNumber | string | O | The bulk reference number identifying the whole batch sent as part of the request. |
items | MoneyTransferStatusResponeItem | M | A list of response items, corresponding to the items sent in the bulk operation request, providing the operations status for each request item |
responseCode | string | M | A response code indicating the status (success/partial-success/fail) of the overall bulk operation on the Paga platform. |
message | string | M | A human-readable message describing the transaction result (success or fail) for the overall bulk operation. Indicates the number of successful and failed transactions. |
MoneyTransferStatusResponseItem
Parameter Name | 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 the Paga platform and if failure, indicating reason for failure |
message | string | M | A human-readable message describing the transaction result (success or fail) |
withdrawalCode | string | O | If funds are sent on behalf of the organization itself, 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 item 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 |
Sample Response
{
bulkReferenceNumber":"",
"items":
[{
"withdrawalCode":null,"referenceNumber":"+251911314250",
"message":"Send cash is successfull","receiverRegistrationStatus":true,
"responseCode":0,”transactionId”:”At34”,”fee”:50.0,
”currency”:null,“exchangeRate”:null
}],
"reponseCode": "", "message": ""
}
7. Airtime Purchase
The Airtime Purchase operation enables an integrated 3rd party to utilize the Paga platform to purchase airtime for any phone number on any of the major networks. The purchase can be funded by the integrated 3rd party themselves, or on behalf of another customer with the appropriate authentication. The source of funds may be the purchaser's Paga account or another source that the sender has pre-registered on the Paga platform.
Service Method: airtimePurchase
https://mypaga.com/paga-webservices/business-rest/secured/airtimePurchase
Request Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
referenceNumber | string | M | A unique reference number provided by the business, identifying the transaction. This reference number will be preserved on the Paga platform to reconcile the operation across systems and will be returned in the response |
Amount | double | M | The amount of airtime to purchase |
Currency | double | O | The currency of the operation, if being executed in a foreign currency |
destinationPhoneNumber | string | O | The phone number for which airtime is being purchased. If null, and Principal is specified, then the airtime will be purchased for the phone number of the purchaserPrincipal. Must be provided if the purchaserPrincipal is null |
purchaserPrincipal | string | O | The authentication principal for the user purchasing airtime if the airtime is being purchased on behalf of a user. If null, the airtime will be processed from the 3rd parties own account. |
purchaserCredentials | string | O | The authentication credentials for the user purchasing the airtime if the airtime is being purchased on behalf of a user. |
sourceOfFunds | String | O | The name of a source account for funds. If null, the source purchaser's Paga account will be used as the funding source. |
Locale (not presently in use) | string | O | The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/airtimePurchase
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + hashkey)
Content-Type: application/json
Request Body
{
"referenceNumber": "", "amount": "", "currency": "",
"destinationPhoneNumber": "", "purchaserPrincipal": "",
"purchaserCredentials": "", "sourceOfFunds": "", "": ""
}
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) |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0, ,”transactionId”:”At34”,”fee”:50.0,
”currency”:null,“exchangeRate”:null
}
8. Bulk Airtime Purchase (not yet available)
https://mypaga.com/paga-webservices/business-rest/secured/airtimePurchaseBulk
Request Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
bulkReferenceNumber | String | M | A reference number identifying the whole batch. This reference number must be unique and may be used to refer to the batch as a single set in future transactions. |
items | AirtimePurchaseItem | M | A list of the airtime purchase items included in this bulk operation |
AirtimePurchaseItem
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 |
destinationPhoneNumber | string | O | The phone number for which airtime is being purchased. If null, and purchaserPrincipal is specified, then the airtime will be purchased for the phone number of the purchaserPrincipal. Must be provided if the purchaserPrincipal is null |
currency | double | O | The currency of the operation, if being executed in a foreign currency |
purchaserPrincipal | string | O | The authentication principal for the user purchasing the airtime if the airtime is being purchased on behalf of a user. If not provided, the airtime purchase will be processed from the 3rd parties own account. |
purchaserCredentials | string | O | The authentication credentials for the user purchasing 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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/airtimePurchaseBulk
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing((referenceNumber + amount + destinationPhoneNumber) of the first item in the collection of bulk airtime purchase request + item counts of the bulk request + hashkey)
Content-Type: application/json
Request Body
{
"bulkReferenceNumber": "",
"items":
[{
"referenceNumber": "", "amount": "", "currency": "",
"destinationPhoneNumber": "", "purchaserPrincipal": "",
"purchaserCredentials": "", "sourceOfFunds": "", "": ""
}]
}
Response Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
bulkReferenceNumber | string | M | The bulk reference number identifying the whole batch sent as part of the request. |
items | AirtimePurchaseResponseItem | M | A list of response items, corresponding to the items sent in the bulk operation request, providing the operations status for each request item |
responseCode | String | M | A response code indicating the status (success/partial-success/fail) of the overall bulk operation on the Paga platform. |
message | String | M | A human-readable message describing the transaction result (success or fail) for the overall bulk operation. Indicates the number of successful and failed transactions. |
AirtimePurchaseResponseItem
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 item |
message | string | M | A human-readable message describing the transaction result (success or fail) |
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 |
Sample Response
{
"bulkReferenceNumber": "",
"items":
[{
"referenceNumber":"+251911314250", "message":"Airtime purchase request made successfully","responseCode":0, ,
”transactionId”:”At34”,”fee”:50.0,”currency”:null,“exchangeRate”:null
}],
"message":"Airtime purchase request made successfully","responseCode":0
}
9. 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
https://mypaga.com/paga-webservices/business-rest/secured/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) |
merchantReferenceNumber | string | M | The account/reference number identifying the customer on the merchant's system |
merchantService | string | M | 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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/merchantPayment
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + merchantAccount + merchantReferenceNumber + hashkey)
Content-Type: application/json
Request Body:
{
referenceNumber": "", "amount": "", "currency": "",
"merchantAccount": "","merchantReferenceNumber": "",
"merchantService": "", "purchaserPrincipal": "",
"purchaserCredentials": "", "sourceOfFunds": "", "locale": ""
}
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 |
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.) |
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 merchant payment item |
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) |
Sample Response
{
"referenceNumber":"+251911314250", "merchantTransactionReference": "",
"message":"Airtime purchase request made successfully","responseCode":0,
”transactionId”:”At34”,”fee”:50.0,”currency”:null,“exchangeRate”:null
}
10. Bulk Merchant Payment (not yet available)
https://mypaga.com/paga-webservices/business-rest/secured/merchantPaymentBulk
Request Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
bulkReferenceNumber | String | M | A reference number identifying the whole batch. This reference number must be unique and may be used to refer to the batch as a single set in future transactions. |
Items | MerchantPaymentItem | M | A list of the merchant payment items included in this bulk operation |
MerchantPaymentItem
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 |
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.) |
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 merchant payment item |
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) |
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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/merchantPaymentBulk
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing((referenceNumber + amount + merchantAccount + merchantReferenceNumber) of the first request in the bulk merchant payment + no of total items in the request + hashkey)
Content-Type: application/json
Request Body:
{
"bulkReferenceNumber": "",
"items":
[{
"referenceNumber": "", "amount": "", "currency": "",
"merchantAccount": "","merchantReferenceNumber": "",
"merchantService": "", "purchaserPrincipal": "",
"purchaserCredentials": "", "locale": ""
}]
}
Response Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
bulkReferenceNumber | string | M | The bulk reference number identifying the whole batch sent as part of the request. |
items | MerchantPaymentResponseItem | M | A list of response items, corresponding to the items sent in the bulk operation request, providing the operations status for each request item |
responseCode | string | M | A response code indicating the status (success/partial-success/fail) of the overall bulk operation on the Paga platform. |
message | string | M | A human-readable message describing the transaction result (success or fail) for the overall bulk operation. Indicates the number of successful and failed transactions. |
MerchantPaymentResponseItem
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 |
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.) |
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 merchant payment item |
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) |
Sample Response
{
"bulkReferenceNumber": "",
"items":
[{
"referenceNumber": "", "", "message":"Airtime purchase request made successfully",
"responseCode":0, ,”transactionId”:”At34”,
”fee”:50.0,”currency”:null,“exchangeRate”:null, "merchantTransactionReference":
"","merchantReferenceNumber": ""
}],
"message":"Airtime purchase request made successfully",
"responseCode":0
}
11. 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
https://mypaga.com/paga-webservices/business-rest/secured/validateDepositToBank
Request Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
referenceNumber | string | M | A unique reference number provided by the business, identifying the transaction. This reference number will be preserved on the Paga platform to reconcile the operation across systems and will be returned in the response |
Amount | double | M | The amount of money to deposit to the destination bank and bank account provided. Your Paga account must contain sufficient funds to cover this amount plus any fees. |
Currency | double | O | The currency of the operation, if being executed in a foreign currency. The currency must be one of the currencies supported by the platform. For supported currencies, check with Paga integration operations support. |
destinationBankUUID | string | M | The Paga bank UUID identifying the bank to which the deposit will be made. In order to get the list of supported banks and bank UUIDs, execute the getBanks operation defined in this document. Bank codes will not change though additional banks may be added to the list in the future. |
destinationBankAccountNumber | string | M | The ten digit NUBAN bank account number for the account to which the deposit will be made. This number should be a valid account number for the destination bank as specified by the destinationBankCode parameter above. Executing operation will validate this number and if valid, return the account holder name as stored at the bank for this account. |
recipientPhoneNumber | string | O | The mobile phone number of the recipient of the deposit to bank transaction. Either one or both of this parameter and the recipientEmail parameter must be provided. If this parameter is provided, this operation will validate that it is a valid phone number. |
recipientMobileOperatorCode | string | O | Ignored if recipientPhoneNumber parameter is not provided. This describes the mobile operator that the recipientPhoneNumber belongs to. If recipientPhoneNumber is provided, but this parameter is not, a default mobile operator will selected based on the phone number pattern, but this may not be correct due to number portability of mobile phone numbers and may result in delayed or failed delivery of any SMS messages to the recipient. |
recipientEmail | string | O | The email address of the recipient of the deposit to bank transaction. Either one or both of this parameter and the recipientPhoneNumber parameter must be provided. If this parameter is provided, this operation will validate that it is a valid email address format. |
recipientName | string | O | The name of the recipient. This parameter is currently bot validated. |
locale (not presently in use) | string | O | The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/validateDepositToBank
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + destinationBankUUID + destinationBankAccountNumber + recipientPhoneNumber + hashkey)
Content-Type: application/json
Request Body:
{
referenceNumber": "", "amount": "", "currency": "",
"destinationBankUUID": "","destinationBankAccountNumber": "",
"recipientPhoneNumber": "", "recipientMobileOperatorCode": "",
"recipientEmail": "", "recipientName": "", "locale": ""
}
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 |
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) |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0, , "fee":50.0, "destinationAccountHolderNameAtBank":null
}
12. 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
https://mypaga.com/paga-webservices/business-rest/secured/depositToBank
Request Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
referenceNumber | string | M | A unique reference number provided by the business, identifying the transaction. This reference number will be preserved on the Paga platform to reconcile the operation across systems and will be returned in the response |
Amount | double | M | The amount of money to deposit to the destination bank and bank account provided. Your Paga account must contain sufficient funds to cover this amount plus any fees. |
Currency | double | O | The currency of the operation, if being executed in a foreign currency. The currency must be one of the currencies supported by the platform. For supported currencies, check with Paga integration operations support. |
destinationBankUUID | string | M | The Paga bank UUID identifying the bank to which the deposit will be made. In order to get the list of supported banks and bank UUIDs, execute the getBanks operation defined in this document. Bank codes will not change though additional banks may be added to the list in the future. |
destinationBankAccountNumber | string | M | The ten digit NUBAN bank account number for the account to which the deposit will be made. This number should be a valid account number for the destination bank as specified by the destinationBankCode parameter above. Executing operation will validate this number and if valid, return the account holder name as stored at the bank for this account. |
recipientPhoneNumber | string | O | The mobile phone number of the recipient of the deposit to bank transaction. Either one or both of this parameter and the recipientEmail parameter must be provided. If this parameter is provided, this operation will validate that it is a valid phone number. |
recipientMobileOperatorCode | string | O | Ignored if recipientPhoneNumber parameter is not provided. This describes the mobile operator that the recipientPhoneNumber belongs to. If recipientPhoneNumber is provided, but this parameter is not, a default mobile operator will selected based on the phone number pattern, but this may not be correct due to number portability of mobile phone numbers and may result in delayed or failed delivery of any SMS messages to the recipient. |
recipientEmail | string | O | The email address of the recipient of the deposit to bank transaction. Either one or both of this parameter and the recipientPhoneNumber parameter must be provided. If this parameter is provided, this operation will validate that it is a valid email address format. |
recipientName | string | O | The name of the recipient. This parameter is currently bot validated. |
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 | string | 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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/depositToBank
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + destinationBankUUID + destinationBankAccountNumber + recipientPhoneNumber + hashkey)
Content-Type: application/json
Request Body:
{
referenceNumber": "", "amount": "", "currency": "",
"destinationBankUUID": "","destinationBankAccountNumber": "",
"recipientPhoneNumber": "", "recipientMobileOperatorCode": "",
"recipientEmail": "", "recipientName": "", "suppressRecipientMessage": "",
"remarks": "", "locale": ""
}
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 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 | 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) |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0, "transactionId": "", "fee":50.0,
"currency": "", "exchangeRate": "", "destinationAccountHolderNameAtBank":null
}
13. Charge Customer (POS) (not yet available)
The Charge Customer operation enables an integrated 3rd party to utilize the Paga platform to request a payment to them from existing Paga customers. The process will request authentication from the Paga customer using an alternate channel and will credit the integrated 3rd party upon approval of the charge. The authentication for this process can be handled in different ways:
1) Single stage - The charge request maintains a persistent connection while the customer is contacted for authentication and will return when authentication is complete
2) Polling - The charge request will return immediately with a pending status and will request authentication from the customer in a separate thread. The 3rd party client will need to poll the service using the Charge Customer Confirm request (below) until a completed status (success or fail) is returned
3) 2 stage / One time authorization credential - The charge request will return immediately and will request authentication from the customer in a separate thread. The customer will be provided with a one-time authorization code, which they will provide to the 3rd party and the 3rd party client will need to submit a confirmation request using the Charge Customer Confirm request (below) with this credential.
Service Method: chargeCustomer
https://mypaga.com/paga-webservices/business-rest/secured/chargeCustomer
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 charge being made to the customer |
currency | double | O | The currency of the operation, if being executed in a foreign currency |
merchantReferenceNumber | string | M | The account/reference number identifying the customer on the merchant's system |
merchantServiceName | string | O | The name of the service that the customer is being charged for. Not required |
customerPrincipal | string | M | The authentication principal for the customer being charged which identifies the customer (typically the customer's phone number) |
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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/chargeCustomer
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + merchantServiceName + merchantReferenceNumber + customerPrincipal + hashkey)
Content-Type: application/json
Request Body:
{
referenceNumber": "", "amount": "", "currency": "",
"merchantReferenceNumber": "", "merchantServiceName": "",
"customerPrincipal": "", "sourceOfFunds": "", "locale": ""
}
Response Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
responseCode | string | M | A response code indicating the status of the operation on the Paga platform. If the charge process is split into two phases, this response will indicate that the process is pending and wait for the charge confirmation. Otherwise, this will indicate success/fail and if failure, indicate reason for failure. |
referenceNumber | string | M | The same reference number that was passed in the request |
transactionId | string | O | If the charge process is completed in one step and is successful, this will return the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction |
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 | O | If the charge process is completed in one step, a human-readable message describing the transaction result (success or fail) |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0, ,”transactionId”:”At34”,”fee”:50.0,
”currency”:null,“exchangeRate”:null
}
14. Charge Customer Confirmation (not yet available)
The Charge Customer Confirm operation is called by the integrating 3rd party for multi-stage POS processes (see Charge Customer above). This operation is used to either poll the service API for the result of a polling customer charge, or to submit the one time customer authorization credentials for the second stage of a two-stage customer charge.
Service Method: chargeCustomerConfirm
https://mypaga.com/paga-webservices/business-rest/secured/chargeCustomerConfirm
Request Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
referenceNumber | string | M | For two step or polling charge processes, this is the same reference number provided in the initial chargeCustomer operation. |
customerCredentials | string | O | This is required for two-step charge processes which require the customer credentials provided in a second step. Otherwise, not required |
locale | string | O | The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/chargeCustomerConfirm
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + customerCredentials + hashkey)
Content-Type: application/json
Request Body:
{
referenceNumber": "", "customerCredentials": "", "locale": ""
}
Response Parameters
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
responseCode | string | M | A response code indicating the status of the operation on the Paga platform. For polling charge processes is split into two phases, this may indicate that the process is pending until complete. If complete, this will indicate success/fail and if failure, indicate reason for failure. |
referenceNumber | string | M | The same reference number that was passed in the request |
transactionId | string | O | If the charge process is completed and is successful, this will return the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction |
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 | O | If the charge process is completed, a human-readable message describing the transaction result (success or fail) |
Sample Response
{
"referenceNumber":"+251911314250", "message":"Airtime purchase request made successfully",
"responseCode":0, ,”transactionId”:”At34”,”fee”:50.0,”currency”:null,“exchangeRate”:null
}
16. 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
https://mypaga.com/paga-webservices/business-rest/secured/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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/accountBalance
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + accountPrincipal + accountCredentials + hashkey)
Content-Type: application/json
Request Body:
{
referenceNumber": "", "accountPrincipal": "",
"sourceOfFunds": "", "accountCredentials": "", "locale": ""
}
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 |
Sample Response
{
"referenceNumber":"+251911314250", "message":"Airtime purchase request made successfully",
"responseCode":0, ,”totalBalance”:”100.0”,”availableBalance”:50.0,
”currency”:null,“balanceDateTimeUTC”:null
}
17. 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
https://mypaga.com/paga-webservices/business-rest/secured/transactionHistory
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. |
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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/transactionHistory
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "", accountPrincipal: "",
"accountCredentials": "", "startDateUTC": "",
"endDateUTC": "", "locale": ""
}
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 |
recordCount | int | M | The number of transaction history records retrieved |
Items | TransactionHistoryItem | M | A list of retrieved transaction history items |
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) |
TrnsactionHistoryItem
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 |
Sample Response
{
"referenceNumber":"+251911314250", "message":"Airtime purchase request made successfully",
"responseCode":0, "recordCount": 0,
items:
[{
"itemNumber": "", "dateUTC": "",
"description": "", "amount": "", "status": "",
"referenceNumber": "+251911314250", "transactionId": "At34",
"currency":null, "exchangeRate":null
}],
"currency": ""
}
18. 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
https://mypaga.com/paga-webservices/business-rest/secured/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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/recentTransactionHistory
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "", accountPrincipal: "", "accountCredentials": "", "locale": ""
}
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 |
recordCount | Int | M | The number of transaction history records retrieved |
items | TransactionHistoryItem | M | A list of retrieved transaction history items |
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) |
TrnsactionHistoryItem
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 |
Sample Response
{
"referenceNumber":"+251911314250", "message":"Airtime purchase request made successfully",
"responseCode":0, "recordCount": 0,
items:
[{
"itemNumber": "", "dateUTC": "", "description": "", "amount": "",
"status": "", "referenceNumber": "+251911314250",
"transactionId": "At34","currency":null, "exchangeRate":null
}],
"currency": ""
}
19. Get Funding Sources (not yet available)
The Get Funding Sources operation enables an integrated 3rd party to utilize the Paga platform to obtain a list of pre-configured funding sources for themselves or on behalf of another customer with the appropriate authentication.
Service Method: getFundingSources
https://mypaga.com/paga-webservices/business-rest/secured/getFundingSources
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 registered funding sources are being retrieved, if the inquiry is being made on behalf of a user. If null, the funding sources will be retrieved for the 3rd parties own account. |
accountCredentials | string | O | The authentication credentials for the user who's registered funding sources are 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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/getFundingSources
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + accountPrincipal + accountCredentials + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "", accountPrincipal: "", "accountCredentials": "", "locale": ""
}
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 |
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 |
sources | FundingSource | M | The list of available funding sources for the provided account holder |
FundingSource
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
alias | string | M | The alias of the funding source |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0,
"sources": [{"alias": ""}]
}
20. 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
https://mypaga.com/paga-webservices/business-rest/secured/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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/getMerchants
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "", "locale": ""
}
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 |
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(M)/ 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 |
Sample Response
{
"referenceNumber":"+251911314250", "message":"Airtime purchase request made successfully",
"responseCode":0,
"merchants":
[{
"name": "", "uuid": "", "id": "", "code": ""
}]
}
21. 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
https://mypaga.com/paga-webservices/business-rest/secured/getMerchantServices
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 |
merchantId | string | O | The identifier which uniquely identifies the merchant on the Paga platform. May be the merchant UUID, id, or code. |
Locale | string | O | The language/locale to be used in messaging. If provided, this must conform to the IETF language tag standard |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/getMerchantServices
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + merchantId + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "", "merchantId" : "", "locale": ""
}
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 |
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 |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0,
"services":
[{
"name": "", "price": "", "shortCode": "", "code": ""
}]
}
22. 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
https://mypaga.com/paga-webservices/business-rest/secured/getBanks
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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/getBanks
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "", "locale": ""
}
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 |
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 |
Bank
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
name | string | M | The bank name |
uuid | string | M | A unique identifier which should be used to identify the bank in requests |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0,
"bank":
[{"name": "", "uuid": "" }]
}
23. 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
https://mypaga.com/paga-webservices/business-rest/secured/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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/getOperationStatus
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "", "locale": ""
}
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 |
Message | string | M | A human-readable message describing the transaction result (success or fail) |
Fee | double | O | The fee associated with the original transaction, if any |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0, "transactionId": , "fee": 5.0
}
24. 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
https://mypaga.com/paga-webservices/business-rest/secured/getMobileOperators
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 |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/getMobileOperators
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "", "locale": ""
}
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 |
message | string | M | A human-readable message describing the transaction result (success or fail) |
mobileOperator | MobileOperator | M | The list of available banks on the Paga platform |
MobileOperator
Parameter Name | Type | Mandatory(M)/ Optional(O) | Description |
|---|---|---|---|
Name | string | M | The bank name |
mobileOperatorCode | string | M | A unique identifier which should be used to identify the bank in requests |
Sample Response
{
"referenceNumber":"+251911314250",
"message":"Airtime purchase request made successfully",
"responseCode":0,
"mobileOperator":
[{"name": "", " mobileOperatorCode ": "" }]
}
25. Onboard Merchant
The Onboard Merchant operation, allows Aggregator Organizations to create sub organizations on the paga platform.
This operation is only available to Merchant aggregators on the Paga platform.
Service Method: onboardMerchant
https://mypaga.com/paga-webservices/business-rest/secured/onboardMerchant
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 |
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. |
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": "gfinance@mail.com"
}
"integration": {
"type" : "MERCHANT_NOTIFICATION_REVERSE_API",
"callbackUrl": "https://mywebhook.com/callback",
"username": "username",
"password": "password"
}
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/onboardMerchant
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + merchantExternalId + name + phone + email + hashkey)
Content-Type: application/json
Request Body:
{
"reference": "52a54d49-6971-401b-9aa0-95cb5b23ddf2",
"merchantExternalId": "27791fe3-47b9-4080-8d3f-20a37e81bb24",
"merchantInfo": {
"legalEntity": {
"name" : "Example Sub Merchant 1",
"description": "business",
"addressLine1": "35 Yabas Road",
"addressLine2": "Somewhere",
"addressCity": "Lagos",
"addressState": "Lagos",
"addressZip": "xxxx",
"addressCountry": "Nigeria"
},
"legalEntityRepresentative": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1995-05-02T07:45:37.726+03:00",
"phone": "+2348188215379",
"email": "primarycontact@email.com"
},
"additionalParameters": {
"establishedDate": "2014-03-13T19:53:37.726+03:00",
"websiteUrl": "http://www.example.com",
"displayName": "Life is Good"
}
},
"integration": {
"type" : "EMAIL_NOTIFICATION",
"financeAdminEmail": "gfinance@apposit.com"
}
}
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 |
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) |
Sample Response
{
"responseCode": 0,
"onboardingUpdate": {
"status": "succeeded",
"credentials": {
"merchantPublicId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXXX",
"merchantSecretKey": "xxxxxxxxxxxxxxxx",
"merchantHmac": "b3c15a3b8xxxxxxxxc06c86e2394xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0fc374d898aed5a3a86xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx9e67c1c969f1b8"
}
}
}
26. Get Merchant Account Details
This Operation allows Businesses to query account details for customer for bill pay
This operation is only available to Merchant aggregators on the Paga platform.
Service Method: onboardMerchant
https://mypaga.com/paga-webservices/business-rest/secured/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 | json | M | Customer account Number at organization. |
Sample Request
URL:
https://mypaga.com/paga-webservices/business-rest/secured/onboardMerchant
Http Headers
principal: publicId (business organization publicId)
credentials: password
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + merchantExternalId + name + phone + email + hashkey)
Content-Type: application/json
Request Body:
{
"referenceNumber": "abcefghijklmnopqrstuv",
"merchantAccount": "A3878DC1-F07D-48E7-AA59-8276C3C26647",
"merchantReferenceNumber": "ABCD1234"
}
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 |
customerName | string | M | Customer name from the merchant |
message | string | M | A human-readable message describing the transaction result (success or fail) |
| phoneNumber | string | M | Phone number of the customer at merchant |
| accountNumber | string | M | Account Number of the Customer at Merchant |
| details | json | M | unstructured data as received from Merchant |
Sample Response
{
"responseCode": 0,
"message": null,
"customerName": "Mock User",
"phoneNumber": null,
"accountNumber": "Mock User",
"details": {
"First Name": "Mock",
"details": "Mock User",
"Last Name": "User",
"merchantAccountDetails": "Mock User"
}
}
Next: Sample REST Clients
Related articles