Skip to main content
POST
/
checkout
/
sessions
curl -X POST https://api.maash.io/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: mk_live_1234567890abcdef1234567890abcdef" \
  -H "x-maash-user-type: checkout" \
  -d '{
    "merchant_id": "mer_01ABC",
    "transaction_id": "txn_123456789",
    "amount_usd": 100,
    "merchant_currency": "USD",
    "merchant_amount": 100,
    "theme": {
      "primaryColor": "#4ade80",
      "backgroundColor": "#f5f5f5",
      "cardColor": "#ffffff"
    }
  }'

{
  "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=eyJhbGciOi...&primaryColor=%234ade80&backgroundColor=%23f5f5f5&cardColor=%23ffffff",
    "ext_transaction_id":"txn_1515",
    "transaction_id":"01KHQSZXR80Q5GR29W4Q166P5Q",
    "expires_at": "2024-02-02T15:25:00Z",
    "created_at": "2024-01-31T15:25:00Z"
  }
}
Creates a hosted checkout session and returns a URL where your customer can complete payment. The session expires after the configured duration (default: 48 hours). If a session with the same transaction_id already exists, the existing session is returned.

​
Authentication

​
x-api-key
string
required
Your merchant API key (e.g., mk_live_1234567890abcdef1234567890abcdef).
​
x-maash-user-type
string
required
Must be set to checkout.

​
Request body

​
merchant_id
string
required
Your merchant identifier (e.g., mer_01ABC). Must not be empty.
​
transaction_id
string
required
Your unique identifier for this transaction. Use this to correlate payments with orders in your system. Must not be empty. If a session with the same transaction_id already exists, the existing session is returned.
​
amount_usd
number
required
Payment amount in USD. Must be between 0.01 and 1000000.
​
merchant_currency
string
Merchant’s currency code (ISO 4217). Supported currencies include: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, BRL, MXN, SGD, HKD, NZD, ZAR, SEK, NOK, DKK, PLN, TRY, KRW, ALL, DZD, ARS, AMD, AZN, BHD, BDT, BYN, BMD, BOB, BAM, BGN, KHR, CLP, COP, CRC, HRK, CUP, CZK, DOP, EGP, GEL, GHS, GTQ, HNL, HUF, ISK, IDR, IRR, IQD, ILS, JMD, JOD, KZT, KES, KWD, KGS, LBP, MKD, MYR, MUR, MDL, MNT, MAD, MMK, NAD, NPR, TWD, NIO, NGN, OMR, PKR, PAB, PEN, PHP, QAR, RON, RUB, SAR, RSD, SSP, VES, LKR, THB, TTD, TND, UGX, UAH, AED, UYU, UZS, VND, and more. Defaults to USD when omitted.
​
merchant_amount
number
Payment amount in merchant’s currency. Use this when merchant_currency is provided to specify the amount in the merchant’s local currency.
​
is_maash_transaction
boolean
Optional flag to mark this as a Maash-managed transaction. Defaults to false when omitted.
​
theme
object
Optional theme customization for the checkout widget. When provided, the returned checkout_url and checkout_url_with_token will include the theme values as URL query parameters so the widget renders with your brand colors on first load. See Theme Customization for all available parameters.
Merchant settings such as webhook_url and settlement_wallet_address are loaded from your merchant record. Configure these in the Maash Dashboard.

​
Response

​
data
object
​
session_id
string
Unique session identifier (e.g., cs_01ARZ3NDEKTSV4RRFFQ69G5FAV).
​
checkout_url
string
URL to redirect the customer to for payment.
​
checkout_url_with_token
string
Checkout URL with embedded session token for iframe embedding.
​
transaction_id
string
The transaction identifier created by Maash.
​
ext_transaction_id
string
Your unique identifier for this transaction.
​
expires_at
string
ISO 8601 timestamp when this session expires.
​
created_at
string
ISO 8601 timestamp when the session was created.
curl -X POST https://api.maash.io/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: mk_live_1234567890abcdef1234567890abcdef" \
  -H "x-maash-user-type: checkout" \
  -d '{
    "merchant_id": "mer_01ABC",
    "transaction_id": "txn_123456789",
    "amount_usd": 100,
    "merchant_currency": "USD",
    "merchant_amount": 100,
    "theme": {
      "primaryColor": "#4ade80",
      "backgroundColor": "#f5f5f5",
      "cardColor": "#ffffff"
    }
  }'

{
  "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=eyJhbGciOi...&primaryColor=%234ade80&backgroundColor=%23f5f5f5&cardColor=%23ffffff",
    "ext_transaction_id":"txn_1515",
    "transaction_id":"01KHQSZXR80Q5GR29W4Q166P5Q",
    "expires_at": "2024-02-02T15:25:00Z",
    "created_at": "2024-01-31T15:25:00Z"
  }
}