How it works

Maytes lets your customers pay now or split the cost with friends — without you building any of the payment or splitting logic. You add a checkout to your online store, your customer pays in the Maytes window, and you capture the payment to finalise the order.

Every integration starts the same way: your backend creates a checkout with Maytes (the order's line items, total, and your redirect URLs), and the customer pays in the Maytes-hosted window. From there, the checkout follows the authorize, then capture pattern (the same shape as a card pre-auth): the customer's funds are first held, and money only moves when you capture.

One order, two payments

Behind a split, Maytes runs two transactions on the paying customer's (the lead's) card:

1. The lead's own share — charged when you capture the checkout.
2. The mates' shares — a second authorization held on the lead's card. The mates then have 48 hours to pay their shares to Maytes; whatever is still unpaid when the window closes is captured from that authorization, so the lead covers any mate who didn't pay in time.

You never see or manage the second transaction — it's between Maytes and your customer. What it means for you: your order total is fully secured from the moment you capture, whether or not the mates ever pay. The splitting, reminders, and collection are Maytes' problem, not yours.

Keep this in mind for the choice below: after paying, the customer has one more valuable step inside Maytes — telling us who their mates are.

Choosing your integration flow

There are two ways to integrate Maytes, named for how your backend learns the payment is authorized and ready to capture:

• Webhook flow (recommended) — Maytes notifies your backend directly, with a signed checkout.authorized webhook, the moment the customer's payment is authorized. You capture from that webhook handler, server-to-server, while the customer stays inside the Maytes window.
• Redirect flow (legacy) — there is no direct notification. Your signal is the customer's browser landing back on your return_url after they pay, and your success-page handler does the capture.

Side by side:

	Webhook flow (recommended)	Redirect flow (legacy)
You learn the checkout is authorized via	checkout.authorized webhook to your backend	Customer landing on your return_url
You capture from	Your webhook handler, immediately	Your success-page handler
Customer lands on return_url	After capture — and after adding their mates, so possibly minutes later, or not at all if they close the window	Right after authorizing, before capture — skipping the add-mates step
Fulfilment trigger	Capture success	Capture success (called from the success page)
Customer's split experience	Adds mates' details in the Maytes flow, right after paying	Interrupted — Maytes follows up by SMS to collect mates' details later

New integrations should use the webhook flow. The redirect flow remains supported for existing integrations.

The webhook flow (recommended)

The webhook flow is preferred because it gives the customer the best experience end-to-end: the order is validated and captured within seconds of payment, and the customer stays in the Maytes flow to add their mates' details — on the web, or in the Maytes app where their contacts are a tap away. If any mate's information is missing, Maytes follows up with the customer by SMS. Only after that step does the customer return to your return_url.

1. Your customer chooses to pay with Maytes on your online store.
2. Your backend creates a checkout with Maytes and gets a checkout_url.
3. The customer authenticates and pays in the Maytes checkout window. Funds are authorized (held), not yet taken.
4. Maytes sends a checkout.authorized webhook to your backend. Your customer sees a payment-processing screen in the Maytes window while your handler runs.
5. Your handler captures the checkout (or cancels it if you can't fulfil). Capture is synchronous — when the call returns 200, the money has moved.
6. The customer continues inside Maytes — adding the mates who'll share the cost — and finally lands on your return_url.

Fulfil on capture, not on return_url

In the webhook flow, capture success is your fulfilment trigger. The customer may spend several minutes in the split step after you've captured — or close the window entirely and never land on return_url. Their payment stands either way. Treat the return_url landing as a courtesy confirmation page, never as the signal that the order is paid.

Your webhook handler should capture immediately — your customer is watching a processing screen while it runs. If you can't fulfil the order (say a final stock check fails), call cancel instead so the hold is released and the customer isn't left waiting. See Webhooks for the full handler recipe, signature verification, and delivery semantics.

The redirect flow (legacy)

If your integration predates webhooks, the flow you built still works — but it's not recommended for new integrations. The customer returns to your website immediately after the payment step, missing the opportunity to add their mates' details while they're still in the flow. Maytes follows up by SMS with a link back into the add-mates flow, but a later, out-of-context message is easy to miss and can create confusion.

The mechanics:

1. Your backend creates a checkout and opens checkout_url for the customer.
2. The customer authorizes in the Maytes window and is redirected to your return_url.
3. Your success-page handler captures the checkout server-to-server.

The trade-off: the customer is bounced back to your site while the payment is only authorized, and your success page is a single point of failure — if the customer never lands on it (closed tab, dropped connection), nothing captures the payment and the authorization is auto-voided after 2 minutes.

Migrating? You can run both flows at the same time safely — capture is idempotent, so a webhook capture and a success-page capture racing each other resolve cleanly. Write your success page defensively: GET the checkout on landing and branch on status — captured means the webhook already did the work (just show confirmation); authorized means you're on the legacy path (capture now).

Amounts are in minor units

Every amount in the API is an integer in the currency's minor unit — cents for AUD. 4500 means AUD 45.00. Never send decimals. All examples in these docs use AUD.

Before you begin

New to Maytes? Onboarding covers getting your merchant account, credentials, and Stripe payout account set up. From the Maytes merchant portal you get:

• OAuth client credentials (client_id + client_secret) — a separate pair for the sandbox and production environments.
• Your webhook subscription — endpoint URL, event types, and the signing secret used to verify deliveries. (Webhook flow only — the redirect flow doesn't need one.)
• Your merchant account configuration, connected to your payout account.

Keep your client_secret and webhook signing secret on your server — never expose either in browser code.

Next

• Quickstart — a working webhook-flow integration, step by step.
• Webhooks — events, signature verification, and delivery semantics.
• Authentication — getting and using access tokens.