This solution supports Cash-in to a Maya Wallet only.

Overview

Cash-in via Maya Login leverages the Maya-hosted login page to get user authorization, granting your application the permission to get the User Access Token and initiate the transaction on their behalf.

Cash-in via Maya Login requires a User Access Token to initiate the Cash-In. If you are unfamiliar with the User Access Token, you can start by reading User Authorization for Cash-in via Maya Login to implement the required steps in obtaining the User Access Token.

Your Access to the Cash-in to Maya Wallet Endpoints

In Maya, you must go through onboarding first to be granted access to the Cash-in to Maya Wallet, the service that facilitates the Cash-in transactions.

Acquiring Your API Key for Cash-in to Maya Wallet

During onboarding, your Maya Relationship Manager will ask you to submit the following:

1. The email address of your nominated key recipient
2. The public GPG key of your nominated key recipient. If you are unfamiliar with GPG, see the GNUPG document and start importing a public GPG key.

After successful onboarding, Maya will send you the API key specific for the Cash-in to Maya Wallet endpoints. The API key will be stored in an encrypted file using the public GPG you submitted during onboarding. The encrypted file will be sent to your nominated key recipient via email. Refer to the GNUPG document to start decrypting your file.

Keep in Mind

• Maya has two (2) environments, Sandbox and Production, each with distinct keys or credentials. See the API Environment to familiarize the API environments of Maya.
• API credentials are specific to the Maya solution you will be using

Storing Your API Credentials

API Credentials will be used to authenticate your application, so save them in a secure location. Misuse or mishandling of tokens or keys within the jurisdiction of the Partner could entail risks and vulnerability of transactions.

If your API keys are lost or breached, delete the old API keys and request to your Maya Relationship Manager to generate new ones in the same environment.

Build your Integration

Before you begin

• Ensure that you were onboarded in Sandbox and have obtained your API keys. If you have not receive it yet or unsure whether you were onboarded, reach out to your Maya Relationship Manager.
• Ensure that you have implented the User Authorization for Cash-in via Maya Login.

1. Get the User Access Token

Create a link or button event on your platform that will trigger the User Authorization for Cash-in via Maya Login. During this step, you should acquire the User Access Token before proceeding with the next steps.

2. Initiate and execute a Cash-in

Now that you have the User Access Token, you can now use it to initiate a Cash-in to Maya Wallet.

2.1. Initiate Transfer

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.

The transferId is a unique identifier used to ensure the idempotency of the transfer intent during execution.

At present, there is no time restriction for executing a transfer 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. Change in this behavior may be imposed in the future.

At this stage, no funds are moved within Maya. This is to provide you ample time to validate the transfer details, including recipient information, potential fees, and other relevant factors.

Refer to the Code Recipe below to guide you in building the request:

2.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 result of the Execute Transfer is 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.

Refer to the Code Recipe below to guide you in building the request:

3. Monitoring the Cash-in transaction

Monitor the Cash-in transaction.

3.a. 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.

Refer to the Code Recipe below to guide you in building the request:

3.b. 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.

Business Rules to Code

To supplement your knowledge of the integration, it is essential to know the Business Rules to Code for Cash-in. This ensures that technology requirements and other development considerations are met.

At this point, you have understood the following:

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

API Sequence

This solution requires implementation of User Authorization for Cash-in via Maya Login to proceed with the Cash-in transaction.

1. The customer initiates a Cash-in to their Maya wallet through the platform of the API Consumer.
2. The API Consumer prepares the valid token during User Authorization for Cash-in via Maya Login.
3. The API Consumer calls the Initiate a Transfer endpoint of Maya Cash-in using the customer access_token in Maya.
4. Maya Cash-in creates the transfer intent in Maya, uniquely identified by a transferId.
5. Maya Cash-in responds to the API Consumer with the generated transferId in Maya.
6. The API Consumer saves the transferId acquired from Maya.
7. The API Consumer calls the Execute Transfer endpoint of Maya, providing the transferId associated with the transfer intent in Maya.
8. Maya Cash-in processes the transfer intent in Maya.
9. If successful or failed, Maya Cash-in responds with the result.
10. 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 transferId in Maya.
• Maya Cash-in returns the details of the transfer intent associated with the transferId in Maya.

11. The API Consumer notifies the customer of the status.

Endpoints

Frequently Asked

1. Is there an expiry for the 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.
2. What to do when the User Access Token (access_token) expires?
   • Answer: Your platform must request to generate a new User Access Token (access_token) from the Maya Connect endpoint. Refer to the Refreshing an Expired Access Token section of the User Authorization for Cash-in via Maya Login.