Generate connectToken for Payment V2

Overview

Maya's Payment V2 solution requires user authorization and consent before initiating a request. Once the user grants access, Maya issues a token that allows your application to perform secure API calls on their behalf.

Maya implements the OAuth 2.0 Authorization Code Flow, which is designed for web applications requiring user consent.

This flow enables your app to:

• Obtain user authorization, and
• Generate a User Access Token for secure API calls.

What is OAuth 2.0?

OAuth 2.0 (Open Authorization) is an industry-standard framework that enables applications to access user data securely without sharing passwords. Learn more: OAuth 2.0 Documentation

There are several OAuth flows, but Maya uses the Authorization Code Flow Grant for Create Payment V2, which is best for web applications requiring user consent.

What is the Authorization Code Flow Grant?

This flow allows your application to access user data on their behalf. It involves the following high-level steps:

• The application opens a browser page asking the user to log in or approve access.
• The user authorizes or denies the request.
• Upon approval, the user is redirected to your registered redirect URL with an authorization code.
• Your application exchanges the authorization code for a User Access Token.

Authorization Code

• Generated after successful user login and consent.
• Sent to your redirect URL as part of the callback.
• Valid for single use and expires after 300 seconds.

Note: In Maya, the Authorization Code is:

• Valid for 300 seconds (5 minutes).
• Can be used only once.
• Once used or expired, Maya invalidates the code.

Tokens

The authorization code can be exchanged for tokens. These tokens are:

• User Access Token: A short-lived token that allows your application to access user-authorized resources or create a request on their behalf.
• Refresh Token: A temporary token that can be used by your application to request a new User Access Token when the previous token expires.

Tokens Expiry in Maya

Before You Begin

Prerequisites

Ensure the following are ready before integration:

• Completed the onboarding to Maya Connect.
  • Submitted the Redirect URL(s)
  • Nominated key recipient’s email
  • Provided the Public GPG key of your key recipient
• Received the client_id and client_secret
  • These credentials are sent in an encrypted file using your submitted GPG key
• Store Credentials Securely
  • If lost or compromised, request key regeneration from Maya
  • Credentials differ between Sandbox and Production

Your Access to Maya Connect

You will be granted access to Maya Connect, Maya’s OAuth 2.0 service that supports the Authorization Code Flow.

Redirect URL Registration

Maya Connect strictly enforces redirect URL validation for security. Only URLs that have been pre-registered during onboarding are allowed for browser redirection.

Key requirements:

• The redirect URL must use HTTPS.
• The URL must exactly match one of the URLs registered with Maya Connect.
  • Example:
    • Valid: https://example.com/auth
    • Invalid: https://example.com/auth?destination=account

Tip: Avoid using query string parameters in your redirect URLs.
Instead, include only the path component (e.g., /auth) to ensure exact matching.

Multiple Redirect URLs

You may register multiple redirect URLs during onboarding. This is recommended if your application operates across different environments or subdomains, such as:

• https://staging.example.com/auth
• https://app.example.com/auth
• https://partner.example.com/auth

Each registered URL must still follow the same HTTPS and exact-match rules.

Integration Steps

Step 1: Get the Authorization Code

1.1 Redirect User to Maya Connect

Send the user to the Maya Connect Authorization URL to log in and authorize access:

GET https://connect-sb-issuing.paymaya.com/authorize?
    response_type=code&
    client_id={yourClientId}&
    redirect_uri={https://yourApp/callback}&
    prompt=login&
    user_id={+63userMobileNumber}&
    state={yourState}

Request Parameters:

1.2 Parse and Get the Authorization Code

Once the user authorizes, Maya redirects to your redirect URL with parameters:

https://yourApp/callback?code={authorizationCode}&state={yourState}&userId=%2B{63maskedUserMobileNumber}&profileId={profileId}

Response Parameters

User Authorization code is valid for a single use and lasts for 300 seconds. After being used or once the time expires, Maya will invalidate the code, making it unusable for any subsequent processes.

Step 2: Exchange the Authorization Code for Tokens

2.1 Prepare Basic Authentication Header

Use Basic Authentication with your client_id and client_secret encoded in Base64.

Basic Authentication in Maya Connect API

1. Format the credentials. Use the client_id as the username, then put a colon (':') after it. Then, put the client_secret as the password (after the colon).
2. Convert to Base64. The next step is to encode the formatted string from Step 1 using Base64. You can use an online Base64 encoder or do it in code (e.g., in Python: base64.b64encode(credentials.encode()).decode()).
3. Add the Authorization header. In your Maya Connect API request, include an Authorization header. The value should be "Basic " followed by the Base64-encoded string from Step 2.

Sample Code:

import base64
client_id = "your_client_id"
client_secret = "your_client_secret"
credentials = f"{client_id}:{client_secret}"
encoded = base64.b64encode(credentials.encode()).decode()
headers = {"Authorization": f"Basic {encoded}"}

const username = "client_id";
const password = "client_secret";
const credentials = `${username}:${password}`;
const encodedCredentials = btoa(credentials);
console.log("Basic " + encodedCredentials);

2.2 Request Access Tokens

Send a POST request to Create Access Token API to exchange your code for tokens

For every successful call, the API returns fresh tokens – the User Access Token (access_token) and the Refresh Token (refresh_token). At the same time, Maya Connect will invalidate the previous ones.

Step 3: Refreshing an Expired User Access Token (when needed)

When the User Access Token (access_token) expires, your application should be able to obtain a new User Access Token using the Refresh Token Grant of OAuth 2.0.

The Refresh Token Grant is a process in OAuth 2.0 that allows an application to obtain a new access token without requiring the user to log in again. It is used when an access token expires but the user still needs continued access.

3.1 Prepare Basic Authentication Header

Use Basic Authentication with your client_id and client_secret encoded in Base64.

Basic Authentication in Maya Connect API

1. Format the credentials. Use the client_id as the username, then put a colon (':') after it. Then, put the client_secret as the password (after the colon).
2. Convert to Base64. The next step is to encode the formatted string from Step 1 using Base64. You can use an online Base64 encoder or do it in code (e.g., in Python: base64.b64encode(credentials.encode()).decode()).
3. Add the Authorization header. In your Maya Connect API request, include an Authorization header. The value should be "Basic " followed by the Base64-encoded string from Step 2.

Sample Code:

import base64
client_id = "your_client_id"
client_secret = "your_client_secret"
credentials = f"{client_id}:{client_secret}"
encoded = base64.b64encode(credentials.encode()).decode()
headers = {"Authorization": f"Basic {encoded}"}

const username = "client_id";
const password = "client_secret";
const credentials = `${username}:${password}`;
const encodedCredentials = btoa(credentials);
console.log("Basic " + encodedCredentials);

3.2 Request to Refresh User Access Token

Send the valid Refresh Token to the Create Access Token API endpoint. (Refer to REFRESHTOKENREQUEST)

For every successful call, the API returns a fresh User Access Token (access_token) and invalidates the previous User Access Token.

Refer to the Code Recipe below to guide you in building the request:

Business Rules to Code

Login Scenarios

Maya has a variety of login scenarios depending on the user_id value.

Handling of Expired Tokens

Your application should monitor and trigger a refresh for expiring tokens. expires_in in the API response provides the expiry of the access_token.

Handling of OAuth 2.0 Errors

For the list of errors and how they can be handled, please refer to the OAuth 2.0 Authentication Errors.

Endpoints

FAQs

Q: What happens when my access token expires?

A: If refresh_token is still valid, your platform may use it to request to generate a new User Access Token (access_token) from the Maya Connect endpoint. Otherwise, you may need to get a new authorization from the user. Refer to Handling Expired Tokens.

Next Steps

• Use the access_token as connectToken when initiating a payment using Create Payment V2 API. Refer to Create Payment V2 using connectToken