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 secured operation request to impersonate the user credibly. The secure operation URI depends on the operation being executed, and are 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:
Authorization = Bearer 3cad5173-7b2a-4626-86be-0ff67804bd59Output Formating
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.
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 = <unique reference number>
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>
Amount to charge the usermerchantCustomerReference = <your customer identification> Unique identifier for your customer eg. Phone number, email, id etc.
merchantProductCode = <your product code>
This is an optional code that you can use to verify your payments.
currency = <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
1. REST-Style parameterized URL with all parameters provided.
Merchant Payment Request
URI: https://mypaga.com/paga-webservices/oauth2/secure/merchantPayment/referenceNumber/{referenceNumber}/amount/{amount}/
merchantCustomerReference/{merchantCustomerReference}/merchantProductCode/{merchantProductCode}/currency/{currency}
Headers: Authorization: Bearer <access token>
Accept: application/json |or application/xml
Parameters: N/A2. REST-Style parameterized URL with optional currency parameter omitted.
Merchant Payment Request
URI: https://mypaga.com/paga-webservices/oauth2/secure/merchantPayment/referenceNumber/{referenceNumber}/amount/{amount}/
merchantCustomerReference/{merchantCustomerReference}/merchantProductCode/{merchantProductCode}
Headers: Authorization: Bearer <access token>
Accept: application/json |or application/xml
Parameters: N/A3. REST-style parameterized URL with the optional currency AND product code parameters omitted
Merchant Payment Request
URI: https://mypaga.com/paga-webservices/oauth2/secure/merchantPayment/referenceNumber/{referenceNumber}/amount/{amount}/
merchantCustomerReference/{merchantCustomerReference}
Headers: Authorization: Bearer <access token>
Accept: application/json |or application/xml
Parameters: N/A4. Regular non-parameterized http POST URL with request parameters
Merchant Payment Request
URI: https://mypaga.com/paga-webservices/oauth2/secure/merchantPayment
Headers: Authorization: Bearer <access token>
Accept: application/json |or application/xml
Parameters: referenceNumber={referenceNumber}&amount={amount}&merchantCustomerReference={merchantCustomerReference}Response Sample
Sample Merchant Payment Responses
JSON: {"merchantPaymentResult":
{ "amount":600.0,"transactionId":"00PF9","confirmationCode":0124HDSUE,
"agentCommission":null,"fee":0.0,
"currency":null,"exchangeRate":null
}
}
XML: <result>
<amount>5000.0</amount>
<transactionId>9P3V4</transactionId>
<fee>0.0</fee>
<confirmationCode>0124HDSUE</confirmationCode>
<agentCommission></agentCommission>
<currency></currency>
<exchangeRate></exchangeRate>
</result>
On this page:
- 1 Overview
- 1.1 Authorization
- 1.2 Output Formating
- 2 Secure Operations
- 3 1. Merchant Payments
- 3.1 Parameters passed to the operation
- 3.2 1. REST-Style parameterized URL with all parameters provided.
- 3.2.1 Merchant Payment Request
- 3.3 2. REST-Style parameterized URL with optional currency parameter omitted.
- 3.3.1 Merchant Payment Request
- 3.4 3. REST-style parameterized URL with the optional currency AND product code parameters omitted
- 3.4.1 Merchant Payment Request
- 3.5 4. Regular non-parameterized http POST URL with request parameters
- 3.5.1 Merchant Payment Request
- 3.6 Response Sample
- 4 3. User Details
- 4.1 Parameters passed to the operation.
- 4.2 Request Samples
- 4.3 REST-type url with the referenceNumber and user's publicId provided.
- 4.3.1 User Details Request
- 4.4 REST-type url with only the referenceNumber provided
- 4.4.1 User Details Request
- 4.5 Regular non-parameterized http POST URL with request parameters
- 4.5.1 User Details Request
- 4.6 Sample Response
- 4.6.1 User Details Response
- 4.7 Error Response
- 5 Next: Customizing the Look and Feel
- 6 Related Articles
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
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.
User Details Request
URI: https://mypaga.com/paga-webservices/oauth2/secure/getUserDetails/publicId/<publicId>/referenceNumber/<referenceNumber>
Headers: N/A
Parameters: referenceNumber : <referenceNumber>(required)
publicId : <publicId>REST-type url with only the referenceNumber provided
User Details Request
URI: https://mypaga.com/paga-webservices/oauth2/secure/getUserDetails/referenceNumber/<referenceNumber>
Headers: N/A
Parameters: referenceNumber : <referenceNumber>(required)Regular non-parameterized http POST URL with request parameters
User Details Request
URI: https://mypaga.com/paga-webservices/oauth2/secure/getUserDetails
Headers: N/A
Parameters: referenceNumber : <referenceNumber>(required)
publicId : <publicId>Sample Response
User Details Response
JSON: { "detailsResult":
{ "errorCode":null,"errorMessage":null,"details":
{ "publicId":"CDAA6432-5416-44D9-894A-0349EA84575D","lastName":"Doe",
"username":"johndoe","accountBalance":9918800.0,"firstName":"John",
"email":"xxxxxxxx@gmail.com"
}
}
}
XML: <detailsResult>
<details>
<entry><string>publicId</string><string>CDAA6432-5416-44D9-894A-0349EA84575D</string></entry>
<entry><string>lastName</string><string>Doe</string></entry>
<entry><string>username</string><string>johndoe</string></entry>
<entry><string>accountBalance</string><double>9918800.0</double></entry>
<entry><string>firstName</string><string>John</string></entry>
<entry><string>email</string><string>xxxxxxxxx@gmail.com</string></entry>
</details>
</detailsResult>Error Response
User Details Respons (Error)
URI: N/A (HTTP response)
Headers: N/A
Parameters: errorCode=<error code>
error_description=<error description>