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

  1. 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

  1. 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

  1. 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**
Http Headers:
            Authorization: Bearer d3bad54d-8586-48f1-bc0e-c9132b05e237

https://www.mypaga.com/paga-webservices/oauth2/secure/merchantPayment/v3/referenceNumber/1e2de470-0605-442d-96e3-3e61976ea4cb/amount/2000/merchantCustomerReference/353ww5673636/merchantProductCode/23WER/currency/NGN
{
            "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/referenceNumber/{referenceNumber}/amount/{amount}/skipMessaging/{skipMessaging}

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/referenceNumber/{referenceNumber}/amount/{amount}/

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

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

  1. 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

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}

Request Method

POST

Sample Request and Response

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


https://www.mypaga.com/paga-webservices/oauth2/secure/merchantPaymentRefund/v3?transactionReferenceNumber=1e2de470-0605-442d-96e3-3e61976ea4cb&amount=500&reason=&referenceNumber=6087aa0a-32d0-4c06-9bb0-e8c1fead7a59
{
    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