As a Maya Mini App partner, your customers can easily make payments for products and services in your Mini App without having to re-enter their credentials.

This solution requires complete implementation of the Maya Mini App .

API Sequence

This solution requires the Customer Access Token (accessToken), which you will obtain during session initiation as part of the full implementation of the Maya Mini App. For more details, please refer to the Maya Mini App guide.

The Customer initiates a Payment using their Maya Wallet through the API Consumer's Mini App within the Maya App.
The API Consumer prepares the required tokens and credentials acquired from the Maya Mini App:
- Customer Access Token: the accessToken obtained from Maya through either your session URL or acquired by refreshing the tokens , whichever is the most recent or valid value
- Client Credentials Token: the access_token acquired during OAuth 2.0 Authentication using the client_credentials grant type
The API Consumer calls the Create Maya Mini App Payment endpoint providing the customer's accessToken in Maya.
Maya Mini App creates a payment record in Maya, uniquely identified by the payment id.
Maya Mini App responds to the API Consumer with the generated id in Maya.
The API Consumer saves the payment id from the response of Maya Mini App.
The API Consumer calls the Execute Maya Mini App Payment endpoint of Maya, providing the payment id associated with the payment record in Maya.
Maya Mini App processes the payment in Maya.
Whether the transaction is successful or failed, Maya Mini App responds with the result.
The API Consumer notifies the customer of the status.

Build your Integration

This solution uses Bearer Authentication which relies on the Client Credentials Token (access_token) to authenticate incoming requests. access_token is generated during OAuth 2.0 Authentication using the client_credentials grant type.

Create the required pages

Design and host your mini app or webview pages.

Based on your envisioned customer journey, design and create a button within your page for your customers to initiate the payment transaction.

Create and execute a Payment transaction

Use the customer accessToken from the Maya Mini App to create and execute a payment transaction.

When implementing Maya Mini App, your Mini App shall be able to utilize the Customer Access Token or the accessToken obtained from Maya through your session URL or acquired by refreshing the tokens , whichever is the most recent or valid value.

Once your application has acquired the Customer Access Token (accessToken) from Maya, you may proceed with the following steps.

Step 1: Create Payment

Any requests using an expired Customer Access Token (accessToken) will result in an error.

Be sure to use a valid accessToken and request a new accessToken as needed. Refer to the Manage Mini App Session: Expired Customer Session for the handling of expired accessToken.

The customer should be able to make payments using their Maya Wallet in your Mini App by implementing Maya Mini App's Create Maya Mini App Payment .

This endpoint will require you to provide your p2mId, used to identify your merchant account; Maya will provide this information during onboarding.

After a successful call, this endpoint will respond to your Mini App with the transaction details along with the payment id. Save this id and use it to execute payments and monitor transactions.

At this stage, no debits will be done yet on the customer's Maya Wallet.

Retries for Create Payment

In cases where there is no response from this endpoint or a timeout occurs, your Mini App could retry the API call. Each time a new request is sent to this endpoint, a unique payment id is generated. It is important to note that no actual balance movement occurs following the creation of the payment.

📖

Create Maya Mini App Payment

Open Recipe

Step 2: Execute Payment

Any requests using an expired Customer Access Token (accessToken) will result in an error.

Be sure to use a valid accessToken and request a new accessToken as needed. Refer to the Manage Mini App Session: Expired Customer Session for the handling of expired accessToken.

After a successful create payment, provide the returned payment id to the Execute Maya Mini App Payment endpoint to proceed with the process. Triggering the Execute Maya Mini App Payment finalizes the request and authorizes the balance movement in Maya.

Execution of a particular payment in Maya can only be done ONCE. Whether APPROVED or DECLINED, succeeding execution of payment in Maya will return an error.

At this stage, the transaction amount will be charged to the customer's Maya Wallet.

Retries for Execute Payment

When there is no response or a timeout happens at this endpoint, your Mini App can safely attempt the API call again. The execute payment function is designed to be retried without any risks, as it will only process the payment once. If you try to execute a payment that has already been successfully processed, you will receive the error code PY0010, with the description "The payment has already been processed".

📖

Execute Maya Mini App Payment

Open Recipe

Monitor the Payment transaction

Monitoring the Payment transaction in Maya Manager.

Maya Mini App Payments are processed in a synchronous approach, thus responses from the Execute Maya Mini App Payment endpoint are final.

In cases when errors are encountered, you may validate the transaction via the Maya Manager. For more details, reach out to your Maya Relationship Manager.

Refer to Cash-in from a Mini App to implement Cash-in in the Maya Mini App.

Endpoints

The following are relevant endpoints for Payments via Maya Mini App.

Name	HTTP Method	Key Type	Endpoint	Description
Create Maya Mini App Payment	POST	Bearer Auth	/merchant/payments	Creates payment using the valid Customer Access Token (`accessToken`), either obtained through your session URL or acquired by refreshing the tokens , whichever is the most recent or valid value
Execute Maya Mini App Payment	POST	Bearer Auth	/merchant/payments/{id}/execute	Executes payment using the payment `id` acquired during Create Maya Mini App Payment

Business Rules to Code

To supplement your knowledge of the integration, it is essential to read the following business rules:

This ensures that technology requirements and other development considerations are met.

At this point, you have understood the following:

The necessary APIs and their endpoints
The sequence and purpose of each API
The prerequisites for building your integration

Frequently Asked

What to do when customer's accessToken expires?

Answer: Your platform must request to generate a new Customer Access Token (accessToken) from the Maya endpoints. See the Manage Mini App Session: Expired Customer Session for more details.

Is there an expiry on the created payment?

Answer: You may refer to the Payment Expiry section in the Business Rules to Code for Online Payments.

When timeout occurs, can my Mini App retry the payment?

Answer:

Retries for Create Payment

It’s safe to retry the create payment, as each time a new request is sent to this endpoint, a unique payment id is generated. It is important to note that no actual balance movement occurs following the creation of the payment.

Retries for Execute Payment

It’s safe to retry the execute payment, as it will only process the payment once. If you try to execute a payment that has already been successfully processed, you will receive the error code PY0010, with the description "The payment has already been processed".

Payments via Mini App