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.

• OAuth 2.0
• Aaron Parecki - OAuth2 Simplified
• Wikipedia OAuth

🚧

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.

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

Authorization Code scope

Table 1.0 Authorization Code Scope parameters

Authorization Code user_data parameter

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

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

🚧

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

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

❗️

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:

REST-Style parameterized URL with all parameters provided.

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

📘

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.

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