Skip to main content
Prerequisites: Before you start, make sure you have: - A Maash merchant account and API key (format: mk_live_* or mk_test_*) - A webhook endpoint URL to receive payment notifications - A Solana wallet address for settlement

​
Get started

1

Get your API key

Sign in to the Maash Dashboard and navigate to Settings > API Keys. Copy your API key. Test keys start with mk_test_ and live keys start with mk_live_.
Keep your API key secure. Never expose it in client-side code or public repositories.
2

Create a checkout session

Make a POST request to create a new checkout session:
curl -X POST https://api.maash.io/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: mk_test_your_api_key_here" \
  -H "x-maash-user-type: checkout" \
  -d '{
    "merchant_id": "mer_your_merchant_id",
    "transaction_id": "order_12345",
    "amount_usd": 25.00
  }'
3

Redirect your customer

The API returns a checkout_url_with_token. Redirect your customer to this URL to complete payment.
Want to keep customers on your site instead of redirecting? Use the iframe integration to embed the checkout widget directly in your page.
Response
{
  "data": {
    "session_id": "cs_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "checkout_url": "https://pay.maash.io/checkout/cs_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "checkout_url_with_token": "https://pay.maash.io/checkout/cs_01ARZ3NDEKTSV4RRFFQ69G5FAV?token=eyJ...",
    "expires_at": "2024-02-02T15:25:00Z",
    "created_at": "2024-01-31T15:25:00Z"
  }
}
Use the checkout_url_with_token for redirecting customers. This URL contains a secure session token for authentication.Your customer selects a token and chain, scans the QR code or clicks the payment link, and sends the payment from their wallet.
4

Handle the webhook

When the payment completes, Maash sends a POST request to your webhook_url:
Webhook payload
{
  "event": "payment.completed",
  "payment_id": "pay_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "session_id": "cs_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "transaction_id": "order_12345",
  "status": "completed",
  "amount": {
    "usd_requested": 25.00,
    "token_expected": "25.025000",
    "token_received": "25.025000",
    "token_symbol": "USDC",
    "chain": "polygon"
  },
  "settlement": {
    "amount_usdc": "25.000000",
    "chain": "solana",
    "settled_at": "2024-01-31T15:30:00Z"
  },
  "metadata": {},
  "timestamp": "2024-01-31T15:30:00Z"
}
Verify the webhook signature before processing. See the Webhooks guide for details.
5

Confirm the payment

You can also poll the session status by calling:
curl https://api.maash.io/checkout/sessions/cs_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  -H "x-api-key: mk_test_your_api_key_here" \
  -H "x-maash-user-type: checkout"

​
Next steps

Iframe integration

Embed the checkout widget directly in your page instead of redirecting.

Webhooks

Set up webhook verification and handle all event types.

Checkout flow

Understand the full payment lifecycle.

Supported chains

View all tokens, chains, and confirmation times.