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.

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-0ff67804bd59

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

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 user

• merchantCustomerReference = <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.

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/A

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

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/A

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

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/A

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

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

 
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>

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.

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

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

URI:		https://mypaga.com/paga-webservices/oauth2/secure/getUserDetails
 
Headers:	N/A
 
Parameters:	referenceNumber : <referenceNumber>(required)
			publicId : <publicId>

Sample 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

URI:		N/A (HTTP response)
Headers:	N/A
Parameters:	errorCode=<error code>
			error_description=<error description>

Next: Customizing the Look and Feel