Skip to main content
All API requests require two headers for authentication. Both must be included in every request.

​
Required headers

Every API request must include both of these headers: 
curl https://api.maash.io/checkout/sessions \
  -H "x-api-key: mk_live_1234567890abcdef1234567890abcdef" \
  -H "x-maash-user-type: checkout"
HeaderValueDescription
x-api-keymk_live_... or mk_test_...Your merchant API key
x-maash-user-typecheckoutIdentifies the request as a checkout API call

​
API key authentication

Use API keys for all server-side API calls. Include your key in the x-api-key header. 
curl https://api.maash.io/checkout/sessions \
  -H "x-api-key: mk_live_1234567890abcdef1234567890abcdef" \
  -H "x-maash-user-type: checkout"

​
Key formats

PrefixEnvironmentDescription
mk_live_ProductionProcesses real payments on mainnet
mk_test_TestSimulates payments without real funds

​
Security best practices

Never expose your API key in client-side code, mobile apps, or public repositories.
Store API keys in environment variables or a secrets manager. Never hardcode keys in source files.
Rotate keys periodically from the Maash Dashboard. If a key is compromised, revoke it immediately and generate a new one.
Use test keys (mk_test_) during development and staging. Only switch to live keys (mk_live_) when deploying to production.
Restrict API key access to specific IP addresses when possible to limit exposure.

​
How keys are stored

API keys are hashed with SHA-256 before storage. Maash never stores your raw API key. If you lose your key, generate a new one from the dashboard.

​
Session tokens

When you create a checkout session, the response includes a checkout_url_with_token that contains an embedded session token. This token authenticates requests from the hosted checkout page. 
https://pay.maash.io/checkout/cs_01ARZ3...?token=eyJhbGciOi...
Session tokens are HMAC-signed JWTs that contain the session_id and expire when the checkout session expires. You do not need to manage session tokens directly — the hosted checkout page handles this automatically.

​
Webhook signature verification

Maash signs every webhook delivery with HMAC-SHA256. Verify the signature to confirm that a webhook came from Maash and was not tampered with. See the Webhooks guide for implementation details.

​
Authentication by endpoint

All endpoints require the x-api-key and x-maash-user-type: checkout headers.
EndpointMethodHeaders required
GET /checkout/tokensGETx-api-key, x-maash-user-type: checkout
GET /checkout/quoteGETx-api-key, x-maash-user-type: checkout
POST /checkout/sessionsPOSTx-api-key, x-maash-user-type: checkout
GET /checkout/sessions/{id}GETx-api-key, x-maash-user-type: checkout
POST /checkout/sessions/select-paymentPOSTx-api-key, x-maash-user-type: checkout

​
Error responses

If authentication fails, the API returns one of these responses:
401 Unauthorized (missing API key)
{
  "error": "Missing or invalid API key"
}
401 Unauthorized (missing user type)
{
  "error": "Missing x-maash-user-type header"
}
403 Forbidden
{
  "error": "Access denied"
}

​
Next steps

Quickstart

Create your first checkout session using your API key.

Webhooks

Learn how to verify webhook signatures with HMAC-SHA256.

Error handling

Handle authentication errors and other API error responses.

API Reference

See which endpoints require authentication.