Note the following when generating or requesting your API Keys or Credentials:

Maya has two (2) environments, Sandbox and Production, each with distinct keys or credentials. Refer here for more details
API credentials are specific to the Maya solution you will be using

Acquiring your API Credentials for Maya Connect

During onboarding, your Maya Relationship Manager will ask you to nominate a key recipient and provide their public GPG key and email address. Your Maya Relationship Manager will assist you with the onboarding.

Once onboarded, the API keys or credentials will be sent to your nominated key recipient. These credentials will be stored in an encrypted file using the submitted public GPG key. Refer to the GPG guide for instructions on decrypting the file.

Grant Types

The OAuth framework specifies several grant types for different use cases. The grant type refers to the way an application gets an access token.

Client Authentication

`client_credentials`

Use the Bearer Authentication (also called Token Authentication) to verify your identity as an authorized entity accessing Maya's endpoints.

This method uses the grant type client_credentials. When referring to the API reference, make sure you are reviewing the CLIENT_CREDENTIALS specifications.

The API Consumer checks if a valid access_token exists.
If the existing access_token has expired or no valid access_token exists, the API Consumer requests a new one from Maya Connect via Create Access Token Endpoint .
Maya Connect responds with the access_token to the API Consumer.
The API Consumer saves the access_token.
The API Consumer uses the new access_token to invoke Maya's API.

User Authorization

`authorization_code`

Exchange one-time authorization code for tokens.

This method uses the grant type authorization_code. When referring to the API reference, make sure you are reviewing the AUTHORIZATION_CODE specifications.

The customer initiates the request to the API Consumer.
The API Consumer redirects the customer to the GET /authorize for authorization.
The customer logs in to their Maya account and completes the One-time PIN challenge on the Maya-hosted page.
Maya Connect generates the authorization code.
Maya Connect redirects the customer back to the API Consumer providing the authorization code.
The API Consumer gets the authorization code from the response of Maya.
The API Consumer calls the Create Access Token endpoint of Maya providing the authorization code to generate tokens.
Maya Connect generates the access_token and refresh_token in Maya.
Maya Connect returns the access_token and refresh_token of the customer to the API Consumer.
The API Consumer saves the access_token and refresh_token of the customer.

Getting the authorization code

Step 1: Redirect to Maya Connect’s /authorize URI

To obtain authorization from the user, redirect them to Maya Connect's URI. At this stage, the user will be presented with the Maya login screen, where the user will need to enter their Maya Credentials and One-Time PIN (OTP).

Sample Request:

GET https://connect-sb-issuing.paymaya.com/authorize?
    response_type=code&
    client_id=myapp&
    redirect_uri=https://myapp.com/callback&
    prompt=login&
    user_id=+639412345678&
    state=sf9xm&

Request Parameters:

Parameter	Required?	Type	Description
`response_type`	Required	String	Indicates the authorization processing flow to be used; value is `code` when using the Authorization Code Flow
`client_id`	Required	String	The Client ID
`redirect_uri`	Required	String	Where the response will be sent; Must exactly match one of the Redirection URI values registered for the Client ID
`prompt`	Required	String	Expected value for Cash-in via web Login integration: `login` Any user session will be destroyed and the user will be asked to re-authenticate
`user_id`	Required	String	Expected value for Cash-in via web Login integration: *{mobile number}* If a user exists with that identifier, it will redirect to the login screen Else, it will redirect to the registration screen It will be pre-filled in the login or registration form and will not be editable
`state`	Optional	String	Recommended; Used to maintain state between the request and the callback; This can be used to mitigate Cross-Site Request Forgery (CSRF) attacks.

Step 2: Get the authorization `code`

Once the user grants authorization, they will be redirected back to the specified redirect URI, accompanied by the following information:

Redirect URI Parameters

Parameter	Description
`code`	The generated authorization `code`
`state`	The same state value as supplied in the authorization request
`error`	Added if there is any error. e.g. `login_required`
`userId`	Masked user ID
`profileId`	A unique numeric system identifier for the User

Sample

https://myapp.com/callback?code=X2wy4L&state=sf9xm&userId=%2B639*****5678&profileId=772988142429

Parse the URI and get the code to proceed with the next step.

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.

`refresh_token`

Use the refresh_token from the authorization_code grant to generate new user access_token.

This method uses the grant type refresh_token. When referring to the API reference, make sure you are reviewing the REFRESH_TOKEN specifications.

The API Consumer calls the Create Access Token endpoint providing a valid refresh_token of the customer.
Maya Connect generates new access_token of the customer in Maya.
Maya Connect returns the new access_token of the customer to the API Consumer.
The API Consumer saves the new access_token of the customer.

When user's access_token expires, your system or platform is expected to call the Create Access Token endpoint of Maya providing a valid refresh_token to request a new access_token of the customer. This endpoint will be enabled depending on your use case and user journey. For more information, contact your Maya Relationship Manager.

Each successful token refresh generates a new access_token, and invalidates the previous access_token, while the refresh_token remains valid until it expires.

Generating the `access_token` via Maya Connect

At this point, you should have the following credentials:

Valid Client ID
Valid Client Secret

These credentials are provided once onboarded. Different credentials will be provided for each environment (e.g. sandbox, production).

Reach out to your Maya Relationship Manager for the onboarding requirements and process.

Providing the correct credentials and following the specifications, send the request to the Create Access Token endpoint of Maya to generate the access_token.

Every successful call to this endpoint would generate a time-limited access_token.

Token Expiry

Token	Lifetime
`access_token`	`3600` seconds
`refresh_token`	`604800` seconds

For authorization_code grant only:

When your access_token expires, send a new request using the refresh_token grant to generate a new token.

📖

Create Access Token

Open Recipe

Endpoints

Name	HTTP Method	Key Type	Endpoints	Description
Create Access Token	POST	SECRET	/token	Generate an `access_token` for different flows
Authorize	GET	Note: This is a web endpoint and not an API endpoint.	/authorize	This endpoint is used to interact with the resource owner and obtain an authorization grant by redirecting the user's browser Note: This is a web endpoint and not an API endpoint

Business Rules to Code

Login Scenarios for `authorization_code` grant

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

Scenario	Result
If `user_id` was not initially provided in the browser request	Redirects to Maya log-in page
If `user_id` was initially provided in the browser request AND `user_id` is a valid Maya Account	Redirects to Maya login page with prefilled mobile number If the `user_id` was pre-defined, the prefilled mobile number cannot be edited/modified
If `user_id` was initially provided in the browser request AND `user_id` is NOT a valid Maya Account	Redirects to Maya registration form with the prefilled username

Handling Expired Token for `authorization_code` grant

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

Token	Lifetime
`access_token`	`3600` seconds
`refresh_token`	`604800` seconds

Scenario	Result
If `access_token` expires AND `refresh_token` is still valid	Use the refresh_token and call the Create Access Token endpoint of Maya See refresh_token
If `access_token` expires AND `refresh_token` is also expired	Redirect user to the Maya Connect for re-authorization and call Create Access Token of Maya to generate a new `access_token`: See authorization_code

Handling of errors

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

OAuth 2.0 Authentication

Acquiring your API Credentials for Maya Connect

Grant Types

Client Authentication

`client_credentials`

User Authorization

`authorization_code`

Getting the authorization code

Step 1: Redirect to Maya Connect’s /authorize URI

Sample Request:

Request Parameters:

Step 2: Get the authorization `code`

Redirect URI Parameters

Sample

`refresh_token`

Generating the `access_token` via Maya Connect

Token Expiry

Endpoints

Business Rules to Code

Login Scenarios for `authorization_code` grant

Handling Expired Token for `authorization_code` grant

Handling of errors

Payment APIs

Developer resources

More

Acquiring your API Credentials for Maya Connect

Grant Types

Client Authentication

client_credentials

User Authorization

authorization_code

Getting the authorization code

Step 1: Redirect to Maya Connect’s /authorize URI

Sample Request:

Request Parameters:

Step 2: Get the authorization code

Redirect URI Parameters

Sample

refresh_token

Generating the access_token via Maya Connect

Token Expiry

Endpoints

Business Rules to Code

Login Scenarios for authorization_code grant

Handling Expired Token for authorization_code grant

Handling of errors

Payment APIs

Developer resources

More

`client_credentials`

`authorization_code`

Step 2: Get the authorization `code`

`refresh_token`

Generating the `access_token` via Maya Connect

Login Scenarios for `authorization_code` grant

Handling Expired Token for `authorization_code` grant