Product Guides
Maya Tech BlogGo to Maya Business Manager

Maya Mini Apps Technical Guide

Your guide to become an app within Maya

⚠️ 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 a 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:

  1. When the user goes to their Maya App and clicks your tile, Maya will initiate a session with your system.
  2. Once the session has been established, Maya will redirect the user to your landing page via webview.
  3. Comply with Maya’s authentication and acquire access.
  4. 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 the user’s profile for pre-filled forms
    • Maintain and keep user session while the user continues to browse your webview
    • Accept payments using the user’s Maya Wallet as a fund source
    • Transfer funds to the 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 the user’s data and their Maya account.

For privacy checks, some of the components of the Maya Mini App require 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 Webview 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 prerequisites: 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 users’ sessions, 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.

Create your application’s session URL

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

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

EnvironmentIP Address
Sandbox52.76.175.228
13.251.40.239
13.251.3.237
18.138.3.140

Every time users access 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
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.

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 a mobile-responsive design.

Maya will redirect the user to your landing page, with the sessionId your session URL endpoint returned during session initiation. Make sure that your landing page can 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
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}

  1. Your system should be a GET endpoint and should receive a query parameter name sessionId.
  2. 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.
  3. In addition, landing page URL should be SSL-secured (https) and publicly accessible.
  4. 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

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.

  1. Maya Connect client ID
  2. Maya Connect client secret
  3. JWE and JWK keys to be used to decrypt profile data
  4. p2mid, if you have payments use case
  5. 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 before 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 with the 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:

  1. Valid Client ID
  2. 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 a successful call to this endpoint, Maya will respond to you with a client token (access_token).

API Contract

This API endpoint requires Basic Authentication, which relies on client credentials. Your client_id serves as the username, while client_secret is the password. You must provide these credentials as part of the Authorization header in the form of a base64-encoded string.

--header Authorization: Basic <base64encode(clientId:clientSecret)>

Request Parameters
Request Header
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

To comply with Basic Authentication, please encode your client credentials (client_id and client_secret) into a base64-encoded string and include them in this header field.

Example: Basic {base64encode(clientId:clientSecret)}
Request Body
Attribute Type Format Description
grant_type REQUIRED string client_credentials

Successful Response
Response Body
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)

ℹ️ 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 prerequisite steps, it is expected that your mini-application will be able to successfully receive and process the following data:

Your URL/EndpointsData you'll ReceiveData to Return
Session URLaccessToken
refreshToken
expiresAt		sessionId
Landing PagesessionId

🧩 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 the user clicks your icon/tile in the Maya App, Maya will start initiating session.
  • During session initiation, Maya will ask the user for their consent and notify the user of the data that will be shared with you.
  • When the 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 your landing page, with the sessionId value acquired from your session URL.

ℹ️ 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.

User Access Token Expiry

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

TokenLifetime
accessToken600 seconds
refreshToken1200 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 exceed 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

⚠️ Your system or platform is expected to call POST https://op-sandbox.paymaya.com/tokens when the user access token expires providing the latest refresh token generated to request a new user access token.

It's important to note that every successful token refresh will invalidate the old tokens.


What happens during Refresh:

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

API Contract

This API endpoint requires Bearer Authentication (also called Token Authentication), which relies on the client token (bearer token) generated by Maya Connect Token API. You must provide this token as part of the Authorization header.

--header Authorization: Bearer <client_token>

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-No 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}
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

A successful call to this endpoint will generate a 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 features is seamless profile sharing. Maya Mini App provides you secure access to a user profile which you can use to authenticate an existing user with a Maya account or for account registration on your application.

Access to the 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 A 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

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.
GET https://op-sandbox.paymaya.com/profile


What happens during the Get Profile:

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

API Contract

This API endpoint requires Bearer Authentication (also called Token Authentication), which relies on the client token (bearer token) generated by Maya Connect Token API. You must provide this token as part of the Authorization header.

--header Authorization: Bearer <client_token>

Request Parameter
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
Authorization REQUIRED string JWS

Client token generated by Maya Connect. See how to Obtain your Client Token.

Example: Bearer {client_token}
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 you 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

  1. Import privateJwk using the algorithm RS512.
  2. Import secretJwk using the algorithm HS256.
  3. Decrypt the JWE token (value of data from the response) using privateJwk to get the JWS token.
  4. 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 with 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 the 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

From your application, the user opts 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.


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.

What happens during Create Payments:

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

API Contract

This API endpoint requires Bearer Authentication (also called Token Authentication), which relies on the client token (bearer token) generated by Maya Connect Token API. You must provide this token as part of the Authorization header.

--header Authorization: Bearer <client_token>

Request Parameter
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
Authorization REQUIRED string JWS

Client token generated by Maya Connect. See how to Obtain your Client Token .

Example: Bearer {client_token}
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


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.
POST https://op-sandbox.paymaya.com/merchant/payments/{id-from-create-payment}/execute


✅ 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 a 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

This API endpoint requires Bearer Authentication (also called Token Authentication), which relies on the client token (bearer token) generated by Maya Connect Token API. You must provide this token as part of the Authorization header.

--header Authorization: Bearer <client_token>

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-No 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}
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 it 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.

Updated 6 months ago

Payment APIs

Vault
Checkout
Pay with Maya
Invoice

Developer resources

Demo Apps
GPG Guide
Maya plugins
Webhooks
Sandbox credentials and cards

More

Maya Tech Blog
Contact support
Maya Business Home
Contact sales
Pricing

© Copyright Maya 2023 All Rights Reserved.