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¤cy=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 |
Updated over 1 year ago