Documentation

Appearance

How it works ​

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

Every integration starts with your backend creating a checkout. The request includes the order's line items, total, and redirect URLs. The customer then pays in the Maytes-hosted window.

The checkout follows an authorize, then capture pattern, like a card pre-authorization. Authorization holds the customer's funds; capture moves the money.

One order, two payments ​

For a split, Maytes runs two transactions on the customer's card. This customer is the lead:

  1. The lead's own share — charged when you capture the checkout.
  2. The mates' shares — held as a second authorization on the lead's card. Mates have 48 hours to pay Maytes. When the window closes, Maytes captures any unpaid amount from that authorization, so the lead covers mates who did not pay in time.

You do not see or manage the second transaction; it is between Maytes and the customer. Your full order total is secured when you capture, whether or not the mates pay. Maytes handles splitting, reminders, and collection.

After paying, the customer stays in Maytes to add their mates, then returns to your site.

The webhook flow ​

Maytes sends your backend a signed checkout.authorized webhook as soon as the payment is authorized. Your webhook handler captures server-to-server while the customer remains in the Maytes window.

The webhook flow validates and captures the order within seconds of payment. The customer stays in Maytes to add mates on the web or in the Maytes app, where they can select contacts. If any details are missing, Maytes follows up by SMS. The customer reaches your return_url only after this step.

  1. The customer chooses Maytes in 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 your backend a checkout.authorized webhook. The customer sees a payment-processing screen while your handler runs.
  5. Your handler captures the checkout, or cancels it if you cannot fulfill. Capture is synchronous: when the call returns 200, the money has moved.
  6. The customer adds the mates who will share the cost, then lands on your return_url.

Fulfill on capture, not on return_url

In the webhook flow, capture success is your fulfillment trigger. After capture, the customer may spend several minutes adding mates or close the window without reaching return_url. The payment remains valid. Use return_url only as a confirmation page, never as proof that the order is paid.

Capture immediately from the webhook handler because the customer is waiting on a processing screen. If you cannot fulfill the order, for example because a final stock check fails, call cancel to release the hold. See Webhooks for the full handler, signature verification, and delivery semantics.

Amounts are in minor units ​

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

Before you begin ​

Onboarding covers setting up your merchant account, credentials, and Stripe payout account. The Maytes merchant portal provides:

  • 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.
  • 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.