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:
- When the user goes to their Maya App and clicks your tile, Maya will initiate a session with your system.
- Once the session has been established, Maya will redirect the 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 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:
Environment | IP Address |
---|---|
Sandbox | 52.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 andsessionId
.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 samesessionId
, 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: |
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: |
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
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 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
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 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 ( Example: |
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 |
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/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 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 andsessionId
.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 samesessionId
, 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.
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 POSThttps://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
Your system or platform is expected to callhttps://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 newrefreshToken
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: |
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: |
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: |
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: |
contact[].subType
| string | Subtype of user's contact. Expected values: |
contact[].value
| string | If type is If type is |
contact[].verificationStatus NULLABLE |
string | Reflects the verification status of the name registered. Expected values: |
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: |
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: |
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: |
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. |
identityDocument[].value
NULLABLE |
string | Nullable when:
|
identityDocument[].frontUrl
NULLABLE |
string | Nullable when:
|
identityDocument[].backUrl
NULLABLE |
string | Nullable when
|
identityDocument[].expiryDate |
string | MM-dd-YYYY |
identityDocument[].verificationStatus NULLABLE |
string | Reflects the verification status of the user's identity documents. Expected values: |
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
andJWK
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.
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: |
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.
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
- Import
privateJwk
using the algorithmRS512
.- Import
secretJwk
using the algorithmHS256
.- 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 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.
In this step, no debits will be done yet on the user’s Maya wallet. This endpoint will just create a payment record.
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: |
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.
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: |
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 Business Rules to Code for Cash-in page to access relevant and important details regarding in integrating to the service.
Keep in mind
Refer to the Cash-in from a Mini App for the steps on funding a Maya wallet. In using Fund a Maya wallet:
- You should always set the
recipient.type
asTOKEN
- Pass the user access token (
accessToken
) as therecipient.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 about 1 month ago