Paga Connect Operations

Overview

Once you've acquired an access code for a user, your Client will store the access token and provide it with a secured operation request to impersonate the user credibly. The secure operation URI depends on the operation being executed and is listed later.

📘

Obtaining an Access Token

Please see the Getting Started Article for how to obtain an access token.

Authorization
When executing a secured operation, per the specification, the Access Token is provided as a HTTP header with the ‘Bearer’ prefix eg. if the access token value is 3cad5173-7b2a-4626-86be-0ff67804bd59, the header would be:

Output Formatting
For the secured resource requests you should supply the HTTP Accept header to determine the formatting of the response sent back from the operation. The header value must be either application/json (for a JSON formatted response body) or application/xml (for XML formatted response body). The default if not specified is application/json.

Secure Operations

The following Secure operations can be performed.

📘

Response Type

Paga supports both XML and JSON response types. However JSON is the recommended format.

Test base-url : https://beta.mypaga.com/
Live base-url: https://www.mypaga.com/

1. Merchant Payments

This is the operation executed to make a payment to you on behalf of the customer.

Parameters passed to the operation

• referenceNumber =
  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 =
  Amount to charge the user

• merchantCustomerReference =
  Unique identifier for your customer eg. Phone number, email, id etc.

• merchantProductCode =
  This is an optional code that you can use to verify your payments.

• currency =
  This is the currency code of the transaction, NGN is the only supported currency as of now (February 2016)

There are several ways in which this operation can be executed, as listed below

Request Parameter

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

2. REST-Style parameterized URL with optional currency parameter omitted.

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

4. Regular non-parameterized http POST URL with request parameters

Response Sample

Sample Merchant Payment Responses

{"merchantPaymentResult":
            {   "amount":600.0,"transactionId":"00PF9","confirmationCode":0124HDSUE,
                "agentCommission":null,"fee":0.0,
                "currency":null,"exchangeRate":null
            }
        }

2. Money Transfer

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

The parameters provided for this operation are:

• referenceNumber =
  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 =
  Amount to be transferred

• skipMessaging =
  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

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

Response Sample

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

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 in the data parameter. Additionally, the scope parameter must contain the USER_DETAILS_REQUEST option.

• FIRST_NAME: Get the user's first name
• LAST_NAME: Get the user's last name
• MOBILE_NUMBER: Get the user's paga mobile number
• EMAIL: Get the user's paga email address.
• USERNAME: Get the user's paga username
• ACCOUNT_BALANCE: To get the user's account balance
• PAGA_NUBAN: To get the user's PAGA NUBAN

Parameters passed to the operation.

• publicId (optional)
  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.

• referenceNumber
  This is a unique reference number provided by the client to uniquely identify the transaction and for use in retrieving the transaction records later.

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

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

REST-type URL with only the referenceNumber provided

Regular non-parameterized http POST URL with request parameters

Sample Response
User Details Response

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

Error Response

4. Money Transfer To Bank

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

The parameters provided for this operation are:

• externalReferenceNumber =
  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 =
  Amount to be transferred

• destinationBankPublicId =
  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 =
  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 =
  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 =
  The first name of the recipient.

• recipientLastName =
  The last name of the recipient.

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

Regular non-parameterized http POST URL with request parameters

Sample Response
Money Transfer to Bank Response

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