Product Guides
Maya Tech BlogGo to Maya Business Manager

Fund a Maya Wallet

Helps your customer to transfer their funds from your application onto their Maya wallet.

Maya’s Fund a Maya Wallet enables users to withdraw their funds from your application to their Maya Wallet.

To use Fund a Maya Wallet, you need to integrate with Maya Connect for user authentication, which is to enhance security and privacy, and with Money Movement for transferring funds.

⚠️

Maya allows transfers from external wallets to an upgraded (KYC1) Maya account only, otherwise transaction will be rejected with error code M133 (see Money Movement Errors for the list of error codes).

Maya recommends handling this error by prompting user to upgrade their Maya account via the Maya app. For more details, contact your Maya Relation Manager.

1 Getting started

Prior to initiating the integration process, it is essential to familiarize yourself with critical information about the solution and have accomplished the onboarding process.

Please refer to the Know Before you Code page to access relevant and important details regarding Money Movement.

For the onboarding requirements and checklists, consult the Quickstart guide.

2 Get authorization from your user

ℹ️ Are you a Maya Mini App partner?

Maya Mini App partners no longer need to implement this step. You may proceed to Funding a Maya Wallet .

Do you want to become a Maya Mini App partner? Check its use case and learn more .

This solution requires authorization from the user to fund their own Maya wallet. User needs to input their Maya credentials to authorize the transaction.

Step 1: Get authorization

To obtain authorization from the user, you need to redirect them to Maya Connect's URI. At this stage, the user will be presented with the Maya login screen, where user will need to enter their Maya Credentials and OTP (One-Time Password).
GET https://connect-sb-issuing.paymaya.com/authorize

Upon successful authorization, an authorization code will be generated and returned to your system.

🧠 Keep in mind

The authorization code is only valid for 5 minutes and is intended for single-use only. Maya will invalidate the code after initial use.


What happens during authorization:

  1. The user accesses your application and initiates a transfer of their funds to their Maya wallet.
  2. Using the provisioned Connect secret keys and following the API contract, your system sends an API request to GET https://connect-sb-issuing.paymaya.com/authorize
  3. Maya Connect displays the login and authorization form to the user.
  4. The user provides the necessary credentials and approves the authorization form.
  5. Maya Connect contacts your system by utilizing the designated redirect URL, supplying the authorization code and setting cookies.

API Contract

Request

Sample Request:

GET https://connect-sb-issuing.paymaya.com/authorize?
    response_type=code&
    client_id=myapp&
    redirect_uri=https://myapp.com/callback&
    prompt=login&
    user_id=+639412345678&
    state=sf9xm&
Request Parameters
Parameter Type Description
response_type REQUIRED string Indicates the authorization processing flow to be used. When using the Authorization Code Flow, this value is code.
client_id REQUIRED string Client ID
redirect_uri REQUIRED string Where the response will be sent. Must exactly match one of the Redirection URI values registered for the Client ID.
prompt REQUIRED string

Expected value for Fund a Maya Wallet integration:

  • login
    • Any user session will be destroyed and user will be asked to re-authenticate.
user_id REQUIRED string

Expected value for Fund a Maya Wallet integration:

  • {mobile number}
    • If a user exists with that identifier, it will redirect to login screen
    • Else, it will redirect to registration screen.
    • It will be pre-filled in the login or registration form and will not be editable.
state OPTIONAL string Recommended. Used to maintain state between the request and the callback. This can be used to mitigate Cross-Site Request Forgery (CSRF) attacks.

Successful Response

Once the user grants authorization, they will be redirected back to the specified redirect URI, accompanied by the following information:

Sample Request:

https://myapp.com/callback?code=X2wy4L&state=sf9xm&userId=%2B639*****5678&profileId=772988142429
Redirect URI Parameters
Parameter Description
code The generated authorization code.
state The same state value as supplied in the authorization request.
error Added if there is any error. e.g. login_required
userId Masked user ID
profileId A unique numeric system identifier for User

Login Scenarios

Maya Connect has a variety of login scenarios depending on the user_id value.

Scenario Result
If user_id was not initially provided in the browser request Redirects to Maya log in page

If user_id was initially provided in the browser request

AND

user_id is a valid Maya Account

Redirects to Maya login page with prefilled mobile number.

⚠️ If the user_id was pre-defined, the prefilled mobile number cannot be edited/modified.

If user_id was initially provided in the browser request

AND

user_id is NOT a valid Maya Account

 Redirects to Maya registration form with prefilled username.

Step 2: Get the user access token

Upon obtaining the authorization code, you need to exchange it for the user access token through the POST /token.
POST https://connect-sb-issuing.paymaya.com/token

✅ At this point, you should have the following tokens:

code

Valid authorization code, you've obtained during authorization of the user. See Step 1: Get authorization .
Secret Key

Your Maya Connect API key which will be provided to you by Maya during onboarding. See Quickstart guide.

A successful call to this endpoint will generate and provide the user access token, refresh token, and token expiry. At the same time, Maya will invalidate the authorization code.

TokenLifetime
User Access Token3600 seconds
Refresh Token604800 seconds

🧠 Keep in mind

The user access token has a validity of only 3600 seconds. Once it expires, you have the following options:

  1. Utilize the refresh_token to generate new user access token. Learn more.
  2. Return to Step 1, where the user needs to authorize the request by logging in again.

What happens during get token:

  1. With the Connect secret keys provisioned to you and following the API contract, send the API request to POST https://connect-sb-issuing.paymaya.com/token providing the authorization code.
  2. Maya Connect will respond with a user access token, refresh token and their token expiry details.

API Contract

This API endpoint requires Basic Authentication, which relies on client credentials. Your client_id serves as the username, while client_secret is the password. You must provide these credentials as part of the Authorization header in the form of a base64-encoded string.

--header Authorization: Basic <base64encode(clientId:clientSecret)>

Request
Request Header
Attribute Type Description
Content-Type REQUIRED string application/x-www-form-urlencoded
Authorization REQUIRED string

To comply with Basic Authentication, please encode your client credentials for Maya Connect (client_id and client_secret) into a base64-encoded string and include them in this header field.

Example: Basic {base64encode(clientId:clientSecret)}
Request Body
Attribute Type Description
grant_type REQUIRED string authorization_code
code REQUIRED string The authorization code received from the authorization request
redirect_uri REQUIRED string Identical redirect_uri as the authorization request

Successful Response
Response Body
Attribute Type Description
access_token string The user access token. Your application should store this securely while also consider the expiration.
token_type string Bearer
refresh_token string Token for getting a new user access token. Your application should store this securely while also consider the expiration
expires_in string Lifetime of the user access token in seconds.
scope string List of scopes enabled in the client.
id_token string ID value of the token

Conditional: Refresh user access token

When user access token expires, you can request new token by using the refresh token. This endpoint will be enabled depends on your use case and user journey. For more information, contact your Maya Relationship Manager.

⚠️ Your system or platform is expected to call the POST https://connect-sb-issuing.paymaya.com/token when the user access token expires providing the latest refresh token generated to request a new user access token.

It's important to note that each successful token refresh invalidates the previous user token, while refresh token remains the same until it expires.


POST https://connect-sb-issuing.paymaya.com/token

✅ At this point, you should have the following tokens:

refresh_token

Valid refresh token, you've obtained together with the user access token. See Step 2: Get the user access token .
Secret Key

Your Maya Connect API key which will be provided to you by Maya during onboarding. See Quickstart guide.


What happens during refresh token:

  1. With the Connect secret keys provisioned to you and following the API contract, send the API request to POST https://connect-sb-issuing.paymaya.com/token providing the refresh token.
  2. Maya Connect will respond with a new user access token and its token expiry details.

API Contract

This API endpoint requires Basic Authentication, which relies on client credentials. Your client_id serves as the username, while client_secret is the password. You must provide these credentials as part of the Authorization header in the form of a base64-encoded string.

--header Authorization: Basic <base64encode(clientId:clientSecret)>

Request
Request Header
Attribute Type Description
Content-Type REQUIRED string application/x-www-form-urlencoded
Authorization REQUIRED string

To comply with Basic Authentication, please encode your client credentials for Maya Connect (client_id and client_secret) into a base64-encoded string and include them in this header field.

Example: Basic {base64encode(clientId:clientSecret)}
Request Body
Attribute Type Description
grant_type REQUIRED string refresh_token
refresh_token REQUIRED string The refresh token received from during Get user access token
scope OPTIONAL string Space-delimited list of scopes which should be a subset of the original set of scopes requested. Omitting this will default to requesting the original set of scopes.

Successful Response
Response Body
Attribute Type Description
access_token string The user access token. Your application should store this securely while also consider the expiration.
token_type string Bearer
refresh_token string Token for getting a new user access token. Your application should store this securely while also consider the expiration
expires_in string Lifetime of the user access token in seconds.
scope string List of scopes enabled in the client.
id_token string ID value of the token

3 Funding user's Maya wallet

For you to proceed in funding user's Maya wallet, you will be needing to provide the user access token upon creating a transfer intent. This time-limited token will be used to identify user and their Maya wallet.

🧠 Keep in mind

User access token can be acquired in different ways, depends on your integration:

  1. For the standalone Fund a Maya Wallet, you will acquire the user access token through Step 2: Get the user access token.
  2. For Maya Mini App partners, user access token is provided to your system during session initiation

Step 1: Create a Transfer

Once you have acquired the user access tokens you can proceed with creating an intent to transfer, utilizing the user access token as the recipient.
POST https://api-test.paymaya.com/mi3-sandbox/transfers

🧠 Keep in mind

When using user access tokens to represent the recipient, the account type of the recipient (recipient.type) in the transfer request must be set as TOKEN and the recipient.value is the user access token acquired in Step 2: Get the user access token.

At this stage, no actual movement of funds will occur. This allows you sufficient time to validate the transfer details, including recipient information, potential fees, and other relevant factors.

⚠️ Creating transfers always result in a new intent even when using the same request reference number. See also Know Before you Code for the information related to idempotency.


What happens during create transfer:

  1. With the API keys provisioned to you and following the API contract, send the API request to POST /transfers providing the user access token.
  2. Maya will respond with the transferId and its transfer details.

ℹ️ There is currently no time limit for executing a transfer after creation. Change on this behavior may be imposed in the future.

Step 2: Execute the Transfer

Once the intent to transfer has been created, utilize this endpoint to execute the transfer. To do so, you will need to provide the transferId obtained during the Step 1: Create a Transfer.
PUT https://api-test.paymaya.com/mi3-sandbox/transfers/{transferId}/execute

⚠️ The execution of a specific transfer can only be performed ONCE, and any subsequent attempts will result in an error.

Following a successful call, the state will be updated to either APPROVED or DECLINED depending on the status of the transaction processing.


What happens during execute transfer:

  1. With the API keys provisioned to you and following the API contract, send the API request to PUT /transfers/{transferId}/execute.
  2. Maya will return the status of the transfer after processing.

Conditional: Retrieve a Transfer

Maya made this endpoint available for you to obtain the transfer details or check the status of a transfer by using the transferId obtained during Step 1: Create a Transfer.
GET https://api-test.paymaya.com/mi3-sandbox/transfers/{transferId}


What happens during retrieve transfer:

  1. With the API keys provisioned to you and following the API contract, send the API request to GET /transfers/{transferId}.
  2. Maya will return the transfer details and its state.

🧩 When to use Retrieve a Transfer

Maya recommends using Retrieve a Transfer when you have encountered the following scenarios during Execute transfer and Retrieve a transfer, to validate the transaction before you proceed to the next steps (For example: Execute a transfer):

  1. When you did not receive response from Maya.
  2. When the response from Maya is ambiguous (gateway errors, time outs, anything unparsable). See Money Movement errors for more details.

Updated 8 months ago

Payment APIs

Vault
Checkout
Pay with Maya
Invoice

Developer resources

Demo Apps
GPG Guide
Maya plugins
Webhooks
Sandbox credentials and cards

More

Maya Tech Blog
Contact support
Maya Business Home
Contact sales
Pricing

© Copyright Maya 2023 All Rights Reserved.