As a Maya Mini App partner, you can leverage Maya's Cash-in to offer your customers a seamless way to transfer funds directly into their Maya wallet.
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 Cash-in to their Maya wallet through the API Consumer using a web view within the Maya App.
- The API Consumer prepares the valid token. Refer to the Maya Mini App
for more details.
- The API Consumer calls the Initiate a Transfer
endpoint of Maya Cash-in using the Customer Access Token (
accessToken) in Maya. - Maya Cash-in creates the transfer intent in Maya, uniquely identified by a
transferId. - Maya Cash-in responds to the API Consumer with the generated transferId in Maya.
- The API Consumer saves the
transferIdacquired from Maya. - The API Consumer calls the Execute Transfer
endpoint of Maya, providing the
transferIdassociated with the transfer intent in Maya. - Maya Cash-in processes the transfer intent in Maya.
- If successful or failed, Maya Cash-in responds with the result.
- If the API Consumer receives an ambiguous error
or no response from Maya Cash-in:
- API Consumer calls the Retrieve a Transfer
endpoint of Maya providing the
transferIdin Maya. - Maya Cash-in returns the details of the transfer intent associated with the
transferIdin Maya.
- API Consumer calls the Retrieve a Transfer
- The API Consumer notifies the customer of the status.
Build your Integration
This solution uses Basic Authentication, which requires API keys to authenticate incoming requests. To obtain your API key, please refer to the Acquire Keys from Relationship Manager guide.
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 Cash-in transaction.
Initiate and execute a Cash-in transaction
Use customer accessToken from the Maya Mini App to initiate and execute a Cash-in to Maya wallet.
accessToken from the Maya Mini App to initiate and execute a Cash-in to Maya wallet.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: Initiate Transfer
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.
Initiate the Cash-in by calling the Initiate a Transfer endpoint of Maya. Each transfer attempt creates a new intent and is assigned a unique
transferId in Maya. Maya recommends generating a unique request reference number for each transfer.
Note that Maya's transferId will be used to ensure the idempotency of the transfer intent during execution.
At present, there is no time restriction for executing a transfer intent after it has been created. However, if you choose not to proceed, you can discard the transferId and handle the customer management on your end.
NOTE: Change in this behavior may be imposed in the future.
At this stage, no funds are moved within Maya. This provides you ample time to validate transfer details, including recipient information, potential fees, and other relevant factors.
Step 2: Execute Transfer
After creating the intent to transfer in Maya, proceed by calling the Execute Transfer endpoint of Maya with the provided
transferId. Triggering the Execute Transfer of Maya finalizes the request and authorizes the balance movement in Maya.
Execution of a particular transfer in Maya can only be done ONCE. Whether APPROVED or DECLINED, succeeding execution in Maya will return an error.
At this stage, funds are moved from your account in Maya to the customer’s Maya wallet.
Monitor the Cash-in transaction
Monitoring the Cash-in transaction in Maya.
As a Cash-in partner
Maya’s Cash-in endpoint processes requests synchronously, returning the final state in the response.
If a timeout or ambiguous error occurs, you can use the Retrieve a Transfer
endpoint of Maya with the
transferId to check the status.
As a Maya Wallet user
Customers will be notified via SMS from Maya or the Maya mobile app notification. They can view the Cash-in transaction in the Transaction List within the Maya App.
Refer to Payments via Mini App to implement payments in the Maya Mini App.
Endpoints
The following are the endpoints relevant for Cash-in using Maya Mini App Token.
| Name | HTTP Method | Key Type | Endpoint | Description |
|---|---|---|---|---|
| Initiate Transfer | POST | SECRET | /transfers | Creates a transfer intent in Maya. Generates a transferId |
| Execute Transfer | PUT | SECRET | /transfers/{transferId}/execute | Processes a transfer intent on Maya associated with the transferId |
| Retrieve a Transfer | GET | SECRET | /transfers/{transferId} | Get the transfer intent in Maya associated with the transferId |
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
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 User Session for more details.
Is there an expiry on for transfer intent?
Answer: No expiry is implemented to the transfer intent in Maya. However, please note that a change in this behavior may be imposed in the future.