Maya Recurring Integration Guide

Maya Recurring enables merchants to collect subscription or recurring payments directly from a customer's Maya wallet. Customers authorize a recurring payment mandate (or enrollment) during the initial transaction, allowing merchants to perform future debits without requiring manual approval for every payment.

This payment method is widely used in the Philippines for subscription-based services, including streaming platforms, gaming services, digital memberships, and SaaS products. Maya Recurring helps merchants reduce churn by offering a familiar local wallet experience.

This capability is commonly used for SaaS and digital subscriptions, gaming memberships and in-app subscriptions, streaming and entertainment services, e-learning platforms, and utilities and telecom services.

Key Features

Feature	Purpose	Benefit
Enrollment Authorization	Customer enrollment approval.	Enables secure customer consent while eliminating the need for repeated authorization per payment.
Merchant Initiated Charges	Create new charges linked to a previously accepted and valid enrollment.	Simplifies billing automation and reduces friction for subscription-based services.
Subscription Lifecycle Management	Provides the ability to query, cancel, or manage subscription enrollments.	Gives merchants operational control over subscriptions and improves customer account management.
Payment Notifications	Sends asynchronous updates whenever payment status changes.	Ensures merchants receive real-time transaction updates for reconciliation and order fulfillment.

How it works

Subscription Enrollment - Merchant registers the subscription and redirects the user to authorize it within the Maya app.
Recurring Payment Request - Merchant triggers a recurring charge linked to the enrollment when required.
Payment Confirmation - EBANX sends payment status notifications to the merchant.

Maya has a minimum amount limit of 1 PHP and a maximum limit between 50,000 and 100,000, depending on the type of wallet.

Requirements

API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.

Instructions

Follow the steps below.

Select your environment

Select the appropriate environment for your integration. Use the sandbox environment for testing or the production environment for live transactions.
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.
SandboxProduction
https://sandbox.ebanx.com/ws/direct

Define enrollment parameters

To start the recurring payment process, enroll the subscription using the /ws/direct endpoint. This step involves collecting essential customer details and subscription parameters to establish the recurring billing agreement.

Users will be required to complete 2FA/login to accept this enrollment in their app. Once the process is complete, the customer will be enrolled for the recurring payment cycle.

Basic parameters

Parameter	Requirement	Description
`integration_key`	Required	Your integration key.
`operation`	Required	Must be `request`.

Enrollment parameters

Parameter	Requirement	Description
`payment.name`	Required	Full name of the payer.
`payment.email`	Required	Customer email.
`payment.phone_number`	Required	Customer phone number.
`payment.country`	Required	Set to `ph` for Philippines.
`payment.payment_type_code`	Required	Must be `paymaya-recurring`.
`payment.merchant_payment_code`	Required	Unique code for the payment.
`payment.currency_code`	Required	Set to `PHP`.
`payment.amount_total`	Required	Payment amount.
`payment.enrollment.merchant_enrollment_code`	Required	Unique identifier for the enrollment.
`payment.enrollment.back_urls.success`	Required	URL to redirect on success.
`payment.enrollment.back_urls.failure`	Required	URL to redirect on failure.
`payment.enrollment.subscription.subscription_name`	Required	Subscription description (1-35 characters).
`payment.enrollment.subscription.expiration_date`	Required	Expiration date in `YYYY-MM-DD` format (must be a future date).
`payment.enrollment.subscription.frequency`	Required	Set to `ondemand`.

Enrollment request

Enroll the customer in Maya Recurring using the /ws/direct endpoint.

Sample request

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
  "integration_key": "{{integration_key}}",
  "operation": "request",
  "payment": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "country": "ph",
    "phone_number": "5555555555",
    "payment_type_code": "paymaya-recurring",
    "merchant_payment_code": "{{merchant_payment_code}}",
    "currency_code": "PHP",
    "amount_total": 1,
    "enrollment": {
      "merchant_enrollment_code": "{{unique_enrollment_code}}",
      "back_urls": {
        "success": "https://your-success-url.com",
        "failure": "https://your-failure-url.com"
      },
      "subscription": {
        "subscription_name": "{{description}}",
        "expiration_date": "{{YYYY-MM-DD}}",
        "frequency": "ondemand"
      }
    }
  }
}'

Enrollment response

A successful request will return a JSON response like the one below:

{
  "payment": {
    "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
    "country": "ph",
    "merchant_payment_code": "{{merchant_payment_code}}",
    "order_number": null,
    "status": "PE",
    "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "confirm_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "transfer_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "amount_br": "99.85",
    "amount_ext": "99.85",
    "amount_iof": "1",
    "currency_rate": "1.0000",
    "currency_ext": "PHP",
    "due_date": "{{YYYY-MM-DD}}",
    "instalments": "1",
    "payment_type_code": "paymaya-recurring",
    "redirect_url": "https://merchant.example.com/callback",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
      "email": "john.doe@example.com",
      "name": "John Doe"
    },
    "currency_ext_base": "PHP"
  },
  "status": "SUCCESS",
  "redirect_url": "https://merchant.example.com/callback"
}

On-demand frequency provides merchants with the flexibility to initiate charges at any time within the subscription validity period, without being restricted to a fixed billing schedule.
The enrollment is automatically created and accepted upon the initial payment confirmation.

Save the merchant_enrollment_code for subsequent payment requests.

Confirm the enrollment

As soon as the payment is confirmed by the customer in their e-wallet app, the enrollment status is modified from pending to accepted, and a Status Update Notification is sent to the URL defined in your merchant configuration.
Notification example:
```
operation=enrollment_status_change&notification_type=update&merchant_enrollment_code={{merchant_enrollment_code}}
```
To ensure efficient and compliant interactions, EBANX allows merchants to confirm a user's enrollment status before sending multiple notifications or processing transactions.
- Learn more about Enrollment Notifications
Query enrollment status

Before requesting any payments, call the /ws/userenrollments/query endpoint using the merchant_enrollment_code to get the latest status of the enrollment.

Sample request
```
curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/userenrollments/query' \
  --header 'Content-Type: application/json' \
  --data '{
  "integration_key": "{{integration_key}}",
  "payment_type_code": "paymaya-recurring",
  "enrollment": {
    "country": "ph",
    "merchant_enrollment_code": "{{unique_enrollment_code}}"
  }
}'
```
Sample response
```
{
  "status": "SUCCESS",
  "payment_type": "paymaya-recurring",
  "enrollment": {
    "status": "accepted"
  }
}
```
The response will indicate one of the following values for enrollment status:
- accepted - Enrollment approved by the customer.
- not accepted - Enrollment rejected by the customer.
- pending - Enrollment awaiting customer action.
- expired - Enrollment expired.
- not_found - Enrollment not found.
- revoked - Enrollment cancelled.
If your enrollment has the status accepted, you can start requesting recurring payments.

Define payment parameters

After the enrollment is accepted, you can create recurring payment requests. The payment follows the usual standards of /ws/direct payment requests, with the addition of specific parameters related to enrollment.

Parameter	Requirement	Description
`integration_key`	Required	Your EBANX integration key.
`operation`	Required	Set to `request`.
`payment.name`	Required	Full name of the payer.
`payment.email`	Required	Customer email.
`payment.phone_number`	Required	Customer contact number.
`payment.country`	Required	Set to `ph` for Philippines.
`payment.payment_type_code`	Required	Set to `paymaya-recurring`.
`payment.merchant_payment_code`	Required	Unique code for the payment.
`payment.currency_code`	Required	Set to `PHP`.
`payment.amount_total`	Required	Payment amount.
`payment.enrollment.merchant_enrollment_code`	Required	Unique identifier associated with the enrollment.

Create payment request

Sample request

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
  "integration_key": "{{integration_key}}",
  "operation": "request",
  "payment": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "country": "ph",
    "phone_number": "5555555555",
    "payment_type_code": "paymaya-recurring",
    "merchant_payment_code": "{{merchant_payment_code}}",
    "currency_code": "PHP",
    "amount_total": 99.85,
    "enrollment": {
      "merchant_enrollment_code": "{{unique_enrollment_code}}"
    }
  }
}'

The merchant_enrollment_code associated with the enrollment is required for every subsequent charge.

Payment response

A successful request will return a JSON response like the one below. The Maya Recurring payment will have a pending (PE) status until confirmed.

{
  "payment": {
    "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
    "country": "ph",
    "merchant_payment_code": "{{merchant_payment_code}}",
    "order_number": null,
    "status": "PE",
    "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "confirm_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "transfer_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "amount_br": "99.85",
    "amount_ext": "99.85",
    "amount_iof": "1",
    "currency_rate": "1.0000",
    "currency_ext": "PHP",
    "due_date": "{{YYYY-MM-DD}}",
    "instalments": "1",
    "payment_type_code": "paymaya-recurring",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
      "email": "john.doe@example.com",
      "name": "John Doe"
    },
    "currency_ext_base": "PHP"
  },
  "status": "SUCCESS"
}

EBANX does not offer a recurrent billing engine. Merchants are required to maintain their own charge schedules.

Monitor payment for status changes

Notifications
- EBANX will send a notification whenever a payment status changes.
- Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
- Learn more about Payment Notifications
Status
- After receiving a notification that the status has changed, retrieve the payment status.
- When a payment is confirmed, the status will change from pending (PE) to confirmed (CO).
- Learn more about Retrieving Payment Status
Congratulations!

You have successfully integrated Maya Recurring.
For more information, refer to the
Direct API reference guide

Error Scenarios

This section outlines potential errors that may occur during enrollment creation and recurring payment requests in Maya Recurring. These are synchronous error scenarios triggered by EBANX, in accordance with the product business rules and required fields.

EBANX Code	EBANX Message	Details
`BP-UE-18`	Field enrollment.subscription.expiration_date must be a future date	Incorrect expiration date.
`BP-UE-03`	Field enrollment.email or enrollment.phone_number is required	Mandatory field is missing.
`BP-UE-30`	The field subscription_name size must be between 1 and 35 characters.	Subscription name character limit exceeded.
`BP-UE-23`	Field enrollment.subscription.frequency is required	Frequency field is blank.

See all enrollment error codes

Cancel Enrollment

Merchants can revoke an active subscription by sending a cancel request with the merchant enrollment code.

Ensure enrollment status is Pending or Accepted

You can only cancel an enrollment if its status is pending or accepted. You can check the status using the /ws/userenrollments/query endpoint referencing its merchant_enrollment_code.

Sample request

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/userenrollments/query' \
  --header 'Content-Type: application/json' \
  --data '{
  "integration_key": "{{integration_key}}",
  "payment_type_code": "paymaya-recurring",
  "enrollment": {
    "country": "ph",
    "merchant_enrollment_code": "{{unique_enrollment_code}}"
  }
}'

Sample response

{
  "status": "SUCCESS",
  "payment_type": "paymaya-recurring",
  "enrollment": {
    "status": "accepted"
  }
}

Enrollments with a status of accepted or pending are eligible for cancellation. Other possible enrollment statuses include expired, not_found, and revoked, none of which can be cancelled.

Cancel the enrollment

To cancel an enrollment, call the /ws/userenrollment endpoint (from your server) with the following required fields:

Parameter	Requirement	Description
`integration_key`	Required	Your unique and secret integration key.
`operation`	Required	Must be `cancel`.
`payment_type_code`	Required	Must be `paymaya-recurring`.
`enrollment.country`	Required	Must be `ph`.
`enrollment.merchant_enrollment_code`	Required	The unique enrollment identifier.

Sample request

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/userenrollment' \
  --header 'Content-Type: application/json' \
  --data '{
  "integration_key": "{{integration_key}}",
  "operation": "cancel",
  "payment_type_code": "paymaya-recurring",
  "enrollment": {
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "country": "ph"
  }
}'

Sample response

A successful request will return a JSON response with a status of revoked.

{
  "status": "SUCCESS",
  "payment_type": "paymaya-recurring",
  "enrollment": {
    "status": "revoked"
  }
}

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explore

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explore

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explore

Still need help?

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

Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.

Maya Recurring

Key Features​

How it works​

Requirements​

Instructions​

Select your environment​

Define enrollment parameters​

Basic parameters​

Enrollment parameters​

Enrollment request​

Enrollment response​

Confirm the enrollment​

Query enrollment status​

Define payment parameters​

Create payment request​

Payment response​

Monitor payment for status changes​

Congratulations!​

Error Scenarios​

Cancel Enrollment​

Ensure enrollment status is Pending or Accepted​

Cancel the enrollment​

Resources​

API Reference

Mock Customer Data

Error Codes

Still need help?

Key Features

How it works

Requirements

Instructions

Select your environment

Define enrollment parameters

Basic parameters

Enrollment parameters

Enrollment request

Enrollment response

Confirm the enrollment

Query enrollment status

Define payment parameters

Create payment request

Payment response

Monitor payment for status changes

Congratulations!

Error Scenarios

Cancel Enrollment

Ensure enrollment status is Pending or Accepted

Cancel the enrollment

Resources