Maya (Philippines)
Taking Philippine peso payments online and by QR Ph with your own Maya Business account.
Maya (maya.ph) is a Philippine payment provider. This integration is for businesses trading in Philippine pesos — it lets a customer pay by QR Ph at the counter, or online through GCash, their own bank app or the Maya app.
Maya is connected with your own keys, the same way Stripe is: you link your own Maya Business account, and the money lands there. We never hold the funds.
Maya is available only when your company's currency is set to PHP, in Settings → Company profile. Maya's own checkout rejects any other currency outright, so there is nothing to configure on our side beyond getting that one setting right first.
Status today: beta
Every part of this integration is built and verified end-to-end against Maya's sandbox — connecting, the QR Ph counter flow, pay-by-link, refunds and webhooks all work today. It carries a beta label because no production payment has crossed it yet: Maya issues production keys only to a business registered in the Philippines (a DTI or SEC registration), and we are onboarding our first Philippine merchants now. If that could be you, get in touch — we'll walk your shop through it personally, and the label goes to live once the first real peso payment has been proven end to end.
What it does
- At the counter — choose the Maya payment method and the POS shows a QR Ph code on screen. The customer scans it with the Maya app, GCash, or their own bank's app, and pays. The till watches for the payment and finishes the sale by itself.
- On an invoice — if the invoice is in PHP and Maya is connected, the pay-by-link page offers Pay online (Maya / GCash / QR Ph). The customer is sent to Maya's own hosted checkout page and comes back when they are done. See Online payment links.
- Refunds — issued from the suite, from the sale's refund button, exactly like a card refund.
Maya has no cloud API for its card terminals, so an in-store Maya card terminal cannot be connected here — in-store means the QR code, not a paired device. It does not support any currency other than PHP. And your subscription to the suite itself is still billed in one of the subscription currencies, which do not include PHP yet — connecting Maya only changes how your own customers pay you.
Connecting
Go to Settings → Integrations → Maya (owners and admins only) and connect in two stages.
Stage one — the keys. In your Maya Business Manager, find two keys:
- A public key, starting
pk-— this is what creates a payment. - A secret key, starting
sk-— this is what reads a payment's status and issues refunds.
Both are required and they are not interchangeable. The keys also tell us which environment they belong to — Maya issues sandbox and production keys separately, so paste in the pair for the environment you mean to use. We check both keys against Maya before saving; if either one is wrong, nothing is stored. Once saved, the keys are encrypted at rest and are never shown again.
Stage two — the webhook, registered for you. Connecting also registers the three checkout events with Maya automatically, using your own keys, so payments confirm promptly with no dashboard work. The panel still shows the webhook URL, once — keep a copy. Two cases fall back to registering it by hand in your Maya dashboard, and the panel tells you when they apply: Maya allows one endpoint per event, so an event your account already routes to your own system is left untouched rather than overwritten; and if Maya could not be reached during connect, nothing was registered. The URL carries a secret token and is shown only that once; disconnecting removes our registrations, and reconnecting issues and registers a fresh URL.
Maya does not sign its webhooks, so a webhook on its own is never trusted as proof of payment — it is only ever treated as a nudge to go and ask Maya what really happened, using the secret key. That is why a payment is never marked paid on the strength of a webhook, or a returning browser, alone.
Finally, add a payment method that uses Maya at the counter: go to POS → Settings → Payments and set a method's gateway to Maya. Until that step is done, the integration sits connected while nothing at the counter offers it.
At the counter
A Maya checkout expires one hour after it is created. Nothing is charged unless Maya reports that the payment succeeded.
If the cashier cancels while the QR code is on screen, the till stops waiting for it. But if the customer had already paid, that payment still goes through at Maya's end — the suite flags it, records it, and alerts so it can be refunded by hand. Check with the customer before cancelling, and know that a payment that lands after a cancel is never silently dropped.
Refunds
Maya draws a line at midnight, Philippine time, and it changes what a refund is called and how flexible it can be:
- Same day (before midnight, Philippine time) a payment is voided, and a void must be for the full amount.
- From the next day onwards it is a refund, and that is available for 180 days. Beyond 180 days, it has to be arranged with Maya directly.
Refunds are card-not-present, so unlike an EFTPOS terminal refund the customer does not need to be at the counter for one. See Refunds and returns.
Troubleshooting
| What you see | What to check |
|---|---|
| Maya isn't offered as a payment method | Three usual causes: the company's currency isn't PHP (see Settings → Company profile), Maya isn't connected, or no payment method is bound to the Maya gateway in Settings → Payment methods. |
| The customer says they paid, but the sale didn't finish | The till keeps checking with Maya directly, and the webhook is the backup path — give it a moment before doing anything else. A payment that lands after the sale was cancelled is flagged for a manual refund, not lost. |
| Keys rejected on connect | Usually the public and secret keys were swapped, or sandbox keys were pasted in against production (or the reverse). Re-check which of the two starts pk- and which starts sk-, and which environment each was issued for. |