Below are the details of the services exposed via the Paga Business services API

Note on Hash Parameters

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)

1. Register Customer

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

Service Method: registerCustomer

Request URL

 https://mypaga.com/paga-webservices/business-rest/secured/registerCustomer

Request Parameters

Argument Name	Type	Requirement	Description	Validation
referenceNumber	String	Required	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	A valid alpha-numeric
customerPrincipal	String	Required	The identifying credential (principal) for the customer (eg. phone number, username). This will be checked against the Paga system to determine if the account belongs to an existing user
customerCredentials	String	Required	The Customer’s credentials which is a valid phone number	A valid phone number
customerFirstName	String	Required	The first name of the customer	A valid personal name with no number and special characters.
customerLastName	String	Required	The Last name of the customer	A valid person name with no number and special characters.
customerDateOfBirth	String	Required	Birth date of the customer	A valid date in dd/mm/yyyy format
accountDetails	String	Optional	Additional optional account details provided by customer, to be specified in a format indicated by the 3rd party

Sample Request

Sample Request

URL:
	https://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 + 			customerPrincipal + customerCredentials + hashkey)
	Content-Type: application/json

Request Body:  
	{
		"referenceNumber": "", "customerPrincipal": "+251911400862",
		"customerCredentials":"password1", "customerFirstName":"henok",
		"customerLastName":"Solomon", 	"customerDateOfBirth":"01/01/2013", 
		"accountDetails": ""
	}

Response Parameters

Argument Name

Type

Requirement

Description

refernceNumber

String

Required

A unique reference number provided to the business

message

String

Required

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

responseCode

Integer

Required

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

Sample Response

Sample Response

{
	"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.",
	"referenceNumber":"","responseCode":0
}

2. Validate Money Transfer (not yet available)

The Validate Money Transfer operation enables an integrated 3rd party to utilize the Paga platform to pre-validate potential money transfer operations using the same parameters that would be provided for the actual money transfer. This will return a result indicating whether the actual money transfer using the same parameters is likely to be successful or not, and if not, why not.

Service Method: validateMoneyTransfer

Request URL

https://mypaga.com/paga-webservices/business-rest/secured/validateMoneyTransfer

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	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. 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
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.
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	Additional transfer-specific reference information that may be required for transfer processing
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
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

Sample Request

URL:
	https://mypaga.com//paga-webservices/business-rest/secured/validateMoneyTransfer 

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":"2345","amount":"10000","currency":"AED",
		"destinationAccount":"12345", "destinationBank": "",
		"senderPrincipal": "","senderCrendetials": "", "transferReference": "", 
		"sourceOfFunds" : "", "sendWithdrawalCode": ""
	}

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
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)

Sample Response

Sample Response

{
	"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": ""
}

3. Bulk Validate Money Transfer (not yet available)

The Bulk Validate Money Transfer operation enables an integrated 3rd party to utilize the Paga platform to execute the validate money transfer operation described above for multiple recipients simultaneously.

Service Method: validateMoneyTransferBulk

Request URL

https://mypaga.com/paga-webservices/business-rest/secured/validateMoneyTransferBulk

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

Sample Request

URL:
	https://mypaga.com/paga-webservices/business-rest/secured/validateMoneyTransferBulk 
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

Sample Response

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":""
}

On this page:

4. 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 URL

https://mypaga.com/paga-webservices/business-rest/secured/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	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. 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
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.
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	Additional transfer-specific reference information that may be required for transfer processing
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.

Sample Request

Sample Request

URL:
	https://mypaga.com/paga-webservices/business-rest/secured/moneyTransfer 

Http Headers:
	principal: 61d3dbca-056a-48e4-8074-99624fd86955 (publicId of business organization)
	credentials: password1
	hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + amount + destinationAccount + hashkey)
	Content-Type: application/json

Request Body :  
	{
		"referenceNumber":"2345","amount":"10000","currency":"AED",
		"destinationAccount":"12345", "destinationBank": "",
		"senderPrincipal": "","senderCrendetials": "", "transferReference": ""
		, "sourceOfFunds" : "", "sendWithdrawalCode": ""
	}

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
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)

Sample Response

Sample Response

{
	"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": ""
}

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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)

Request URL

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

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

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

Request URL

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

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

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)

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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

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

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

Request URL

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.

Email Notification

"integration": {
		"type" : "EMAIL_NOTIFICATION",
		"financeAdminEmail": "gfinance@mail.com"
   }

Merchant Notification Reverse API

"integration": {
		"type" : "MERCHANT_NOTIFICATION_REVERSE_API",
		"callbackUrl": "https://mywebhook.com/callback",
		"username": "username",
		"password": "password"
   }

Sample Request

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

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

Request URL

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

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

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

Page:

Paga Business Services API
Page:

Getting started

Browser not supported