⚠️ The focus of this guide will be solely on sandbox endpoints and tokens. After successfully completing coordinated testing with Maya, you will be provided with production endpoints and access tokens. For the complete production go-live process, please coordinate with your Maya Relationship Manager.

How Maya Mini App works

With Maya Mini App, you are given the opportunity to establish your presence within the Maya App. This solution incorporates Maya's session technology and profile sharing functionalities to ensure seamless experience for your users. It also empowers your user to effortlessly perform financial transactions using their Maya wallet.

⚠️ Complete Partner Onboarding

In order to enable your presence in the Maya App and be able to execute the API endpoints mentioned in the succeeding section, you will need to complete the partner onboarding process.

The basic flow for Maya Mini App looks like this:

When user goes to their Maya App and clicks your tile, Maya will initiate session to your system.
Once session has been established, Maya will redirect user to your landing page via webview.
Comply with Maya’s authentication and acquire access.
With access token (user access token and client token), your system calls Maya's available API’s to perform transactions based on your use cases:
- Obtaining user’s profile for pre-filled forms
- Maintain and keep user session while user continue to browse your webview
- Accept payments using user’s Maya Wallet as fund source
- Transfer funds to user’s Maya Wallet

Access Tokens

One of the important aspects you need to understand in Maya Mini Apps' is the access tokens. Access tokens comply with the industry standard method for representing permissions securely between two parties. When someone accesses your application via the Maya Mobile App, your system obtains an access token that provides temporary, secure access to user’s data and their Maya account.

For privacy checks, some of the components of Maya Mini App requires access tokens. Maya Mini Apps have two (2) types of access tokens.

⚠️ In compliance to privacy and security regulations of Maya, each token is configured with their own lifetime.

Token Type	Lifetime	Description
User Access Token	`600 seconds`	A token that is required by majority of the Maya Mini App's APIs to identify the user. User access token are generally obtained during session initiation together with its refresh token, with the user’s consent.
Client Token	`3600 seconds`	The client token is an identifier that your system is permitted to call Maya’s API. Your scope or access grants are bound to this token. You can get your client token via Connect endpoints.

Data Access

Maya Mini App asks permission from the Maya App users. These permissions, if granted by the user, give you access to user’s data. For example, your app can access user's name and address as registered in Maya.

Access to user data will be determined in your scope during onboarding and will be bound to your credentials.

In addition, data access expiration is bound to the user access token and your client token.

⚠️ Without user's consent, Maya will not share any of the user's information to your application.

Maya App’s In-app Web view Limitations

Maya Mini App currently does not support the following:

Redirecting users to external browser
Opening new tab
Media picker
Opening camera for photo and video
Landscape orientation

1 Before you integrate

Before your application can be available within the Maya app, you will need to prepare for the pre-requisites: the session URL and the landing page URL of your web application. These are part of the onboarding requirements to be provided to Maya. See Quick Start Guide for more details.

Step 1: Prepare for Session Initiation

From the Maya app, the user will be navigating to your application. In this instance, Maya will be sharing details of the initiated session. The Maya's session technology provides a secure and efficient method to share user’s session, with their consent, to your system.

During initiation, Maya will send you the user access token (accessToken) which you can use later to perform actions on-behalf of the user.

1a. Create your application’s session URL

You will need to implement a dedicated endpoint where Maya can send the accessToken which we can call as the session URL.

For privacy and security, session URL must be accessible by Maya only. One way to do this is by applying whitelisting mechanism, and then whitelist the following Maya IPs:

Environment	IP Address
Sandbox	`52.76.175.228` `13.251.40.239` `13.251.3.237` `18.138.3.140`

Every time users accesses your application, Maya will send an API request to the specified session URL. The session URL needs to be capable of receiving and processing the API contract provided below, and it should respond by sending a sessionId back to Maya.

ℹ️ Manage your User’s Session

Your application should be able to identify the user via the sessionId. One way to do this is to have a mapping of accessToken and sessionId.

Every sessionId your system responds back to Maya must be unique and can only be used once. Maya recommends invalidating the session ID once it has been utilized and ensure that it will not be reused in the future. In case of subsequent attempts, where the landing page employs the same sessionId, your system should decline or reject the access.

API Contract

Method: POST

Request Payload you will receive

Click to see full API specifications

Request Header

Attribute	Type	Format	Description
`Content-Type` REQUIRED	string	`application/json`	Specifies the media type of the request
`Request-Reference-No` REQUIRED	string	UUIDv4	Unique reference identifier for tracking the request

Request Body

Attribute	Type	Format	Description
`accessToken` REQUIRED	string	JWE	The user access token. Your application should store this securely while also consider the expiration
`refreshToken` REQUIRED	string	JWT	Token for getting a new access token. Your application should store this securely while also consider the expiration
`expiresAt` REQUIRED	integrer	N	Timestamp of the session expiration, in seconds since the epoch (UNIX timestamp)

Response Payload you should return

Click to see full API specifications

Request Body

Attribute Type Format Description

Attribute	Type	Format	Description
`sessionId` REQUIRED	string	AN(255)	Must be URL-safe and must be valid for one-time use only. Recommended: `UUIDv4` format.

sessionId REQUIRED

string

AN(255)

Must be URL-safe and must be valid for one-time use only.

Recommended: UUIDv4 format.

✅ Once session URL is created, submit the URL to Maya for enrollment / onboarding.

1b. Create your HTML 5 Mobile Web Application Landing Page

Create a web application a user can access within the Maya app, thus it should have mobile-responsive design.

Maya will redirect the user to the your landing page, with the sessionId your session URL endpoint returned during session initiation. Make sure that your landing page is able to handle this.

<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <p>Welcome to My App</p>
  </body>
</html>

API Contract

Method: GET

Request Payload you will receive

Click to see full API Specifications

Request Query

Attribute Type Format Description

Attribute	Type	Format	Description
`sessionId` REQUIRED	string	AN(255)	The session ID returned by your session URL. Must be URL-safe. Recommended: `UUIDv4` format.

sessionId REQUIRED

string

AN(255)

The session ID returned by your session URL. Must be URL-safe.

Recommended: UUIDv4 format.

🧠 Keep in mind

Maya will redirect the user to your landing page together with the sessionId. URL would look like this: https://your-landing-page-url.com?sessionId={sessionId-value}

Your system should be a GET endpoint and should receive a query parameter name sessionId.

Maya recommends invalidating the session ID once it has been utilized and ensure that it will not be reused in the future. In case of subsequent attempts, where the landing page employs the same sessionId, your system should decline or reject the access.

In addition, landing page URL should be SSL-secured (https) and publicly accessible.

It is recommended that you configure SSL on standard port 443, otherwise your application may experience network issues when integrating with Maya.

✅ Once Landing page is created, take note and submit the base URL to Maya for enrollment / onboarding.

Step 2: Submit URLs and other onboarding requirements

In order to execute the API endpoints mentioned in the succeeding sections, you will need to complete the partner onboarding process. Provide the session URL and landing page to Maya, and see Quick Start Guide for the other items required for onboarding.

Upon completion of partner onboarding you will be provided with the following tokens or keys.

Maya Connect client ID
Maya Connect client secret
JWE and JWK keys to be used to decrypt profile data
p2mid, if you have payments use case
Fund Maya Wallet API Key, for withdrawal use case.

⚠️ As part of security measures, sharing of keys between Maya and the Partner shall follow secure key protocols, such as GPG encryption. Misuse or mishandling of tokens or keys within the jurisdiction of the Partner, could entail risk and vulnerability of transactions.

2 Initiate and Manage Sessions

As discussed in the access token section, Maya Mini Apps would require two tokens representing the permissions, your session and the session of your users.

2a. Obtaining your Client Token

For security, Maya requires authentication of your application prior to giving access or permissions to Maya’s services. Once authentication is done, Maya will issue a time-limited client token.

As long as client token is valid, you can use it to any of the following APIs:

Refresh User Access Token
Get Profile
Create and Execute Payments

Client Token Expiry

You may call this endpoint and acquire your client token anytime, however, please note that in compliance to privacy and security regulations of Maya, client token has its default lifetime.

Token	Lifetime
Client Token (`access_token`)	3600 seconds

Step 1: Generate your Client Token via Maya Connect Token API

POST https://connect-sb-issuing.paymaya.com/token

Every successful call to the Maya Connect Token API would generate a time-limited client token (access_token). This API would need your credentials to process the request.

✅ At this point, you should have the following credentials:

Valid Client ID

Valid Client Secret

These credentials will be provided once onboarded. See Quick Start Guide for the onboarding requirements and process. Note also that different credentials will be provided for each environment (e.g. sandbox, production).

What happens during the Client Token generation:

Following the API specifications, send your API request to POST https://connect-sb-issuing.paymaya.com/token
Upon successful call to this endpoint, Maya will respond to you with a client token (access_token).

API Contract

Request Parameters

Request Header

Attribute Type Format Description

Content-Type REQUIRED string application/x-www-form-urlencoded Specifies the media type of the request

Attribute	Type	Format	Description
`Content-Type` REQUIRED	string	`application/x-www-form-urlencoded`	Specifies the media type of the request
`Authorization` REQUIRED	string	Base64 encoded	Base64 encoded string of the provided Connect credentials: `clientID:clientSecret` Example: `Basic base64encodedClientIDSecret=`

Authorization REQUIRED

string

Base64 encoded

Base64 encoded string of the provided Connect credentials: clientID:clientSecret

Example: Basic base64encodedClientIDSecret=

Request Body

Attribute	Type	Format	Description
`granType` REQUIRED	string		`client_credentials`

Successful Response

Response Body

Attribute Type Format Description

Attribute	Type	Format	Description
`access_token` REQUIRED	string	JWT	The client token to be used in the Authorization header of Maya specific endpoints. (i.e. GET `/profile`, POST `/payments`)

access_token REQUIRED

string

JWT

The client token to be used in the Authorization header of Maya specific endpoints.

(i.e. GET /profile, POST /payments)

ℹ️ When your client token expires, send a new request to Maya Connect Token API to generate new client token.

2b. Complete Session Initiation

In the previous section 1 Before you integrate, you were able to create and submit the following to Maya: session URL and landing page. Once Maya is done onboarding you in the sandbox environment, be ready to initiate Maya’s session technology.

Summarizing the pre-req steps, it is expected that your mini application will be able to successfully receive and process the following data:

Your URL/Endpoints	Data you'll Receive	Data to Return
Session URL	`accessToken` `refreshToken` `expiresAt`	`sessionId`
Landing Page	`sessionId`

🧩 Before executing any complex logic that may cause timeout, your session URL should promptly respond with sessionId in a successful status code (2xx).

Implementing this approach would benefit the rendering duration and redirection speed of your user to your landing page.

What happens during the session initiation:

Once user clicks your icon/tile in the Maya App, Maya will start initiating session.
During session initiation, Maya will ask user for their consent and notify user the data that will be shared to you.
When user provides their consent, Maya will send the user access token to your session URL.
Your session URL should acknowledge the API request and return a sessionId to Maya.
Maya to redirect the user to the your landing page, with the sessionId value acquired from your session URL.

User Access Token Expiry

In compliance to privacy and security regulations of Maya, user access tokens have its default lifetime. Once the user access token expires, the user will lose access to your application.

Token	Lifetime
`accessToken`	600 seconds
`refreshToken`	1200 seconds

ℹ️ When user access token expires, you can request for a new set of user access tokens by using its refreshToken through POST https://op-sandbox.paymaya.com/tokens

See the next section for Refreshing user access tokens.

Conditional: Refreshing User Access Token

Some use cases would require longer sessions which sometimes exceeds the lifetime of the user access token. One way to maintain and extend the session of the user is by utilizing this endpoint.

✅ At this point, you should have the following tokens:

refreshToken A valid refresh token, either received in your session URL or acquired during refreshing tokens, whichever is the latest/valid value.

access_token A valid client token. See how to Obtain your Client Token .

Step 1: Trigger Refresh by providing refreshToken

POST https://op-sandbox.paymaya.com/tokens

What happens during Refresh:

Following the API specifications, send your API request to POST https://op-sandbox.paymaya.com/tokens
Upon successful call to this endpoint, Maya will respond to you with new set of tokens – new accessToken and new refreshToken values.

API Contract

Request Parameter

Request Header

Attribute	Type	Format	Description
`Accept` REQUIRED	string	`application/json`
`Content-Type` REQUIRED	string	`application/json`	Specifies the media type of the request
`Request-Reference-Number` REQUIRED	string	UUIDv4	Unique reference identifier for tracking the request
`Authorization` REQUIRED	string	JWS	Client token generated by Maya Connect. See how to Obtain your Client Token . Example: `Bearer clientToken-Value`

Request Body

Attribute	Type	Format	Description
`refreshToken` REQUIRED	string		`User refresh token` either received in your session URL or acquired during refreshing tokens , whichever is the latest/valid value.

Successful Response

Response Body

Attribute	Type	Format	Description
`accessToken` REQUIRED	string	JWE	The user access token. Your application should store this securely while also consider the expiration
`refreshToken` REQUIRED	string	JWT	Token for getting a new access token. Your application should store this securely while also consider the expiration
`expiresAt` REQUIRED	integer	N	Timestamp of the session expiration, in seconds since the epoch (UNIX timestamp)

Step 2: Save new user tokens

Successful call to this endpoint will generate new accessToken and refreshToken values.

🧠 Keep in mind

Maya will invalidate the old ones, thus, you must update your records and save the new set of user tokens.

3 Set up the users of your application

One of the Maya Mini App’s feature is seamless profile sharing. Maya Mini App provides you secure access to user profile which you can use to authenticate an existing user with a Maya account or for account registration on your application.

Access to user profile is bound to your scope. Listed below are the supported scopes in Maya Mini Apps:

Available Scopes

openid scope DEFAULT

This includes the unique customer ID of the user and their KYC status.

Attribute	Type	Description
`id`	string	This ID is unique to the user.
`profileId`	string	An additional identifier of a user.
`kycStatus`	string	KYC status of the customer. KYC0 (unverified account) or KYC1 (verified account)

profile scope BY REQUEST

The user’s personal information, such as their name and birth details.

Attribute	Type	Description
`name`	object	An object containing the user's registered name.
`name.firstName`	string	User's registered first name.
`name.middleName` NULLABLE	string	User's registered middle name.
`name.lastName`	string	User's registered last name.
`name.verificationStatus` NULLABLE	string	Reflects the verification status of the name registered. Expected values: `PASS`, `FAILED`, null
`birthDetails`	object	An object containing the user's registered birth details.
`birthDetails.birthDate`	string	`MM-dd-YYYY`
`birthDetails.city`	string	City of birth
`birthDetails.nationality`	string	User's nationality
`birthDetails.country`	string	Country of birth
`birthDetails.verificationStatus` NULLABLE	string	Reflects the verification status of the provided birth details. Expected values: `PASS`, `FAILED`, null

contact scope BY REQUEST

The user’s contact information, which can be either an email address or mobile number.

Attribute	Type	Description
`contact`	array	An array containing the user's contact details.
`contact[].type`	string	User's type of contact. Expected values: `EMAIL` or `MSISD`
`contact[].subType`	string	Subtype of user's contact. Expected values: `PRIMARY` or `RECOVERY`
`contact[].value`	string	If type is `EMAIL`, then value is email address If type is `MSISDN`, then value is mobile number
`contact[].verificationStatus` NULLABLE	string	Reflects the verification status of the name registered. Expected values: `PASS`, `FAILED`, null

address scope BY REQUEST

This includes all the address information of the user.

Attribute	Type	Description
`address`	array	An array containing the user's address details.
`address[].type`	string	Type of address. Expected values: `PRESENT` or `PERMANENT`
`address[].line1`	string	Address Line 1
`address[].line2`	string	Address Line 2
`address[].locality`	string
`address[].city`	string	City
`address[].province`	string	Province
`address[].region`	string	Region
`address[].country`	enum	Valid country code
`address[].zipCode`	string	ZIP Code
`address[].verificationStatus` NULLABLE	string	Reflects the verification status of the user's address details. Expected values: `PASS`, `FAILED`, null

workDetails scope BY REQUEST

The source of income and nature of work are provided.

Attribute	Type	Description
`workDetails`	object	An object containing the user's work details.
`workDetails.natureOfWork`	string	See list of possible values
`workDetails.natureOfWorkDetails` NULLABLE	string	Additional details on the user's nature of work
`workDetails.sourceOfIncome`	string	See list of possible values
`workDetails.sourceOfIncomeDetails` NULLABLE	string	Additional details on the user's nature of work
`workDetails.verificationStatus` NULLABLE	string	Reflects the verification status of the user's work details. Expected values: `PASS`, `FAILED`, null

identity_document scope BY REQUEST

Have access to image and liveness video of the user.

Attribute	Type	Description
`identityDocument`	array	An array containing the user's identity documents.
`identityDocument[].type`	enum	Type of identity document. See list of possible values
`identityDocument[].value` NULLABLE	string	Nullable when: `frontUrl` is present `frontUrl` is not available due to unsupported format
`identityDocument[].frontUrl` NULLABLE	string	Nullable when: `value` is present `frontUrl` is not available due to unsupported format `frontUrl` is a S3 presigned URL with expiry of `15 minutes` ℹ️When the URL expires, you may send another API request to GET `https://op-sandbox.paymaya.com/profile` to obtain a new image URL.
`identityDocument[].backUrl` NULLABLE	string	Nullable when `backUrl` is not available due to unsupported format `backUrl` is a S3 presigned URL with expiry of `15 minutes` ℹ️When the URL expires, you may send another API request to GET `https://op-sandbox.paymaya.com/profile` to obtain a new image URL.
`identityDocument[].expiryDate`	string	`MM-dd-YYYY`
`identityDocument[].verificationStatus` NULLABLE	string	Reflects the verification status of the user's identity documents. Expected values: `PASS`, `FAILED`, null

✅ At this point, you should have the following tokens:

accessToken Valid user access token, either received in your session URL or acquired during refreshing tokens , whichever is the latest/valid value.

access_token A valid client token. See how to Obtain your Client .

JWE and JWK JSON Web Key (JWK) is a JSON object that represents a cryptographic key. JWK will be provided by Maya once onboarded. See 1 Before you integrate , for more details.

Step 1: Get Profile

GET https://op-sandbox.paymaya.com/profile

Use this endpoint to obtain the user’s profile data. Information that you are allowed to access will be defined in the scope of your client token which is determined during onboarding.

What happens during the Get Profile:

Following the API specifications, send your API request to GET https://op-sandbox.paymaya.com/profile
Upon successful call to this endpoint, Maya will respond to you with the encrypted profile data.

API Contract

Request Parameter

Request Header

Attribute	Type	Format	Description
`Content-Type` REQUIRED	string	`application/json`	Specifies the media type of the request
`Request-Reference-Number` REQUIRED	string	UUIDv4	Unique reference identifier for tracking the request
`Authorization` REQUIRED	string	JWS	Client token generated by Maya Connect. See how to Obtain your Client Token. Example: `Bearer clientToken-Value`
`X-Authorization` REQUIRED	string	JWE	Valid user access token (`accessToken`), either received in your session URL or acquired during refreshing tokens , whichever is the latest/valid value.

Successful Response

Response Body

Attribute	Type	Format	Description
`data` REQUIRED	string	JWE	This encrypted profile data is a JSON Web Signature (JWS) in a JSON Web Encryption (JWE). Some documents refer to it as nested JSON Web Token (JWT).

Step 2: Decrypt Profile Data

Successful call of GET https://op-sandbox.paymaya.com/profile endpoint would return an encrypted profile data. You will need to decrypt the data using the JWE and JWK keys that will be provided to your during onboarding.

{
  "kty": "<value>",
  "n": "<value>",
  "e": "<value>",
  "d": "<value>",
  "p": "<value>",
  "q": "<value>",
  "dp": "<value>",
  "dq": "<value>",
  "qi": "<value>"
}

{
  "kty": "<value>",
  "k": "<value>"
}

🧩 How to use JWE and JWK keys

Import privateJwk using the algorithm RS512.

Import secretJwk using the algorithm HS256.

Decrypt the JWE token (value of data from the response) using privateJwk to get the JWS token.

Verify JWS token from the decrypted JWE token (from #3) using secretJwk to get the raw profile.

Sample Codes


/**
 * Use node version 14
 * Install npm package jose
 *
 */

const { compactDecrypt, jwtVerify, importJWK } = require("jose");

const JWS_ALG = "HS256";
const JWE_KEY = <jwe_key>;
const JWS_KEY = <jws_key>;

const opToken = "<token>";


async function verifyOpToken(token) {
  try {
    // Import the JWE key
    const privateJwk = await importJWK(JWE_KEY);

    // Decrypt the JWE to get the JWS
    const decryptedJwe = await compactDecrypt(token, privateJwk);
    const decodedJwePayload = new TextDecoder().decode(decryptedJwe.plaintext);

    // Import the JWS key, verify the JWS and get the data
    const jwsSecretKey = await importJWK(JWS_KEY, JWS_ALG);
    const decryptedJws = await jwtVerify(decodedJwePayload, jwsSecretKey);
    console.log(decryptedJws);
  } catch (err) {
    console.log(err);
  }
}

verifyOpToken(opToken);
...


# Install library jwcrypto

#!/usr/bin/env python

import json
import sys
from jose import jwe, jwk, jws

def decrypt_and_verify_response(encrypted, private_jwk_str, secret_jwk_str):
  private_jwk = jwk.construct(json.loads(private_jwk_str), algorithm="RS512")
  secret_jwk = jwk.construct(json.loads(secret_jwk_str), algorithm="HS256")

  # decrypt jwe
  decrypted = jwe.decrypt(encrypted, key=private_jwk.to_dict()).decode('ascii')

  # decode and verify jws
  profile = json.loads(jws.verify(decrypted, key=secret_jwk, algorithms="HS256", verify=True))
  return profile

if __name__ == '__main__':
  args = sys.argv[1:]
  print(decrypt_and_verify_response(args[0], args[1], args[2]))


<?php
/* Install web-token/jwt-framework.
* Samples on how to import keys and load nested tokens.
* See the JWT Framework's official docs for more info.
*/

use Jose\Component\Core\JWK;
use Jose\Component\Core\AlgorithmManager;

use Jose\Component\Encryption\Algorithm\KeyEncryption\RSAOAEP;
use Jose\Component\Encryption\Algorithm\ContentEncryption\A256GCM;
use Jose\Component\Encryption\Compression\CompressionMethodManager;
use Jose\Component\Encryption\Compression\Deflate;
use Jose\Component\Encryption\JWEDecrypter;
use Jose\Component\Encryption\Serializer\JWESerializerManager;
use Jose\Component\Encryption\Serializer\CompactSerializer;

use Jose\Component\Signature\Algorithm\HS256;
use Jose\Component\Signature\JWSVerifier;
use Jose\Component\Signature\Serializer\JWSSerializerManager;
use Jose\Component\Signature\Serializer\CompactSerializer as SigCompactSerializer;


// OP Token
$token  = '<encrypted profile data>';

// Create keys
$jweKey = new JWK([<jwe_key>]);
$jwsKey = new JWK([<jws_key>]);

// Decrypt the JWE
$keyEncryptionAlgManager = new AlgorithmManager([ new RSAOAEP() ]);
$contentEncryptionAlgManager = new AlgorithmManager([ new A256GCM() ]);
$compressionMethodManager = new CompressionMethodManager([ new Deflate() ]);
$serializerManager = new JWESerializerManager([ new CompactSerializer() ]);

$jweDecrypter = new JWEDecrypter(
  $keyEncryptionAlgManager,
  $contentEncryptionAlgManager,
  $compressionMethodManager
);

$jwe = $serializerManager->unserialize($token);

// If error, will throw error
$isDecrypted = $jweDecrypter->decryptUsingKey($jwe, $jweKey, 0);
print_r($jwe->getPayload());


// Decrypt JWS
$jwsAlgManager = new AlgorithmManager([ new HS256() ]);
$jwsVerifier = new JWSVerifier( $jwsAlgManager );
$serializerManager = new JWSSerializerManager([ new SigCompactSerializer() ]);

$jws = $serializerManager->unserialize($jwe->getPayload());

// If error, will throw error
$isVerified = $jwsVerifier->verifyWithKey($jws, $jwsKey, 0);
print_r( $jws->getPayload());  // This is the decrypted profile data

Step 3: Process the raw Profile Data

Decrypting the profile data will provide you the raw profile, giving you the user information based on your scope.

ℹ️Maya follows Data Privacy and Security protocols, refer to Quick Start Guide for data handling integration pre-requisites.

Use Case: Create payments with user's Maya wallet

Now that the user can access and browse your application; with Maya Mini App, the users can make payments for the services and products offered by your application, without the need to re-enter their credentials.

Step 1: Create Payments

POST https://op-sandbox.paymaya.com/merchant/payments

✅ At this point, you should have the following tokens:

accessToken Valid user access token, either received in your session URL or acquired during refreshing tokens , whichever is the latest/valid value.

access_token A valid client token. See how to Obtain your Client .

p2mId Identifies your merchant account and will be provided to you by Maya during onboarding. See 1 Before you integrate , for more details.

From your application, the user opt to make payments using their Maya wallet. Utilize the Create Payments API to initiate and create a payment record.

⚠️ In this step, no debits will be done yet on the user’s Maya wallet. This endpoint will just create a payment record.

What happens during Create Payments:

Following the API specifications, send your API request to POST https://op-sandbox.paymaya.com/merchant/payments
Upon successful call to this endpoint, Maya will return the payment details and paymentId.

API Contract

Request Parameter

Request Header

Attribute	Type	Format	Description
`Content-Type` REQUIRED	string	`application/json`	Specifies the media type of the request
`Request-Reference-Number` REQUIRED	string	UUIDv4	Unique reference identifier for tracking the request
`Authorization` REQUIRED	string	JWS	Client token generated by Maya Connect. See how to Obtain your Client Token . Example: `Bearer {client-token-value}`
`X-Authorization` REQUIRED	string	JWE	Valid user access token (`accessToken`), either received in your session URL or acquired during refreshing tokens , whichever is the latest/valid value.

Request Body

Attribute	Type	Format	Description
`p2mId` REQUIRED	string		An identifier for your merchant account. Value will be provided by Maya during onboarding.
`amount` REQUIRED	object		An object for the base transaction amount
`amount.currency` REQUIRED	string	ISO 4217 Alpha-3	Currency code of the amount.
`amount.value` REQUIRED	float	`0.001` to `9999999999.99`	Transaction amount in the exponent / decimal notation of the provided currency

Successful Response

Response Body

Attribute	Type	Format	Description
`id` REQUIRED	string	UUIDv4	Payment ID referencing to the payment record created.
`p2mId` REQUIRED	string		An identifier for your merchant account. Value will be provided by Maya during onboarding.
`requestReferenceNumber` REQUIRED	string	AN(36)	Value provided by the merchant in the `Request-Reference-No parameter of the Create Payment request`
`amount` REQUIRED	object		An object for the base transaction amount
`amount.currency` REQUIRED	string	ISO 4217 Alpha-3	Currency code of the amount.
`amount.value` REQUIRED	float	`0.001` to `9999999999.99`	Transaction amount in the exponent / decimal notation of the provided currency
`fee` REQUIRED	object		An object for the base fee amount
`fee.currency` REQUIRED	string	ISO 4217 Alpha-3	Currency code of the transaction fee.
`fee.value` REQUIRED	float	`0.001` to `9999999999.99`	Fee amount in the exponent / decimal notation of the provided currency.

Step 2: Execute Payments

POST https://op-sandbox.paymaya.com/merchant/payments

While Create Payments is the creation of the payment record, Execute Payments API will complete the transaction and debit the amount on the user’s Maya wallet.

✅ At this point, you should have the following tokens:

accessToken Valid user access token, either received in your session URL or acquired during refreshing tokens , whichever is the latest/valid value.

access_token A valid client token. See how to Obtain your Client .

Payment id The ID value representing the payment record created during Create Payment

What happens during Execute Payments:

Following the API specifications, send your API request to POST https://op-sandbox.paymaya.com/merchant/payments/{id-from-create-payment}/execute
Upon successful call to this endpoint, Maya will process the payment transaction and will return the payment status.

🧠 Keep in mind

Execute payment endpoint is synchronous, thus response returned by this endpoint is final.

You can only execute payment id once, any succeeding attempts will result to error.

API Contract

Request Parameter

Path Parameter

Attribute	Type	Format	Description
`{id-from-create-payment}` REQUIRED	string	UUIDv4	Payment `id` referencing to the payment record created. Generated during Create Payment

Request Header

Attribute	Type	Format	Description
`Accept` REQUIRED	string	`application/json`
`Content-Type` REQUIRED	string	`application/json`	Specifies the media type of the request
`Request-Reference-Number` REQUIRED	string	UUIDv4	Unique reference identifier for tracking the request
`Authorization` REQUIRED	string	JWS	Client token generated by Maya Connect. See how to Obtain your Client Token . Example: `Bearer clientToken-Value`
`X-Authorization` REQUIRED	string	JWE	Valid user access token (`accessToken`), either received in your session URL or acquired during refreshing tokens , whichever is the latest/valid value.

Successful Response

Response Body

Attribute	Type	Format	Description
`id` REQUIRED	string	UUIDv4	Payment ID referencing to the payment record created.
`p2mId` REQUIRED	string		An identifier for your merchant account. Value will be provided by Maya during onboarding.
`requestReferenceNumber` REQUIRED	string	AN(36)	Value provided by the merchant in the `Request-Reference-No` parameter of the Create Payment request
`amount` REQUIRED	object		An object for the base transaction amount
`amount.currency` REQUIRED	string	ISO 4217 Alpha-3	Currency code of the amount.
`amount.value` REQUIRED	float	`0.001` to `9999999999.99`	Transaction amount in the exponent / decimal notation of the provided currency
`fee` REQUIRED	object		An object for the base fee amount
`fee.currency` REQUIRED	string	ISO 4217 Alpha-3	Currency code of the transaction fee.
`fee.value` REQUIRED	float	`0.001` to `9999999999.99`	Fee amount in the exponent / decimal notation of the provided currency.

Use Case: Allow fund transfer to user's Maya Wallet

Besides the capability of the user making a payment to your application, Maya Mini Apps also enables the user to withdraw an amount from your application and transfer to their Maya wallet.

✅ At this point, you should have the following tokens:

accessToken Valid user access token, either received in your session URL or acquired during refreshing tokens , whichever is the latest/valid value.

Secret Key Your Fund a Maya Wallet API key which will be provided to you by Maya during onboarding. See 1 Before you integrate , for more details.

Please refer to the Know Before you Code page to access relevant and important details regarding in integrating to the service.

🧠 Keep in mind

Refer to the Fund a Maya Wallet for the steps on funding a Maya wallet. In using Fund a Maya wallet:

You should always set the recipient.type as TOKEN

Pass the user access token (accessToken) as the recipient.value of the API request.

⚠️ The focus of this guide will be solely on sandbox endpoints and tokens. After successfully completing coordinated testing with Maya, you will be provided with production endpoints and access tokens. For the complete production go-live process, please coordinate with your Maya Relationship Manager.

How Maya Mini App works

⚠️ Complete Partner Onboarding

Access Tokens

Data Access

Maya App’s In-app Web view Limitations

1 Before you integrate

1a. Create your application’s session URL

ℹ️ Manage your User’s Session

API Contract

Request Payload you will receive

Request Header

Request Body

Response Payload you should return

Request Body

1b. Create your HTML 5 Mobile Web Application Landing Page

API Contract

Request Payload you will receive

Request Query

🧠 Keep in mind

2 Initiate and Manage Sessions

2a. Obtaining your Client Token

Client Token Expiry

What happens during the Client Token generation:

API Contract

Request Header

Request Body

Response Body

2b. Complete Session Initiation

What happens during the session initiation:

User Access Token Expiry

Conditional: Refreshing User Access Token

What happens during Refresh:

API Contract

Request Header

Request Body

Response Body

🧠 Keep in mind

3 Set up the users of your application

Available Scopes

What happens during the Get Profile:

API Contract

Request Header

Response Body

🧩 How to use JWE and JWK keys

Sample Codes

Use Case: Create payments with user's Maya wallet

What happens during Create Payments:

API Contract

Request Header

Request Body

Response Body

What happens during Execute Payments:

🧠 Keep in mind

API Contract

Path Parameter

Request Header

Response Body

Use Case: Allow fund transfer to user's Maya Wallet

🧠 Keep in mind

Payment APIs

Developer resources

More