Overview

For Cash-in via Maya Login, a token is required to initiate a cash-in request and identify the Maya wallet where the funds will be credited. This token can only be obtained from Maya when the user authorizes it.

Maya uses the Authorization Code Flow Grant of OAuth 2.0 to get the user authorization and generate the user access token.

What is OAuth 2.0?

OAuth 2.0 (Open Authorization) is an industry-standard framework for securing access to APIs and user data. If you are new to OAuth 2.0, check the OAuth documentation for more details.

There are multiple authorization flows in OAuth 2.0, but certain Maya Solutions use the Authorization Code Flow Grant to generate the User Access Token.

What is the Authorization Code Flow Grant?

The Authorization Code Flow Grant is used when an application needs to access a user’s data on their behalf. This grant type will first require your application to launch a browser to begin the flow. At a high level, the flow has the following steps:

1. The application opens a browser page asking the user for login or approval
2. The user authorizes or approves the request
3. The user is redirected to the registered redirect URLs of the application with an authorization code in the query string
4. The application exchanges the authorization code for a User Access Token.

Redirect URLs

The URL to which the OAuth service will redirect the browser after the user grants the authorization.

The OAuth Service will only allow redirection of users to the URLs that were previously registered with the service to prevent redirection attacks where an authorization code or user access token can be intercepted by an attacker.

Authorization Code

Authorization Code Grant generates an authorization code, a temporary code generated after successful user authorization. This code will be sent to your application via your redirect URL.

Authorization Code Expiry in Maya

In Maya, the 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.

Tokens

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

1. User Access Token: A short-lived token that allows your application to access user-authorized resources or create a request on their behalf.
2. 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

Your Access to the Maya Connect

In Maya, you will be granted access to Maya Connect, the OAuth service in Maya, for the OAuth 2.0 Authorization Code Flow Grant and Refresh Token grant for the Cash-in to Maya Wallet implementation.

Maya Connect will only allow redirection of the browser to the URLs that were registered with the service. Redirect URL must be an https endpoint.

Maya Connect will be looking for an exact match of the redirect URL. This means a redirect URL of https://example.com/auth would not match https://example.com/auth?destination=account. It is best practice to avoid using query string parameters in your redirect URL and have it include just a path.

You are allowed to register multiple redirect URLs during onboarding, which can help when your web application is running on several different subdomains.

Acquiring Your API Credentials for Authorization Code Flow Grant

Maya Connect will require that you go through onboarding first. During onboarding, your Maya Relationship Manager will ask you to submit the following:

1. The redirect URL/s your application will use. The redirect URLs are where Maya Connect will return the user after they have authorized the application.
2. The email address of your nominated key recipient
3. The public GPG key of your nominated key recipient. If you are unfamiliar with GPG, see the GNUPG document and start importing a public GPG key.

After successful onboarding, Maya will give you a client_id and a client_secret specific for your Authorization Code Flow Grant in the Maya Connect. These credentials will be stored in an encrypted file using the public GPG you submitted during onboarding. The encrypted file will be sent to your nominated key recipient via email. Refer to the GNUPG document to start decrypting your file.

Keep in Mind

• Maya has two (2) environments, Sandbox and Production, each with distinct keys or credentials. See the API Environment to familiarize the API environments of Maya.
• API credentials are specific to the Maya solution you will be using

Storing Your API Credentials

API Credentials will be used to authenticate your application, so save them in a secure location. Misuse or mishandling of tokens or keys within the jurisdiction of the Partner could entail risks and vulnerability of transactions.

If your API keys are lost or breached, delete the old API keys and request to your Maya Relationship Manager to generate new ones in the same environment.

Build Your Integration

1. Getting the Authorization Code

1.1. Redirect User to the Maya Connect URI

To get authorization from the user, your application must send the user to the Maya Connect URI, the authorization URL of Maya. At this stage, Maya requires the user to enter their Maya Account Credentials and OTP (One-Time Password).

Sample Maya Connect URI:

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}

Here’s the Request Parameter explained:

1.2. Parse and Get the Authorization code

Once the user grants authorization, they will be redirected back to the specified redirect URI, accompanied by an authorization code and other details from Maya. Parse the URL and get the code.

Sample Response:

{https://yourApp/callback}?code=X2wy4L&state={authorizationCode}&userId=%2B639*****5678&profileId=772988142429

Here’s the Response Parameter explained:

Authorization Code Expiry

In Maya, the 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.

2. Exchanging the Authorization code for Tokens

Now that you have an Authorization Code (code), you must exchange it for tokens. Using the extracted code from the previous step, you will need to send a POST to the Create Access Token endpoint.

2.1. Prepare Your API Credentials

After successful onboarding, you should have acquired your API credentials for Maya Connect API.

Maya Connect API uses Basic Authentication for token requests. This means you send your client_id and client_secret encoded in Base64 with each request.

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
username = "client_id"
password = "client_secret"
credentials = f"{username}:{password}"
encoded_credentials = base64.b64encode(credentials.encode()).decode()
print("Basic " + encoded_credentials)

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

2.2. Request for User Access Tokens

After preparing the Authorization header, build the request by following the correct API specification, then send the valid Authorization Code request to the Create Access Token endpoint.

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.

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

User Tokens Expiry

3. Refreshing an Expired User Access Token

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 Your API Credentials

You should be using the same API Credentials provided to you for the Authorization Code Grant.

Using Basic Authentication, you send the same client_id and client_secret encoded in Base64 with each request.

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
username = "client_id"
password = "client_secret"
credentials = f"{username}:{password}"
encoded_credentials = base64.b64encode(credentials.encode()).decode()
print("Basic " + encoded_credentials)

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

After preparing the Authorization header, build the request by following the correct API specification, then send the valid Refresh Token request to the Create Access Token endpoint.

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.

Frequently Asked

1. What to do when the User Access Token (access_token) expires?
   • Answer: Your platform must request to generate a new User Access Token (access_token) from the Maya Connect endpoint. Refer to the Refreshing an Expired User Access Token section on this same page.
2. My transaction in Sandbox keeps failing. How can I fix this?
   • First, ensure your code is implemented correctly by reviewing the required steps. If your setup is correct but errors persist, check the Sandbox Health Page to verify if the service is operational. If the service is up, retrieve the error code and use the search box in the Maya Developer Hub to find relevant guides on resolving it.
3. Getting timeouts when connecting to the Sandbox of Maya. How can we resolve this?
   • If you're encountering timeouts in the Sandbox, first check the Sandbox Health Page to see if the service is operational. If the service is up but the issue persists, visit our Support Page for the appropriate channel to escalate your concern.

Next Steps

Store your tokens securely for use in API requests. If your token is breached, request a new token to invalidate the old one.

Use the User Access Token to Create Cash-in of the Cash-in via Maya Login solution.

Aside from the User Access Token, there are required fields that have static values and you must include in the API request. Be sure to review the API documentation of the Cash-in to Maya Wallet for the correct specifications.