Cash-in via Maya Login enables your customers to authorize funds transfer from your platform to their Maya account through Maya login.
Leverage Cash-in via Maya Login to perform:
- Fund the customer’s Maya wallet via your platform
- Leverage the OAuth 2.0 for customer authorization and generate a token representing the customer's Maya wallet
This solution requires Customer Authorization using the authorization_code grant.
API Sequence
This solution requires customer access_token, which you will obtain during customer authorization. For more details, please refer to the authorizarion_code grant.
- The customer initiates a Cash-in to their Maya wallet through the platform of the API Consumer.
- The API Consumer prepares the valid token. Refer to the authorization_code
grant for more details.
- The API Consumer calls the Initiate a Transfer
endpoint of Maya Cash-in using the customer
access_tokenin 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
transferIdin 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 web pages.
Step 1: Create Cash-in to Maya Button
Based on your envisioned customer journey, design your page and create a button to trigger the Cash-in to Maya Wallet within your page.
Step 2: Handle the Cash-in to Maya button event
Handle the button event in your platform to trigger the Customer Authorization, by implementing the OAuth 2.0 authorization_code grant. During this step, you will acquire an authorization code and exchange it for the customer
access_token.
Initiate and execute a Cash-in
Use the customer access_token from the authorization_code grant to initiate and execute a Cash-in to Maya wallet.
access_token from the authorization_code grant to initiate and execute a Cash-in to Maya wallet.Acquire and secure the customeraccess_token by completing the Customer Authorization Flow, the OAuth 2.0 authorization_code grant. Once your application has acquired the
access_token from Maya, you may proceed with the following steps.
Step 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, even with the same request reference number. transferId will be used to ensure idempotency during execution. On the other hand, Maya still recommends generating a unique request reference number for each transfer, even though Maya does not validate it.
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.
Endpoints
The following are the endpoints relevant for Cash-in via Maya Login.
| 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 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:
- The necessary APIs and their endpoints
- The sequence and purpose of each API
- The prerequisites for building your integration
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.
What to do when customer's accessToken expires?
Answer: Your platform must request to generate new access_token from the Maya Connect endpoint. See the OAuth 2.0 refresh_token grant for more details.