canonical: https://jentic.com/apis/maya.ph/maya

# Maya Ph Maya API

Jentic publishes the only available OpenAPI specification for Maya API, keeping it validated and agent-ready. Maya is the Philippines' digital financial services platform, and its API exposes checkout, direct payments, vault tokenization, payment links, remittances, transfers, and bill payments. Agents can build full Filipino-market checkout flows, accept card and wallet payments, store payment instruments for recurring use, and move money across the Maya network. The 11 operations cover the end-to-end payment lifecycle from intent creation to refund.

## For AI agents

Process payments, tokenize cards, generate payment links, and run remittances and transfers on Maya's Philippines payment platform.

## Scope

Does not handle accounting, tax filing, or KYC document collection - use for Philippines payment processing, vaulting, and money movement only.

## Capabilities

- Create hosted checkout sessions for one-time card and wallet payments
- Charge a saved card token directly without a hosted page
- Tokenize a card into the Maya vault for repeat charges
- Generate shareable payment links with custom amounts and metadata
- Initiate remittances to Philippine bank accounts and Maya wallets
- Run peer-to-peer or merchant-to-customer transfers
- Pay billers across the Maya biller network programmatically

## Use cases

### Philippines E-Commerce Checkout

Accept card and Maya wallet payments on a Philippines storefront using Maya's hosted checkout. The `/v1/checkout` endpoint creates a session with the cart total, currency, and a redirect URL, and the buyer completes payment on a Maya-hosted page that handles 3D Secure and wallet selection. Settlement clears to the merchant's Maya merchant account in PHP, with webhooks confirming payment success.

Example prompt: Create a checkout session for PHP 1,499 with description 'Order #12345', a success URL of /thanks, and a failure URL of /retry, then return the redirect URL to the caller.

### Card Vaulting for Subscriptions

Store a customer's card once via Maya's vault and charge it on each renewal cycle without re-prompting for card details. The `/v1/vault/tokens` endpoint creates a token bound to a payment instrument, and subsequent `/v1/payments` calls reference the token to execute the charge. This is the standard pattern for SaaS, telco, and streaming subscriptions targeting Filipino customers.

Example prompt: Create a vault token for the supplied card details, then immediately charge that token PHP 299 with description 'Monthly subscription - June'.

### Payment Link Distribution Over Chat

Send shoppers a tokenised, single-use payment link via Viber, Messenger, or SMS so they can pay without leaving the conversation. The `/v1/payment-links` endpoint accepts amount, currency, and metadata and returns a short URL that opens the Maya hosted page. Conversational commerce teams use this pattern to convert chat enquiries into completed orders without building a full storefront.

Example prompt: Generate a payment link for PHP 750, expiring in 24 hours, with metadata.order_id=ORD-987, then return the short URL.

### AI Agent for Payment Reconciliation

Build an agent that reconciles Maya payment status into an internal order ledger by polling `/v1/payments/{paymentId}` for pending records, marking matched orders as paid, and refunding stuck transactions when a duplicate is detected. The agent searches Jentic for the relevant Maya operations, loads schemas, and executes calls using vault credentials. This removes hours of manual reconciliation per day for high-volume merchants.

Example prompt: For each order in the 'pending' table older than 30 minutes, call GET `/v1/payments/{paymentId}`, update the order status to match, and refund duplicates by calling the refund operation with the original paymentId.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/checkout` | Create a hosted checkout session |
| POST | `/v1/payments` | Create a direct payment |
| GET | `/v1/payments/{paymentId}` | Retrieve a payment by id |
| POST | `/v1/vault/tokens` | Create a vault token from card details |
| POST | `/v1/payment-links` | Generate a shareable payment link |
| POST | `/v1/remittances` | Initiate a remittance to a bank account |
| POST | `/v1/transfers` | Send a peer-to-peer or merchant transfer |
| POST | `/v1/bills/payments` | Pay a biller programmatically |

## Key resources

- **Checkout** — Hosted checkout sessions for card and wallet payments
- **Payments** — Direct payment creation and lookup
- **Vault Tokens** — Tokenized card storage for repeat charges
- **Payment Links** — Shareable single-use payment URLs
- **Remittances** — Money movement to Philippine bank accounts
- **Transfers** — Peer-to-peer and merchant transfers
- **Bill Payments** — Programmatic bill payment across Maya billers

## Why Jentic

- **Setup:** Wiring the Maya API by hand means selecting the correct public or secret key per call, encoding it as HTTP Basic auth, choosing the production or sandbox host, and mapping the money-movement operations yourself. Through Jentic you install once, import the Maya API from the API Directory, store the public and secret keys once, and your agent calls it.
- **Permission scoping:** Maya's payment, transfer, and remittance targets travel in the request body rather than being pinned by a resource id in the URL path, so you limit the agent to the operations it needs, such as creating a payment link or checkout. It calls only the operations you allow, so money movement like transfers or remittances is not included unless you add it.
- **Credential handling:** Your Maya public and secret keys are stored once, encrypted, by your own Jentic One instance, which selects the right key per operation and encodes it as a Basic auth header at execution time. The secret key never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Maya payment link', and Jentic returns the matching Maya operation with its input schema so the agent calls the right endpoint without browsing developers.maya.ph.

## Related APIs

- **PayMongo** — Philippines-focused payment platform with similar checkout and tokenisation features
- **Stripe** — Global payments platform with broader currency and method coverage
- **Square** — Payments platform with strong in-person and SMB tooling

## FAQ

### Why is there no official OpenAPI spec for Maya API?

Maya does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Maya API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Maya API use?

Maya uses HTTP Basic authentication where the merchant's API key is passed as the username. Public keys are used for client-side calls (checkout) and secret keys for server-side calls (vault, refunds). Through Jentic, both keys are stored in your Jentic One instance and selected per-operation, so the secret key never enters the agent's context.

### Can I tokenize cards with the Maya API?

Yes. POST `/v1/vault/tokens` accepts card details and returns a token that can be charged via `/v1/payments` without re-entering card data. This is the basis for subscription and one-click checkout flows on the Maya platform.

### What are the rate limits for the Maya API?

Maya enforces per-merchant rate limits documented at developers.maya.ph and varies by environment (sandbox is more permissive than production). Responses use 429 status codes with retry guidance when limits are hit; agents should implement exponential back-off for batch reconciliation jobs.

### How do I create a checkout session with the Maya API through Jentic?

Search Jentic for 'create a Maya checkout session', load the schema for POST `/v1/checkout`, and execute with totalAmount, requestReferenceNumber, and redirectUrl. Jentic attaches the public-key Basic auth header automatically and returns the hosted checkout URL.

### Does the Maya API support refunds?

Yes. Refunds are issued against an existing paymentId via the payments resource. Partial refunds are supported by specifying the refund amount; the API returns a refund record with its own status that can be polled for settlement confirmation.

### Can I send remittances with the Maya API?

Yes. POST `/v1/remittances` initiates a transfer to a Philippine bank account or Maya wallet, and POST `/v1/transfers` handles peer-to-peer and merchant-to-customer payouts. Both require server-side secret-key authentication and are subject to KYC and AML checks on the Maya side.

### Can I limit what my agent is allowed to do with the Maya API?

Yes. Because you run Jentic One yourself, your own rules decide which Maya operations and keys the agent may use, and it calls only the operations you allow. Since Maya's payment, transfer, and remittance targets travel in the request body rather than a resource id in the URL, you scope access at the operation level, for example allowing create-checkout and payment-link calls while excluding money movement like transfers and remittances. You can also keep the public key available for checkout while withholding the secret key that server-side operations require.