Security

Keep every secret on your server. The requirements below protect payment and customer data.

Card data never touches you

Don't collect card details on behalf of the checkout. Customers enter them in the Maytes-hosted checkout window, and our payment provider processes them. Card numbers never pass through your servers, frontend, or the Maytes merchant API, so integrating Maytes doesn't put card data in your PCI scope. There is no API for submitting card details.

Your three secrets

Secret	Used for	If it leaks
client_secret (per environment)	Minting OAuth access tokens	An attacker can act as your merchant account: create, capture, cancel, and refund.
Webhook signing secret (per subscription)	Verifying that deliveries came from Maytes	An attacker can forge "authorized" events at your endpoint.
OAuth access tokens	Every merchant API call	Same power as the credentials, until expiry.

Rules for all three:

• Server-side only. Never put them in browser or mobile code, a repository, or client-accessible configuration. The Checkout Button calls your backend, which calls Maytes.
• Store them in a secret manager or environment variables injected at deploy time.
• Separate them by environment. Test and production use independent credentials and webhook secrets, so a test leak doesn't expose production.
• Don't log them. Redact authorization headers and token responses from request logging.

Verify every webhook delivery

Verify the X-Maytes-Signature header on every webhook using the raw body, constant-time comparison, every v1 entry, and a timestamp tolerance (we recommend 5 minutes). Reject failures with a 4xx and don't process the payload. These checks prevent forged or replayed requests to your guessable endpoint URL. Use the SDK examples in Webhooks → Verify the signature.

Rotate secrets without downtime

• Webhook signing secret: follow the rotation runbook. The built-in 2-hour dual-signature grace window supports scheduled or staff-departure rotations without dropping deliveries. For a suspected leak, set revoke_previous=true to revoke the old secret immediately.
• OAuth client secret: rotate it from the portal's API credentials page. Rotation is immediate, with no grace window, so deploy the new value at once. See Authentication.

Trust server-side state, not the browser

Before fulfilling an order, verify server-side state. Browser state, including arrival at your return_url, can be forged.

• Fulfill on your own capture success (a call your server made with its own credentials) — never on the redirect.
• Use the capture assertions (expected_total_amount, currency, merchant_order_id) to prevent a mixed-up ID from capturing the wrong order.

Handle customer data minimally

Send the optional customer_data block on create only when you have and need the customer's name, email, or mobile. Don't invent placeholder values. Treat this information as personal data under your privacy obligations. Maytes encrypts it at rest and uses it to pre-fill the customer's checkout experience.

Transport

Use HTTPS for your webhook endpoint. All Maytes endpoints are also HTTPS-only. Webhook signatures provide authenticity and integrity; TLS provides confidentiality in transit.

What's next

• Webhooks — signature verification and secret rotation in full.
• Authentication — the OAuth token lifecycle.
• Sandbox environment — including the signature-rejection and duplicate-delivery checks in the go-live list.