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 NameTypeMandatory(M)/Optional(O)Description
referenceNumberStringMThis is a unique reference number provided by the client to uniquely identify the transaction and for use in retrieving the transaction records later
amountDoubleMAmount to charge the user
merchantCustomerReferenceStringMUnique identifier for your customer eg. Phone number, email, id etc.
merchantProductCodeStringOThis is an optional code that you can use to verify your payments.
currencyStringOThis 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 NameMerchant 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 MethodPOST
  1. REST-Style parameterized URL with optional currency parameter omitted.
Argument NameMerchant 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 MethodPOST
  1. REST-style parameterized URL with the optional currency AND product code parameters omitted
Argument NameMerchant 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 MethodPOST
  1. Regular non-parameterized HTTP POST URL with request parameters
Argument NameMerchant 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 MethodPOST

**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 NameTypeDescription
errorCodeStringStatus code of the response. 0 indicates a successful response.
Details of error codes
errorMessageStringDescribes the status of the request. Whether it succeeds or fails
errorCategoryStringDescribes the source of the error e.g System error, User error etc.
amountDoubleThe amount of the merchant payment
transactionIdStringIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
confirmationCodeStringA code returned by the merchant in response to the transaction, typically intended for the payer (eg. token, voucher number, receipt/invoice number etc.)
agentCommissionStringAgent commission for
this transaction
feeDoubleIf successful, the fee/tariff charged to the user for the transaction e.g VAT(Value Added Tax)
currencyStringThe currency of the request
exchangeRateDoubleIf 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 NameTypeMandatory(M)/Optional(O)Description
referenceNumberStringMThis is a unique reference number provided by the client to uniquely identify the transaction and for use in retrieving the transaction records later
amountdoubleMAmount to be transferred
skipMessagingbooleanMTurn 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 NameMoney Transfer Request
URI:https://mypaga.com/paga-webservices/oauth2/secure/moneyTransfer/v3/referenceNumber/{referenceNumber}/amount/{amount}/skipMessaging/{skipMessaging}
Headers:Authorization: Bearer
Accept: application/json
Parameters:N/A
Request MethodPOST

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

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

**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 NameTypeDescription
errorCodeStringStatus code of the response. 0 indicates a successful response.
Details of error codes
errorMessageStringDescribes the status of the request. Whether it succeeds or fails
errorCategoryStringDescribes the source of the error e.g System error, User error etc.
transactionIdStringIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
amountDoubleThe amount of the money transfer
feeDoubleIf successful, the fee/tariff charged to the user for the transaction e.g VAT(Value Added Tax)
exchangeRateDoubleIf 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
withdrawalCodeStringIf 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 NameTypeMandatory(M)/Optional(O)Description
referenceNumberStringMThis is a unique reference number provided by the client to uniquely identify the request.
publicIdStringOThis 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 NameUser 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 MethodPOST

REST-type URL with only the referenceNumber provided

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

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 NameTypeMandatory(M)/Optional(O)Description
errorCodeStringMStatus code of the response. 0 indicates a successful response.
Details of error codes
errorMessageStringMDescribes the status of the request. Whether it succeeds or fails.
errorCategoryStringMDescribes the source of the error e.g System error, User error etc.
detailsjsonMUser Information
details.publicIdStringOPublicId of the user
details.lastNameStringOLast name of the user
details.usernameStringOUsername of the user
details.accountBalanceStringOAccount balance of the user
details.firstNameStringOFirst name of the user
details.emailStringOEmail of the user

4. Money Transfer To Bank

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


Request Parameter

Argument NameTypeMandatory(M)/Optional(O)Description
externalReferenceNumberStringMThis is a unique reference number provided by the client to uniquely identify the transaction and for use in retrieving the transaction records later
amountDoubleMAmount transferred
destinationBankPublicIdStringMThe 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.
destinationBankAccountNumberStringMThe 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.
recipientPhoneNumberStringMThe 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.
recipientFirstNameStringMThe first name of the recipient.
recipientLastNamStringMThe last name of the recipient.
recipientEmailStringOThe email of the recipient.

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

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 NameTypeDescription
errorCodeStringStatus code of the response. 0 indicates a successful response.
Details of error codes
errorMessageStringDescribes the status of the request. Whether it succeeds or fails.
errorCategoryStringDescribes the source of the error e.g System error, User error etc.
transferReferenceNumberStringThe same reference number that was passed in the request
transactionIdStringIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
amountDoubleAmount transferred
feeDoubleIf successful, the fee/tariff that would be charged from your Paga account for the deposit to bank to this recipient
currencyStringThe currency of the request
exchangeRateDoubleIf 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
accountHolderNameAtBankStringIf 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.
vatFeeDoubleIf 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 NameTypeMandatory(M)/Optional(O)Description
accountIdentifierStringMThe 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.
publicIdStringMThe Paga merchant UUID identifying the merchant to which the authorization was granted.

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

Argument NameRevoke 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 NameTypeDescription
errorMessageStringStatus code of the response. 0 indicates a successful response.
errorCodeStringDescribes the status of the request. Whether it succeeds or fails.Details of error codes
errorCategoryStringDescribes 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 NameTypeMandatory(M)/Optional(O)Description
referenceNumberStringMThe reference number provided at the original operation for which the status is being queried
publicIdStringMThe Paga merchant UUID identifying the merchant.

Request Samples

  1. REST-style parameterized URL with all parameters provided
Argument NameVerify 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 NameTypeDescription
errorMessageStringStatus code of the response. 0 indicates a successful response.
errorCodeStringDescribes the status of the request. Whether it succeeds or fails. Details of error codes
referenceNumberStringThe same reference number that was passed in the request
errorCategoryStringDescribes the source of the error e.g System error, User error etc.
statusStringStatus of the transaction that is been verified.
merchantReferenceStringThe account/reference number identifying the customer on the merchant's system
dateTimeUTCStringDate of the transaction
transactionTypeStringAn enum representing the type of transaction executed
amountDoubleThe amount of the transaction
transactionIdStringIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
channelStringMedium in which the transaction was carried out recognised by Paga. e.g OAUTH_WIDGET
byAgentBooleanThis states if the transaction was carried out via an agent.
currencyStringThe currency of the request
exchangeRateDoubleIf 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
foreignCurrencyAmountDoubleIf the transaction request was specified in a foreign currency, this is the amount for that transaction based on the foreign currency.
foreignCurrencyStringThe 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 NameTypeMandatory(M)/Optional(O)Description
transactionReferenceNumberStringMThe unique reference number provided as part of the original transaction which identifies the transaction to be refunded
amountDoubleMIndicates the amount to be refunded.
reasonStringOHuman readable reason for refund
referenceNumberStringMA unique reference number for this request. This same reference number will be returned in the response
isFullRefundBooleanMIndicates whether the refund is full or partial

Request Samples
REST-style parameterized URL with all parameters provided

Argument NameRefund 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 MethodPOST

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 NameTypeDescription
errorMessageStringStatus code of the response. 0 indicates a successful response.
errorCodeStringDescribes the status of the request. Whether it succeeds or fails.Details of error codes
errorCategoryStringDescribes the source of the error e.g System error, User error etc.
amountDoubleThe amount to be refunded
transactionIdStringIf successful, the short transaction id which is provided to all parties involved in the transaction to easily identify the transaction
referenceNumberStringThe same reference number that was passed in the request
originalTransactionIdStringThe reference number that was passed carrying out the transaction that is been verified.
FeeDoubleIf successful, the fee/tariff charged to the user for the transaction e.g VAT(Value Added Tax)
currencyStringThe currency of the request

8. Error Codes

Below are the Paga Connect Error codes and description

ERROR CODEERROR CATEGORYERROR MESSAGE
0NULLSuccess
10102USER_ERRORDuplicate Process
10103USER_ERRORInsufficient funds
10104USER_ERRORInvalid device activation code
11101SYSTEM_ERRORAn error occurred - while processing transaction