Use test mode to build and verify your integration without processing real payments.
Test vs. live mode Feature Test mode Live mode API key prefix mk_test_mk_live_Real blockchain transactions No Yes Webhook delivery Yes Yes Settlement Simulated Real USDC on Solana Rate limits Same Same
Test mode behaves identically to live mode except that no real funds are transferred. All API responses, webhook payloads, and error formats are the same.
Getting test credentials
Navigate to API Keys
Go to Settings > API Keys .
Copy your test key
Copy your test API key (starts with mk_test_).
Creating a test checkout session Create a checkout session the same way you would in production:
curl -X POST https://api.maash.io/checkout/sessions \ -H "Content-Type: application/json" \ -H "x-api-key: mk_test_your_test_key" \ -H "x-maash-user-type: checkout" \ -d '{ "merchant_id": "mer_your_merchant_id", "transaction_id": "test_order_001", "amount_usd": 10.00 }'
Testing webhooks locally Use a tunneling tool to expose your local server for webhook testing:
# Start your local server on port 3000 ngrok http 3000 # Use the generated URL as your webhook_url # Example: https://abc123.ngrok.io/webhooks/maash
Verifying webhook signatures in test mode Webhook signatures work the same way in test and live modes. Use your test webhook secret to verify signatures during development:
import crypto from "crypto" ; function verifySignature ( req , secret ) { const signature = req . headers [ "x-maash-signature" ]; const timestamp = req . headers [ "x-maash-timestamp" ]; const body = JSON . stringify ( req . body ); const expected = crypto . createHmac ( "sha256" , secret ) . update ( ` ${ timestamp } . ${ body } ` ) . digest ( "hex" ); return crypto . timingSafeEqual ( Buffer . from ( signature ), Buffer . from ( expected )); }
Pre-launch testing checklist Before going live, verify the following:
Create checkout sessions
Confirm that POST /checkout/sessions returns a valid checkout_url and
session_id.
Load the checkout page
Open the checkout_url in a browser and verify that your merchant name and
amount display correctly.
Select a payment method
Select a token and chain on the checkout page. Verify that a wallet address
and QR code are displayed.
Receive webhooks
Confirm that your webhook endpoint receives events and returns a 200
response.
Verify webhook signatures
Validate the X-Maash-Signature header on every webhook delivery.
Handle all event types
Test your handler for each event: payment.completed, payment.expired,
payment.underpaid, payment.overpaid, and payment.failed.
Check idempotency
Verify that your webhook handler processes each event only once using the
X-Maash-Idempotency-Key.
Test error responses
Send invalid requests and confirm that your integration handles 400,
401, 404, and 410 responses gracefully.
Going live When your integration passes all tests:
Switch to live API key
Replace your test API key (mk_test_) with your live API key (mk_live_).
Update webhook URL
Update your webhook_url to your production endpoint.
Verify HTTPS
Confirm that your production server uses HTTPS for all endpoints.
Confirm settlement wallet
Double-check your settlement wallet address in the dashboard.
Double-check your settlement wallet address before going live. Payments sent
to the wrong address cannot be recovered.
Next steps
Quickstart Review the quickstart guide for your first live integration.
Webhooks Set up production webhook verification and event handling.
Error handling Handle API errors gracefully in production.
Supported chains Review chain confirmation times for production planning.
