Getting Started

1. Introduction

Paga Connect utilizes the OAuth 2.0 Specification to enable secure integration with our 3rd party clients. Paga connect is currently implemented based on the final release of the OAuth2 Specification (RFC6749).

The OAuth 2.0 Specification uses well established web standards and is available on a multitude of platforms and programming languages. A comprehensive list of supported languages, frameworks, services as well as beginner tutorials can be found at the following links below.

🚧
Note
It is advisable to read and be familiar with the OAuth 2.0 specification before continuing with the rest of the Documentation.

2. Considerations when choosing an implementation

The OAuth 2.0 Specification is based on Web standards, so it is possible to create a custom implementation of the relevant part of the specification, however it's advisable to find a stable and complete implementation of the Specification.

There are a lot of implementations of the OAuth 2.0 specification, however some of them implement the specification to various degrees. Ensure that your implementation can handle the relevant part of the specification. Mobile app developers should preferably look for a lightweight implementation of the specification, while standard web applications can go for the more complete implementations. Paga connect implements the Authorization Code flow of the OAuth 2.0 specification.

🚧
Note
OAuth 2.0 is not the same as OAuth 1.0. There is very little compatibility between the two specifications, don't use an OAuth 1.0 client implementation.

❗️
Browser Support
Paga connect requires HTML 5 support. Browsers with no or partial support for HTML5 might encounter unexpected behaviour.

3. Paga Connect Basic Flow

The OAuth2 service implemented by Paga Connect conforms to the standard specification, below is the Authorization Code flow.

High-level flow
In order to make requests on behalf of a user, the OAuth2 Client must obtain an Access Token from the OAuth2 Service and provide the Access Token with each request on behalf of the user. The Access Token represents the permission that the user and the service have provided to the Client to make specific requests on behalf of the user.

Obtaining The Authorization Code

Forward the user to the authorization endpoint URI (see authorization URI below).
The user will be asked to authenticate, and authorize the Client to execute operations on their behalf.
After validating authorization from the user, we will redirect the user’s agent back to a Uri provided by you (redirect_uri parameter provided with authorization request) and include in there a one-time Authorization Code.
Your Client will extract the Authorization Code and make a separate request (not visible to the user) to get an Access Token, providing the one-time Authorization Code and your Client credentials (client id and password provided to you).
If the request for the Access Token is valid, we will return a new Access Token in the response.
Your Client can now make requests to secure URIs on behalf of the user, by providing the Access Token with the request.

See Fig 1.0 Below for more information.

4. Paga Authentication Details

As of this time, Paga connect authentication details have to be obtained directly from Paga. That will change in the near future.

STEP 1
The steps required to obtain authentication details are outlined below.

Create a Paga Business account
Register your redirect_uri on your business profile dashboard
Send an email to the Paga Operations Support team.
You will be contacted by a Paga representative that will provide you with the information you require.

STEP 2:
If you have completed STEP 1, you can follow the steps below to get your Public key, Secret key/Password, and Hmac.

Login to your Paga Business Account
Go to Manage Account,
Click on Manage API Keys.

5. Obtaining the Authorization Code

The first time you need to obtain an access token to execute secured operations on behalf of a user, you will need to obtain an authorization code which is provided if the user has authorized your client to obtain this access code. To do this, you will need to forward the user to the authorization URI. This typically means submit a POST or GET request from the User’s User-Agent (typically browser) or launching a browser session within the User’s app session and loading the Authorization URI.

Paga Connect Authorization URI
*https://www.mypaga.com/paga-webservices/oauth2/authorization*

Request Parameter
Authorization Code request parameters
The following parameters need to be passed along with the authorization code request.

Argument Name	Type	Mandatory (M)/Optional(O)	Description
client_id	String	M	This is an identifier for your OAuth 2.0 client. You will be assigned a unique client id for your client along with a client secret (password) that will be discussed later. Note that individual organizations would have multiple client ids if they implement multiple OAuth 2.0 clients.
response_type = code	String	M	This is a pre-determined constant per the specification to indicate that this request is for an authorization code
redirect_uri	String	M	This is the URI for your client that our OAuth2 server should redirect the user-agent back to after successful (or denied) authentication by the user
state	String	M	This is an optional state (data) that should be returned back to your client from the server with the response (can be used to persist information)
scope	String	M	It comprises requested permissions. It refers to space-delimited string that allows the client to specify the scope of access required. This scope is also used by the authorization server to inform the users of what permissions they are providing to the client. The scope parameters are outlined in table 1.0 below.
user_data	String	M	This refers to requested user information . It is an optional space-delimited string that allows the client to specify the scope of user data required. This scope is also used by the authorization server to inform the users of what permissions they are providing to the client. The user_data parameters are outlined in table 1.1 below.
display_name	String	O	This refers to an organization display name. Display names can be used for styling purposes as well. See the article on Customizing The Look and Feel for more information on styling. NB : If not provided, the default name of the organization linked to the client_id would be displayed.
logo_url	String	O	An organization can add its own logo by passing its logo URL as the value of the logo_url parameter.

Authorization Code scope

Scope	Description
MERCHANT_PAYMENT	This permission allows you to charge a user's Paga account
USER_REQUEST_ACCOUNT_BALANCE	This allows you to request the Paga user's account balance
MONEY_TRANSFER	This allows you to transfer money to a Paga account
USER_DETAILS_REQUEST	This allows you to request a user's details (See Table 1.1 for more info)
MERCHANT_PAYMENT_REFUND	The permission allows you to get a refund for a transaction carried out.

Table 1.0 Authorization Code Scope parameters

Authorization Code user_data parameter

User Data	Description
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

Table 1.1 User Details Request Parameters

Sample Authorization Code Request and Response
See sample Authorization Code Request and Response below.

📘
Authorization Code Response
The authorization code is derived from the code parameter attached to the redirect_uri.

<a href="https://www.mypaga.com/paga-webservices/oauth2/authorization?client_id=A3878DC1-F07D-48E7-AA59-8276C3C26647&response_type=code&redirect_uri=http://localhost:9000/video/pagaconnect&state=state&scope=USER_DEPOSIT_FROM_CARD+MERCHANT_PAYMENT+USER_DETAILS_REQUEST&user_data=FIRST_NAME+LAST_NAME+USERNAME+EMAIL" >
        <img src="./images/paywithpagabutton.png" alt="" />
</a>

http://localhost:3000/rent/getMovie?code=gGehRp&state=state

https://www.mypaga.com/paga-webservices/auth/authentication-error?authError=invalid_redirect&error_message=Sorry!%20An%20error%20occurred,%20please%20contact%20Paga%20or%20Blogoba%20fasa%20and%20report%20this%20error.

📘
Requesting User Details
In order to request user details, you will have to include the USER_DETAILS_REQUEST in the scope parameter, and the required user information in the user_data parameter.

👍
Scope and Data parameters
The OAuth 2.0 Specification indicates that the scope parameter values be 'space delimited', however some of the major implementations do support 'comma delimited' parameters as well. Paga connect also supports comma delimited parameters, however this should only be used if your client implementation does not support space delimited parameters, to ensure future compatibility.

Sending the user to this authorization Uri notify the user of the request by your client to have them provide permission to execute specific operations on their behalf. The client will then be required to authenticate using their Paga credentials in order to provide that permission on such operations. See the images below.

❗️
Paga Connect Scope
The Paga user has to approve ALL Operation and data requests. Ensure to include all the scopes required, Any change in scope will require the Paga user to re-authenticate.

Following the users authorization (or denial), the user will be redirected back to the URI you provided in the redirect_uri parameter in your request.
If the user granted authorization, the request/redirect to the URI will include the following request parameters:

Response Parameter for Authorization Code

Argument Name	Type	Mandatory(M)/Optional(O)	Description
code	String	M	This is the one-time authorization code that you will use to request for an access token (via a separate request)
state	String	M	This is the state provided by your client (if any provided) in your request to the authorization Uri. It is also referred to as the client state.
redirect_uri	String	M	The URI that Paga's OAuth2 server redirect the user-agent after successfully obtaining (or failing to obtain) the access token. From the Sample Authorization response, http://localhost:3000/rent/getMovie? is the redirect_uri.

If the user denied authorization or there was an error during the authorization process, the request/redirect to the URI will include the following request parameters:

Error Response Parameter for Authorization

Argument Name	Type	Mandatory(M)/Optional(O)	Description
authError	String	M	A short description of the error.
error_message	String	M	Human readable text providing additional information to assist the client in understanding the error that occurred

🚧
Authorization Code Validity
The Authorization code is only valid for 60 Seconds after it is issued.

6. Obtaining the Access Token

Following a successful authorization request to your Client with an authentication code, you will need to send a background request to the Paga OAuth 2.0 service to obtain the access token. Note that this is call made in the "background". i.e the user's user-agent (browser) is not directed to this URL as it is critical that the user does not see the parameters/headers included in this request (because they include your client password).

Paga Connect Access Token URI
https://www.mypaga.com/paga-webservices/oauth2/token

For this request, you will need to supply authentication credentials, using the HTTP Basic authentication (HTTP basic authentication requires and encoded HTTP header). The authentication credentials are your client id and client password. Most all web frameworks will provide a mechanism for supplying HTTP basic authentication credentials per the standard HTTP basic authentication header. See the following articles below for more information

HTTP Basic Authentication (Wikipedia)
HTTP Authentication: Basic and Digest Access Authentication (Specification)
Access Token Request Parameters

Argument Name	Type	Mandatory(M)/Optional(O)	Description
grant_type = authorization_code	String	M	This is a pre-determined constant per the specification indicating that you are requesting an access token using an authorization code
redirect_uri	String	M	This the URI for your client that our OAuth2 server should redirect the user-agent after successfully obtaining (or failing to obtain) the access token.
code	String	M	The authorization code returned back to you in the previous authorization step
scope	String	M	This is a space delimited string that allows the the client to specify the scope of access required. This scope is also used by the authorization server to inform the users of what permissions they are providing to the client.
user_data	String	M	This is an optional space delimited string that allows the the client to specify the scope of user data required. This scope is also used by the authorization server to inform the users of what permissions they are providing to the client.

❗️
Consistent Parameters
The redirect_uri, scope and user_data parameters must be identical with those used in the Authorization code request.

👍
REST Client Tip
Firefox RESTClient plugin can be used to test the web service requests for the access token.

If your client authentication credentials (HTTP Basic authentication header) and the authorization code you provide are valid, this will return a response to you with the Access Token in the response back to you per the specification. This access token is now what you will store and associate with the user so that for subsequent requests by this user, you will simply provide the access token and skip these authentication steps. A successful response will have the following:

If the access token request fails or there was an error during the acquisition process, the request/redirect to the URI will include the following request parameters:

Argument Name	Type	Mandatory(M)/Optional(O)	Description
error	String	M	This refers to the error code. A standard set of error code indicating the nature of the error (see the OAuth 2.0 specification for standard error codes)
error_description	String	M	Human readable text providing additional information to assist the client in understanding the error that occurred

REST-Style parameterized URL with all parameters provided.

Argument Name	Access Token Request
URI	https://www.mypaga.com/paga-webservices/oauth2/token?
Headers	Authorization: Basic Auth (client_id(Principal or PublicId) + secret_key(credential)) Accept: application/json OR application/xml
Parameters	grant_type=authorization_code&redirect_uri=http://localhost:8080&code=xxxxx&scope=USER_DEPOSIT_FROM_CARD,MERCHANT_PAYMENT,USER_DETAILS_REQUEST&user_data=FIRST_NAME,LAST_NAME,USERNAME,EMAIL,ACCOUNT_BALANCE
Request Method	POST

Http Headers:
		Authorization:Basic NDIyMDI2M0MtRTIzNC00OURBLThFNjQtRUNENjA4OUFGNEE4OnhUNiVidFpaeFduOWY2ag==
https://www.mypaga.com/paga-webservices/oauth2/token?grant_type=authorization_code&redirect_uri=https://localhost:3000/rent/getMovie/&code=OgI1BQ&scope=USER_DEPOSIT_FROM_CARD+MERCHANT_PAYMENT+USER_DETAILS_REQUEST+PAGA_ACCOUNT_NUBAN+MONEY_TRANSFER_TO_BANK&user_data=FIRST_NAME+LAST_NAME+USERNAME+EMAIL+ACCOUNT_BALANCE

{
  	"access_token":"xxxx-xxxx-xxxx-xxxxxxxxxxx",
    "refresh_token": "xxx-xxxx-xxxxx-xxxxxxx",
    "token_type":"bearer",
    "expires_in":8639999,
    "scope":"MERCHANT_PAYMENT USER_DEPOSIT_FROM_CARD USER_DETAILS_REQUEST USER_REQUEST_TRANSACTION_HISTORY",
    "user_data":"ACCOUNT_BALANCE EMAIL FIRST_NAME LAST_NAME USERNAME"
}

{
    error: 'unauthorized',
    error_description: 'PagaAccount with principal 4220263C-E234-49DA-8E64-ECD6089AF4A8 not found.'
  }

Response Parameter

Argument Name	Type	Mandatory(M)/Optional(O)	Description
access_token	String	M	This is final access token you will use to execute secured operations
token_type = bearer	String	M	This is the type of access token granted as defined by the specification. The token type provided is bearer.
expires_in	String	M	This is the number of seconds until the token expires, from now (the first time you retrieve the token). It refers to the token expiration date.
refresh_token	String	M	This is a token that can be used to re-acquire a new access token after the old one expires.

📘
Access Token
Access Tokens are valid for 100days

7. Refreshing Access Token

Access token can be refreshed before or after it has expired, this allows you to keep your authorization valid and continue to be able to carry transactions on behalf on the user.
To refresh an access token the same endpoint used to obtain an access token is used except that the grant_type value is changed to refresh_token instead. All the parameters as described above should also be used.

Argument Name	Type	Mandatory(M)/Optional(O)	Description
grant_type = refresh_token	String	M	This is a pre-determined constant per the specification indicating that you are requesting a refresh access token using an authorization code
refresh_token	String	M	The refresh_token returned back to you in the previous while generating access token
redirect_uri	String	M	This the URI for your client that our OAuth2 server should redirect the user-agent after successfully obtaining (or failing to obtain) the access token.
scope	String	M	This is a space delimited string that allows the the client to specify the scope of access required. This scope is also used by the authorization server to inform the users of what permissions they are providing to the client.
user_data	String	M	This is an optional space delimited string that allows the the client to specify the scope of user data required. This scope is also used by the authorization server to inform the users of what permissions they are providing to the client.

Argument Name	Sample Refresh Access Token Request
URI	https://www.mypaga.com/paga-webservices/oauth2/token?
Headers	Authorization: Basic Auth (client_id(Principal or PublicId) + secret_key(credential)) Accept: application/json OR application/xml
Parameters	grant_type=refresh_token&redirect_uri=http://localhost:8080&scope=USER_DEPOSIT_FROM_CARD,MERCHANT_PAYMENT,USER_DETAILS_REQUEST&user_data=FIRST_NAME,LAST_NAME,USERNAME,EMAIL,ACCOUNT_BALANCE
Request Method	POST

Http Headers:
		Authorization:Basic NDIyMDI2M0MtRTIzNC00OURBLThFNjQtRUNENjA4OUFGNEE4OnhUNiVidFpaeFduOWY2ag==
https://www.mypaga.com/paga-webservices/oauth2/token?grant_type=refresh_token&refresh_token=43340a44-0602-4e94-a3ba-daf7aadb2e3f&redirect_uri=https://localhost:3000/rent/getMovie/&scope=USER_DEPOSIT_FROM_CARD+MERCHANT_PAYMENT+USER_DETAILS_REQUEST+PAGA_ACCOUNT_NUBAN+MONEY_TRANSFER_TO_BANK&user_data=FIRST_NAME+LAST_NAME+USERNAME+EMAIL+ACCOUNT_BALANCE

{
  	"access_token":"xxxx-xxxx-xxxx-xxxxxxxxxxx",
    "refresh_token": "xxx-xxxx-xxxxx-xxxxxxx",
    "token_type":"bearer",
    "expires_in":8639999,
    "scope":"MERCHANT_PAYMENT USER_DEPOSIT_FROM_CARD USER_DETAILS_REQUEST USER_REQUEST_TRANSACTION_HISTORY",
    "user_data":"ACCOUNT_BALANCE EMAIL FIRST_NAME LAST_NAME USERNAME"
}

{
    error: 'unauthorized',
    error_description: 'PagaAccount with principal 4220263C-E234-49DA-8E64-ECD6089AF4A8 not found.'
  }

📘
Refresh Token Response Parameter
Response Parameter for refresh token is the same format as the access token response parameter. Refer to Access token edpoint for response parameter definition

Getting Started

1. Introduction

🚧
Note

2. Considerations when choosing an implementation

🚧
Note

❗️
Browser Support

3. Paga Connect Basic Flow

4. Paga Authentication Details

5. Obtaining the Authorization Code

📘
Authorization Code Response

📘
Requesting User Details

👍
Scope and Data parameters

❗️
Paga Connect Scope

🚧
Authorization Code Validity

6. Obtaining the Access Token

❗️
Consistent Parameters

👍
REST Client Tip

📘
Access Token

7. Refreshing Access Token

📘
Refresh Token Response Parameter

1. Introduction

🚧Note

2. Considerations when choosing an implementation

🚧Note

❗️Browser Support

3. Paga Connect Basic Flow

4. Paga Authentication Details

5. Obtaining the Authorization Code

📘Authorization Code Response

📘Requesting User Details

👍Scope and Data parameters

❗️Paga Connect Scope

🚧Authorization Code Validity

6. Obtaining the Access Token

❗️Consistent Parameters

👍REST Client Tip

📘Access Token

7. Refreshing Access Token

📘Refresh Token Response Parameter

🚧
Note

🚧
Note

❗️
Browser Support

📘
Authorization Code Response

📘
Requesting User Details

👍
Scope and Data parameters

❗️
Paga Connect Scope

🚧
Authorization Code Validity

❗️
Consistent Parameters

👍
REST Client Tip

📘
Access Token

📘
Refresh Token Response Parameter