This flow covers both the normal token generation and session usage and the handling of an expired session.

1. The customer clicks the tile within the Maya App triggering the Maya Mini App.
2. The Maya Mini App performs an age and KYC (Know Your Customer) check.
3. If no consent is recorded:
   • Maya App will prompt the customer with the consent screen.
   • The customer will then agree to the terms presented and give consent.
   • Maya Mini App records the consent.
4. Maya Mini App generates a Customer Access Token (accessToken).
5. Maya Mini App sends the Customer Access Token (accessToken) to the API Consumer through their session URL endpoint.
6. The API Consumer saves the Customer Access Token (accessToken) and generates a unique sessionId to correspond with the Customer Access Token (accessToken).
7. API Consumer sends the sessionId as a response to the Maya Mini App.
8. The Maya Mini App appends the sessionId to the API Consumer's registered landing page URL.
9. Maya Mini App redirects the Customer to the API Consumer's landing page URL.
10. The API Consumer uses the sessionId to verify the saved Customer Access Token (accessToken).
11. The API Consumer invalidates the sessionId.
12. 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
13. The API Consumer calls the Get Profile endpoint of the Maya Mini App, providing the accessToken and access_token.
14. Maya Mini App processes the request and retrieves the profile data based on the client scope. Refer to the Supported Scopes section for the list of scopes.
15. After retrieving the profile data, the Maya Mini App sends the encrypted profile data to the API Consumer.
16. The API Consumer monitors the Customer Access Token (accessToken) and Customer Refresh Token (refreshToken) expiry.
17. When the Customer Refresh Token (refreshToken) is about to expire:
    • The API Consumer uses the refreshToken and call the Refresh Token endpoint of the Maya Mini App.
    • Maya Mini App will generate a new Customer Access Token (accessToken) and new Customer Refresh Token (refreshToken).
    • Maya Mini App returns the new Customer Access Token (accessToken) and new Customer Refresh Token (refreshToken) to the API Consumer.
    • The API Consumer updates their system to save the new Customer Access Token (accessToken) and new Customer Refresh Token (refreshToken).
18. When you need the accessToken but it is already expired:
    • The API Consumer uses the valid or the most recent refreshToken and call the Refresh Token endpoint of the Maya Mini App.
    • Maya Mini App will generate a new Customer Access Token (accessToken) and new Customer Refresh Token (refreshToken).
    • Maya Mini App returns the new Customer Access Token (accessToken) and new Customer Refresh Token (refreshToken) to the API Consumer.
    • The API Consumer updates their system to save the new Customer Access Token (accessToken) and new Customer Refresh Token (refreshToken).

To enhance security, you should implement IP whitelisting in your Mini App allowing access to Maya systems only. Implement an IP whitelisting mechanism and specify Maya’s IP Addresses.

Note that the Maya Mini App requests should come from the IPs listed below.

You must create a dedicated endpoint, or the Session URL, where Maya can send the customer session securely and efficiently. Each time a customer accesses your application from the Maya app, Maya will send an API request to your Session URL endpoint.

With the customer's consent, Maya Mini App will send the following to your Session URL endpoint:

• Customer Access Token: the accessToken that your mini app will need to perform actions on behalf of the customer
• Customer Refresh Token: the refreshToken that your mini app can use to generate a new customer access token

Sample payload your Session URL will receive:

curl --location 'https://your.site.com/mayaminiapp/accept' \
--header 'Request-Reference-No: bbd94290-1078-47c4-bc1a-a5a326afaaf5' \
--header 'Content-Type: application/json' \
--data '{
    "accessToken": "eyJ1aWQiOiI0MGE2YmI1NS1iYzBjLTQzMjktYTE0Yi0wMzlmY2I3ZmRkZjciLCJjbGllbnRfaWQiOiIwZjFmMjJhYy1lMjQzLT",
    "refreshToken": "eyJ1aWQiOiI0MGE2YmI1NS1iYzBjLTQzMjktYTE0Yi0wMzlmY2I3ZmRkZjciLCJjbGllbnRfaWQiOiIwZjFmMjJhYy1lMjQzLT",
    "expiresAt": 1659375851
}'

The Session URL endpoint must be capable of receiving and processing this request according to the provided API contract and shall respond with a sessionId to Maya. Be sure to follow the Session URL API Contract .

Sample Payload your Session URL is expected to respond:

{
    "sessionId": "Lr7I2MPDy_WUnnyCWyEE3737_PZF2VIKlQXbi-Q8kZw"
}

Create a web application your customer can access within the Maya app. It should be mobile-responsive.

Maya will redirect the customer to your landing page, with the sessionId generated by your SessionURL endpoint. Implement the necessary logic and make sure that your landing page accepts and handles sessionId.

Development Considerations for the Landing Page

Maya will redirect the customer to your landing page, with the appended sessionId.

Landing Page URL (Sample): https://your-landing-page-url.com

Landing Page URL with appended sessionId: https://your-landing-page-url.com?sessionId={sessionId-value}

• Your landing page should be a GET endpoint capable of receiving the sessionId query parameter
• Invalidate the sessionId after its initial use to prevent reuse; your system should reject any subsequent attempts with the same sessionId
• Ensure the landing page URL is SSL-secured (https) and publicly accessible.
• Configure SSL on the standard port 443 to avoid potential network issues with Maya integration

During session initiation, Maya will use the following endpoints you have developed and submitted during onboarding:

Be guided by the flow described in the API Sequence.

Your Mini App is expected to call Refresh Token endpoint providing the required tokens when:

• The customer initiates a transaction but the Customer Access Token (accessToken) is already expired
• The customer is still active in your Mini App and the Customer Refresh Token (refreshToken) is about to expire

Refer also to the Handling of Expired Maya Mini App Tokens for the scenarios and proper handling.