Paga Connect Operations Version 2

1. Merchant Payment

This is the operation executed to make a payment to you on behalf of the customer. There are several ways in which this operation can be executed, as listed below

Request Parameter

Argument Name	Type	Mandatory(M)/Optional(O)	Description
referenceNumber	String	M	This is a unique reference number provided by the client to uniquely identify the transaction and for use in retrieving the transaction records later
amount	Double	M	Amount to charge the user
merchantCustomerReference	String	M	Unique identifier for your customer eg. Phone number, email, id etc.
merchantProductCode	String	O	This is an optional code that you can use to verify your payments.
currency	String	O	This is the currency code of the transaction, NGN is the only supported currency as of now (February 2016)

1. REST-Style parameterized URL with all parameters provided.

Argument Name	Merchant Payment Request
URI:	https://www.mypaga.com/paga-webservices/oauth2/secure/merchantPayment/v3/ referenceNumber/{referenceNumber}/amount/{amount}/merchantCustomerReference/{merchantCustomerReference}/merchantProductCode/{merchantProductCode}/currency/{currency}
Headers:	Authorization: Bearer Accept: application/json OR application/xml
Parameters:	N/A
Request Method	POST

REST-Style parameterized URL with optional currency parameter omitted.

Argument Name	Merchant Payment Request
URI:	https://www.mypaga.com/paga-webservices/oauth2/secure/merchantPayment/v3/referenceNumber/{referenceNumber}/amount/{amount}/merchantCustomerReference/{merchantCustomerReference}/merchantProductCode/{merchantProductCode}
Headers:	Authorization: Bearer Accept: application/json OR application/xml
Parameters:	N/A
Request Method	POST

REST-style parameterized URL with the optional currency AND product code parameters omitted

Argument Name	Merchant Payment Request
URI:	https://www.mypaga.com/paga-webservices/oauth2/secure/merchantPayment/v3/referenceNumber/{referenceNumber}/amount/{amount}/merchantCustomerReference/{merchantCustomerReference}
Headers:	Authorization: Bearer Accept: application/json OR application/xml
Parameters:	N/A
Request Method	POST

Regular non-parameterized HTTP POST URL with request parameters

Argument Name	Merchant Payment Request
URI:	https://www.mypaga.com/paga-webservices/oauth2/secure/merchantPayment/v3
Headers:	Authorization: Bearer Accept: application/json OR application/xml
Parameters:	referenceNumber={referenceNumber}&amount={amount}&merchantCustomerReference={merchantCustomerReference}
Request Method	POST

**Sample Request and Response**

curl --location --request POST 'https://beta.mypaga.com/paga-webservices/oauth2/secure/merchantPayment/v3/?referenceNumber=b98456152-9e68-4c2e-9f58-3bbb3758&amount=1000&merchantCustomerReference=9995363&merchantProductCode=4353ww&currency=NGN' \
--header 'Authorization: Bearer e4bec0ce-b566-40b7-a8d3-c72266bbc883' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \

{
            "errorCode": 0,
            "errorMessage": "Success",
            "errorCategory": null,
            "amount": 1000,
            "transactionId": "VF43V",
            "confirmationCode": "8900052UILM",
            "agentCommission": 0,
            "fee": 0,
            "currency": "NGN",
            "exchangeRate": null
        }

Response Parameter
NB: All fields are mandatory

Argument Name	Type	Description
errorCode	String	Status code of the response. 0 indicates a successful response. Details of error codes
errorMessage	String	Describes the status of the request. Whether it succeeds or fails
errorCategory	String	Describes the source of the error e.g System error, User error etc.
amount	Double	The amount of the merchant payment
transactionId	String	If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
confirmationCode	String	A code returned by the merchant in response to the transaction, typically intended for the payer (eg. token, voucher number, receipt/invoice number etc.)
agentCommission	String	Agent commission for this transaction
fee	Double	If successful, the fee/tariff charged to the user for the transaction e.g VAT(Value Added Tax)
currency	String	The currency of the request
exchangeRate	Double	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

2. Money Transfer

This operation allows you to credit a user's Paga account.

Request Parameter

Argument Name	Type	Mandatory(M)/Optional(O)	Description
referenceNumber	String	M	This is a unique reference number provided by the client to uniquely identify the transaction and for use in retrieving the transaction records later
amount	double	M	Amount to be transferred
skipMessaging	boolean	M	Turn off Notification of User about payment made to their account.

Request Samples
There are several ways in which this operation can be executed

REST-type url with the referenceNumber and user's publicId provided.

1. REST-style parameterized URL with all parameters provided

Argument Name	Money Transfer Request
URI:	https://mypaga.com/paga-webservices/oauth2/secure/moneyTransfer/v3/amount/{amount}/destinationPhoneNumber/{destinationPhoneNumber}/referenceNumber/{referenceNumber}
Headers:	Authorization: Bearer Accept: application/json
Parameters:	N/A
Request Method	POST

2. REST-style parameterized URL with the optional skipMessaging parameter omitted

Argument Name	Money Transfer Request
URI:	https://mypaga.com/paga-webservices/oauth2/secure/moneyTransfer/v3/amount/{amount}/destinationPhoneNumber/{destinationPhoneNumber}/skipMessaging/{skipMessaging}/referenceNumber/{referenceNumber}
Headers:	Authorization: Bearer Accept: application/json
Parameters:	N/A
Request Method	POST

**Sample Request and Response** **

Http Headers:
			Authorization: Bearer d3bad54d-8586-48f1-bc0e-c9132b05e237

https://mypaga.com/paga-webservices/oauth2/secure/moneyTransfer/v3/?referenceNumber=1e2de470-0605-442d-96e3-3e61976ea4cb&amount=2000&skipMessaging=false

{
    "moneyTransferResult": {
      "errorCode": 0,
      "errorMessage": "Success",
      "errorCategory": null,
      "transactionId": 23400,
      "amount": 500.0,
      "fee": 50.0,
      "currency": null,
      "exchangeRate": null,
      "withdrawalCode": null
    }
  }

Response Parameter
NB: All fields are mandatory

Argument Name	Type	Description
errorCode	String	Status code of the response. 0 indicates a successful response. Details of error codes
errorMessage	String	Describes the status of the request. Whether it succeeds or fails
errorCategory	String	Describes the source of the error e.g System error, User error etc.
transactionId	String	If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
amount	Double	The amount of the money transfer
fee	Double	If successful, the fee/tariff charged to the user for the transaction e.g VAT(Value Added Tax)
exchangeRate	Double	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
withdrawalCode	String	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.

3. User Details

This operation allows the client to get the user's personal details. The data requested is included in the authentication and authorization request.
Request Parameter

Argument Name	Type	Mandatory(M)/Optional(O)	Description
referenceNumber	String	M	This is a unique reference number provided by the client to uniquely identify the request.
publicId	String	O	This public Id is passed if the request is initiated from a web redirect, e.g. from the Paga business portal. In order to verify that the request is genuine, the parameter is passed along. Normal requests won't require that parameter.

Request Samples
There are several ways in which this operation can be executed

REST-type URL with the referenceNumber and user's publicId provided.

Argument Name	User Details Request
URI:	https://mypaga.com/paga-webservices/oauth2/secure/getUserDetails/v2/publicId/{publicId}/referenceNumber/{referenceNumber}
Headers:	Authorization: Bearer Accept: application/json
Parameters:	N/A
Request Method	POST

REST-type URL with only the referenceNumber provided

Argument Name	User Details Request
URI:	https://mypaga.com/paga-webservices/oauth2/secure/getUserDetails/v2/referenceNumber/{referenceNumber}
Headers:	Authorization: Bearer Accept: application/json
Parameters:	N/A
Request Method	POST

Sample Request and Response

Http Headers:
			Authorization: Bearer d3bad54d-8586-48f1-bc0e-c9132b05e237

https://mypaga.com/paga-webservices/oauth2/secure/getUserDetails/v2/?referenceNumber=1e2de470-0605-442d-96e3-3e61976ea4cb

{
    "detailsResult": {
      "errorCode": 0,
      "errorMessage": "Success",
      "errorCategory": null,
      "details": {
        "publicId": "CDAA6432-5416-44D9-894A-0349EA84575D",
        "lastName": "Doe",
        "username": "johndoe",
        "accountBalance": 9918800.0,
        "firstName": "John",
        "email": "[email protected]"
      }
    }
  }

**Response Parameter**

Argument Name	Type	Mandatory(M)/Optional(O)	Description
errorCode	String	M	Status code of the response. 0 indicates a successful response. Details of error codes
errorMessage	String	M	Describes the status of the request. Whether it succeeds or fails.
errorCategory	String	M	Describes the source of the error e.g System error, User error etc.
details	json	M	User Information
details.publicId	String	O	PublicId of the user
details.lastName	String	O	Last name of the user
details.username	String	O	Username of the user
details.accountBalance	String	O	Account balance of the user
details.firstName	String	O	First name of the user
details.email	String	O	Email of the user

4. Money Transfer To Bank

This operation allows you to credit a user's bank account.

Request Parameter

Argument Name	Type	Mandatory(M)/Optional(O)	Description
externalReferenceNumber	String	M	This is a unique reference number provided by the client to uniquely identify the transaction and for use in retrieving the transaction records later
amount	Double	M	Amount transferred
destinationBankPublicId	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	M	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.
recipientFirstName	String	M	The first name of the recipient.
recipientLastNam	String	M	The last name of the recipient.
recipientEmail	String	O	The email of the recipient.

Request Samples
1. REST-style parameterized URL with all parameters provided

Argument Name	Money Transfer To Bank Request
URI:	https://mypaga.com/paga-webservices/oauth2/secure/moneyTransferToBank/v2/amount/{amount}/destinationBankPublicId/{destinationBankPublicId}/destinationBankAccountNumber/{destinationBankAccountNumber}/recipientPhoneNumber/{recipientPhoneNumber}/recipientFirstName/{recipientFirstName}/recipientLastName/{recipientLastName}/recipientEmail/{recipientEmail}/externalReferenceNumber/{externalReferenceNumber}
Headers	Authorization: Bearer Accept: application/json
Parameters:	N/A
Request Method	POST

Sample Request and Response

Http Headers:
			Authorization: Bearer d3bad54d-8586-48f1-bc0e-c9132b05e237

https://mypaga.com/paga-webservices/oauth2/secure/moneyTransferToBank/v2/amount/1000/destinationBankPublicId/40090E2F-7446-4217-9345-7BBAB7043C4C/destinationBankAccountNumber/0000000000/recipientPhoneNumber/+2347020898888/recipientFirstName/John/recipientLastName/Doe/recipientEmail/[email protected]/externalReferenceNumber/23445555666

{
            "errorCode": 0,
      			"errorMessage": "Success",
      			"errorCategory": null,
            "transferReferenceNumber": "00000001089406",
            "transactionId": 1235522,
            "amount": 100,
            "fee": 52.5,
            "currency": "NGN",
            "exchangeRate": null,
            "accountHolderNameAtBank": "Test Customer",
            "vatFee": 0
        }

Response Parameter
NB: All fields are mandatory

Argument Name	Type	Description
errorCode	String	Status code of the response. 0 indicates a successful response. Details of error codes
errorMessage	String	Describes the status of the request. Whether it succeeds or fails.
errorCategory	String	Describes the source of the error e.g System error, User error etc.
transferReferenceNumber	String	The same reference number that was passed in the request
transactionId	String	If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
amount	Double	Amount transferred
fee	Double	If successful, the fee/tariff that would be charged from your Paga account for the deposit to bank to this recipient
currency	String	The currency of the request
exchangeRate	Double	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
accountHolderNameAtBank	String	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.
vatFee	Double	If successful, the fee/tariff charged to the user for the transaction e.g VAT(Value Added Tax)

5. Revoke Authorization

This operation allows Paga customers to revoke the authorization they granted a particular merchant.

Request Parameter

Argument Name	Type	Mandatory(M)/Optional(O)	Description
accountIdentifier	String	M	The account identifier of the customer revoking the authorization. This account identifier may be a phone number, account nickname(username), NUBAN number, or email associated with the customer's Paga account.
publicId	String	M	The Paga merchant UUID identifying the merchant to which the authorization was granted.

Request Samples
1. REST-style parameterized URL with all parameters provided

Argument Name	Revoke Authorization
URI:	https://www.mypaga.com/paga-webservices/paga-webservices/oauth2/secure/revokeAuthorization
Request Method:	DELETE
Headers:	Authorization: Bearer Accept: application/json OR application/xml
Parameters:	accountIdentifier={accountIdentifier}&organizationPublicId={organizationPublicId}

Sample Request and Response

Http Headers:
			Authorization: Bearer d3bad54d-8586-48f1-bc0e-c9132b05e237

https://www.mypaga.com/paga-webservices/oauth2/secure/revokeAuthorization?accountIdentifier=2e73a791-735f-4834-924e-26cb25248f95&organizationPublicId=4220263C-E234-49DA-8E64-ECD6089AF4A8

{
  errorMessage: 'Success', 
  errorCode: 0, 
  errorCategory: null 
}

Response Parameter
NB: All fields are mandatory

Argument Name	Type	Description
errorMessage	String	Status code of the response. 0 indicates a successful response.
errorCode	String	Describes the status of the request. Whether it succeeds or fails.Details of error codes
errorCategory	String	Describes the source of the error e.g System error, User error etc.

6. Verify Transaction

The Verify transaction operation allows an integrated 3rd party to check the status of a previous operation using the operation's reference number and the publicId of the 3rd party.

Request Parameter

Argument Name	Type	Mandatory(M)/Optional(O)	Description
referenceNumber	String	M	The reference number provided at the original operation for which the status is being queried
publicId	String	M	The Paga merchant UUID identifying the merchant.

Request Samples

REST-style parameterized URL with all parameters provided

Argument Name	Verify Transaction
URI:	https://www.mypaga.com/paga-webservices/oauth2/secure/verifyTransaction
Headers:	Authorization: Bearer Accept: application/json OR application/xml
Parameters:	referenceNumber={referenceNumber}&publicId={publicId}
Request Method:	POST

Sample Request and Response

Http Headers:
			Authorization: Bearer d3bad54d-8586-48f1-bc0e-c9132b05e237

https://www.mypaga.com/paga-webservices/oauth2/secure/verifyTransaction?referenceNumber=fc420e18-93ca-4160-a8e3-9d541252a4d8&publicId=4220263C-E234-49DA-8E64-ECD6089AF4A8

{
        "errorMessage": "Success",
        "errorCode": 0,
        "errorCategory": null,
        "referenceNumber": "bd7c0790-2f77-4d5d-8be1-872d62991134",
        "status": "SUCCESSFUL",
        "merchantReference": null,
        "dateTimeUTC": 1628543810777,
        "transactionType": "USER_SEND_CASH_TO_BANK_ACCOUNT_SETTLED",
        "amount": 1000,
        "transactionId": "QR20B",
        "channel": "OAUTH_WIDGET",
        "byAgent": false,
        "currency": "NGN",
        "exchangeRate": null,
        "foreignCurrencyAmount": null,
        "foreignCurrency": null
    }

Response parameter
NB: All fields are mandatory

Argument Name	Type	Description
errorMessage	String	Status code of the response. 0 indicates a successful response.
errorCode	String	Describes the status of the request. Whether it succeeds or fails. Details of error codes
referenceNumber	String	The same reference number that was passed in the request
errorCategory	String	Describes the source of the error e.g System error, User error etc.
status	String	Status of the transaction that is been verified.
merchantReference	String	The account/reference number identifying the customer on the merchant's system
dateTimeUTC	String	Date of the transaction
transactionType	String	An enum representing the type of transaction executed
amount	Double	The amount of the transaction
transactionId	String	If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
channel	String	Medium in which the transaction was carried out recognised by Paga. e.g OAUTH_WIDGET
byAgent	Boolean	This states if the transaction was carried out via an agent.
currency	String	The currency of the request
exchangeRate	Double	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
foreignCurrencyAmount	Double	If the transaction request was specified in a foreign currency, this is the amount for that transaction based on the foreign currency.
foreignCurrency	String	The foreign currency of the request

7. Refund Bill Pay

This service allows merchants to fully or partially refund bill payments previously made to them by a customer. The refund specified may be in full or a partial amount.

Request Parameter

Argument Name	Type	Mandatory(M)/Optional(O)	Description
transactionReferenceNumber	String	M	The unique reference number provided as part of the original transaction which identifies the transaction to be refunded
amount	Double	M	Indicates the amount to be refunded.
reason	String	O	Human readable reason for refund
referenceNumber	String	M	A unique reference number for this request. This same reference number will be returned in the response
isFullRefund	Boolean	M	Indicates whether the refund is full or partial

Request Samples
REST-style parameterized URL with all parameters provided

Argument Name	Refund Bill Pay
URI:	https://www.mypaga.com/paga-webservices/oauth2/secure/merchantPaymentRefund/v3
Headers:	Authorization: Bearer Accept: application/json OR application/xml
Parameters:	transactionReferenceNumber={transactionReferenceNumber}&amount={amount}&reason={reason}&referenceNumber={referenceNumber}&isFullRefund={isFullRefund}
Request Method	POST

Sample Request and Response

curl --location --request POST 'https://beta.mypaga.com/paga-webservices/oauth2/secure/merchantPaymentRefund/v3?transactionReferenceNumber=b456152-9e68-4c2e-9f58-3bbb375&amount=1000&reason=mistakenly paid for goods&referenceNumber=c456152-9h68-4c2e-9f58-3acb375&isFullRefund=true' \
--header 'Authorization: Bearer e4bec0ce-b566-40b7-a8d3-c72266bbc883' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \

{
    errorMessage: 'Success',
    errorCode: 0,
    errorCategory: null,
    amount: 500,
    transactionId: 'BP-C_R_20210917103028504_1264810_5304C',
    referenceNumber: '35ea2996-d3ff-4277-ade4-f9996779863a',
    originalTransactionId: 'BP-C_20210917102747364_1264793_5KQHR',
    fee: 0,
    currency: 'NGN'
  }

Response Parameter
NB: All fields are mandatory

Argument Name	Type	Description
errorMessage	String	Status code of the response. 0 indicates a successful response.
errorCode	String	Describes the status of the request. Whether it succeeds or fails.Details of error codes
errorCategory	String	Describes the source of the error e.g System error, User error etc.
amount	Double	The amount to be refunded
transactionId	String	If successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
referenceNumber	String	The same reference number that was passed in the request
originalTransactionId	String	The reference number that was passed carrying out the transaction that is been verified.
Fee	Double	If successful, the fee/tariff charged to the user for the transaction e.g VAT(Value Added Tax)
currency	String	The currency of the request

8. Error Codes

Below are the Paga Connect Error codes and description

ERROR CODE	ERROR CATEGORY	ERROR MESSAGE
0	NULL	Success
10102	USER_ERROR	Duplicate Process
10103	USER_ERROR	Insufficient funds
10104	USER_ERROR	Invalid device activation code
11101	SYSTEM_ERROR	An error occurred - while processing transaction