Skip to main content

Maya

The Maya Wallet, a top digital wallet in the Philippines, offers secure, real-time payments. Integrating Maya can help your business provide a smooth, local payment experience to a broad customer and merchant base.

This guide will walk you through integrating Maya Wallet via API, covering essential steps like initiating payments, handling user redirection, checking payment statuses, and managing timeouts or cancellations.

Maya supports intent-based flows through mobile and QR flows via web browsers, allowing for instant payment collection with just a tap.

Maya Wallet payments are instant, irrevocable, and real-time, making them a high-conversion, low-risk payment method for the market.

Requirements

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
  • Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.

How it works

If the customer is paying by mobile and has the Maya app, the mobile flow activates automatically via our API-provided address. If using a web browser, this link will display a dynamic QR code to open the Maya app on their phone.

Mobile Flow

  1. The customer chooses Maya Wallet as their payment method.
  2. Merchant requests a Maya transaction with EBANX.
  3. EBANX provides a Maya callback link in response payload.
  4. The merchant redirects the customer to this callback link.
  5. The customer is then redirected to the Maya app.
  6. Customers authenticate by entering an OTP (One-Time Password) linked to their Maya account.
  7. The payment details automatically appear in the app.
  8. The customer can confirm the transaction by tapping “Confirm Payment” in the Maya app.
  9. The customer is redirected back to the merchant's site after payment confirmation.

Web Flow

  1. The customer chooses Maya Wallet as their payment method.
  2. Merchant requests a Maya transaction with EBANX.
  3. EBANX provides a Maya callback link in response payload.
  4. The merchant redirects the customer to this callback link.
  5. The customer is then redirected to a web page displaying a dynamic QR code.
  6. The customer scans the QR code using the Maya app.
  7. The customer authenticates by entering an OTP (One-Time Password) linked to their Maya account.
  8. The payment details automatically appear in the app.
  9. The customer can confirm the transaction by tapping “Confirm Payment” in the Maya app.
  10. The customer is redirected back to the merchant's site after payment confirmation.

Technical flow

  • Request payment - Call the ws/direct endpoint with the parameters defined below
  • Payment instructions - In response to this request, EBANX will return a link to the Maya platform, to which the merchant must redirect the customer to complete the transaction.
  • Customer completes the payment - Once this link is accessed, the customer will have 30 minutes to complete the transaction. During this time, the transaction will be set on our platform with the status pending (PE).
  • Payment Confirmation - As soon as the customer completes the transaction with Maya, EBANX will receive the response and immediately change the payment status to confirmed (CO) or cancelled (CA).

When this status change occurs, the merchant will receive a notification from us, informing them of the payment hash and that a change has occurred in the payment. To view the final status, simply query the payment through the ws/query endpoint.

Instructions

Follow the steps below.

  1. Select your environment

    Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

    https://sandbox.ebanx.com/ws/direct
  2. Retrieve available Digital Wallets

    Check which wallets are available by selected a country using the /ws/ewallet-availableEWallets endpoint.

    Sample Request

    curl -X POST 
    --location 'https://api.ebanx.com/ws/ewallet-availableEWallets' \
    --header 'Content-Type: application/json' \
    --data '{
    "integration_key": "{{your_ebanx_integration_key}}",
    "operation": "request",
    "country": "ph"
    }'

    The API response will return an array of available digital wallets for the selected country. Look for Maya to confirm availability.

    // Sample response: an array of digital-wallet objects.
    [
    {
    "code": "paymaya",
    "name": "Maya",
    "icon_url": "https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/maya/icon.png",
    "promotional_text": "Pay easily with Maya"
    },
    {
    "code": "g-cash",
    "name": "GCash",
    "icon_url": "https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/gcash/icon.png",
    "promotional_text": "Pay easily with GCash."
    }
    ]
    For more information, refer to the
    API reference for digital walletschevron_right
  3. Render digital wallets options

    You can render the Maya details on your checkout page using the information provided in the API response.

    • Display the icon_url to show the Maya logo.
    • Use the promotional_text to display a message for Maya.

    Example HTML

      <div class="digital-wallet">
    <img src="https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/maya/icon.png" alt="Maya logo image">
    <p>Pay easily with Maya.</p>
    </div>
  4. Get the digital wallet code

    Each digital wallet in the response contains a unique code that identifies the wallet (e.g., "maya", "g-cash", "nupay"). You’ll need this code to create a payment. In this case maya.

  5. Define your parameters

    To create a Maya payment, you need to define the parameters in your request. The following table outlines the required parameters for the payment process.

    ParameterRequirementDescription
    integration_keyRequiredYour secret EBANX integration key
    operationRequiredSet to request
    payment_type_codeRequiredSet to paymaya
    countryRequiredSet to ph for Philippines
    nameRequiredCustomer name
    emailRequiredCustomer email
    phone_numberRequiredCustomer phone number
    zipcodeOptionalCustomer zipcode
    merchant_payment_codeRequiredUnique merchant payment code
    currency_codeRequiredMust be php
    amount_totalRequiredTotal amount to be charged
    redirect_urlRequiredURL to callback after finish transaction with Maya
    Minimum and Maximum Amounts

    Maya has a minimum amount limit of 20 PHP and a maximum limit between 50.000 and 100.000, depending on the type of wallet

  6. Payment request

    Once your customer submits a Maya payment, create a payment request using the ws/direct endpoint. Assign the payment_type_code parameter to the digital wallet code.


    Sample request

    curl -X POST \
    --location 'https://api.ebanx.com/ws/direct' \
    --header 'Content-Type: application/json' \
    --data '{
    "integration_key": "{{YOUR_INTEGRATION_KEY}}",
    "operation": "request",
    "payment": {
    "name": "Zara",
    "email": "zara@abc.com",
    "country": "ph",
    "phone_number": "5541991669499",
    "zipcode": "560032",
    "city": "MNB",
    "payment_type_code": "paymaya",
    "merchant_payment_code": "3d09618e-b830-4aa4-9a53-83b70f181991",
    "currency_code": "PHP",
    "amount_total": 500,
    "redirect_url": "https://your-call-back-url.com"
    }
    }'
  7. Payment successful response

    Each request returns a response similar to the example below.

    {
    "payment": {
    "hash": "685d7ce548c6f24391e6a94230aa7b05d66d063c92b10649",
    "country": "ph",
    "merchant_payment_code": "3d99618e-b830-4aa0-9a53-83b70f181991",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2025-06-26 17:01:25",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "500.00",
    "amount_ext": "500.00",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "PHP",
    "due_date": "2025-06-29",
    "instalments": "1",
    "payment_type_code": "paymaya",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
    "email": "zara@abc.com",
    "name": "ZARA"
    },
    "currency_ext_base": "PHP",
    "redirect_url": "https://api.ebanx.com/ws/redirect/execute?hash=5ec27f3b86fa8e318ddcc9727453626aec3989aa2ceccdb7"
    },
    "status": "SUCCESS"
    }

    At this stage, the payment will appear as pending (PE) in your
    EBANX Dashboardchevron_right

    redirect_url behavior

    Note that the address returned from EBANX in redirect_url on the response (the address to which the customer must be redirected to continue with the transaction within the Maya environment) is different from the redirect_url specified by the merchant in the transaction request (the address to which the customer will be redirected at the end of the transaction).

  8. Redirect customer to app

    Redirect the customer to the Maya environment or generate the QR on the website, where they can proceed with payment.

    "redirect_url": "https://api.ebanx.com/ws/redirect/execute?hash=5ec27f3b86fa8e318ddcc9727453626aec3989aa2ceccdb7",
    Sandbox Behavior

    When testing in sandbox, a simulator environment will be rendered, allowing merchants to accept or decline the payment, without direct communication of payment with Maya

  9. Customer flow in Maya app

    In this first example, the image is displayed when the merchant redirects the customer from their web browser:

    QRCODE_MAYA

    If the transaction is carried out directly via mobile, the app will be automatically triggered, requesting an OTP validation:

    OTP_MAYA

    After confirming the OTP, the transaction review will be visible:

    REVIEW_PURCHASE_MAYA

    Confirming the payment, the details of the completed transaction will be displayed:

    COMPLETE_PURCHASE_MAYA

  10. Monitor payment for status changes

    Notifications

    Status

    • After receiving a notification, retrieve the payment status.

    • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will automatically update to cancelled (CA).

  11. Congratulations!

    You have successfully integrated Maya.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.


Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: