Getting Started

Welcome to the Paga Connect Developer Page. You'll find all the information needed to get started integrating with, and using the Paga wallet as your payment platform.

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.

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.

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)

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 Login PagePaga Connect Login Page

Paga Connect Login Page

Paga Connect Access Approval PagePaga Connect Access Approval Page

Paga Connect Access Approval Page

❗️

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

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