Checkout - RMZ Developer Docs

The Embed API supports two checkout modes: authenticated checkout (using a Sanctum token from the OTP flow) and guest checkout (providing customer details directly). Both modes create a checkout session and return payment options.

Authenticated Checkout

Create a checkout session for an authenticated customer. Customer information is retrieved from the token.

POST /api/embed/checkout

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <token>` (must have `embed:checkout` ability)
`X-Embed-Key`	Yes	Your store’s embed public key
`Content-Type`	Yes	`application/json`

Request Body

Field	Type	Required	Description
`product_id`	integer	Yes	The product ID
`quantity`	integer	Yes	Purchase quantity (min: 1)
`coupon_code`	string	No	Coupon code to apply
`customer_note`	string	No	Customer note (max 500 characters)
`notice`	string	No	Alternative field for customer note
`subscription_plan`	integer	No	Subscription variant ID (required for subscription products)
`fields`	object	No	Custom product field values (keyed by field index)

curl -X POST "https://embed.rmz.gg/api/embed/checkout" \
  -H "Authorization: Bearer 1|abc123xyz..." \
  -H "X-Embed-Key: your_embed_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 42,
    "quantity": 1,
    "coupon_code": "SAVE20"
  }'

Success Response - Payment Required (200)

{
  "success": true,
  "data": {
    "type": "payment_required",
    "checkout_id": 789,
    "checkout_url": "ck_abc123",
    "payment_url": "https://store.rmz.gg/checkout/ck_abc123",
    "amount": "126.50",
    "subtotal": "149.00",
    "discount_amount": "29.80",
    "tax_amount": "17.88",
    "payment_methods": [
      {
        "id": "card",
        "name_ar": "بطاقة ائتمان",
        "name_en": "Credit Card",
        "icon": "card"
      },
      {
        "id": "mada",
        "name_ar": "مدى",
        "name_en": "Mada",
        "icon": "mada"
      },
      {
        "id": "applepay",
        "name_ar": "Apple Pay",
        "name_en": "Apple Pay",
        "icon": "applepay"
      }
    ]
  }
}

Success Response - Free Order (200)

When the total is zero (e.g., 100% discount coupon), the order is created immediately:

{
  "success": true,
  "data": {
    "type": "free_order",
    "order_id": 456,
    "message": "Order created successfully"
  }
}

Available Payment Methods

ID	Description
`card`	Credit Card (Visa/Mastercard)
`mada`	Mada debit card
`stcpay`	STC Pay
`applepay`	Apple Pay
`paypal`	PayPal
`bank`	Bank Transfer
`coinbase`	Cryptocurrency

Available payment methods depend on the store’s configuration and the order amount. Not all methods are available for every store.

Guest Checkout

Create a checkout session without OTP authentication. Customer details are provided directly in the request body.

POST /api/embed/guest/checkout

Headers

Header	Required	Description
`X-Embed-Key`	Yes	Your store’s embed public key
`Content-Type`	Yes	`application/json`

Request Body

Field	Type	Required	Description
`product_id`	integer	Yes	The product ID
`quantity`	integer	Yes	Purchase quantity (min: 1)
`customer_first_name`	string	Yes	Customer first name (max 100)
`customer_last_name`	string	Yes	Customer last name (max 100)
`customer_email`	string	Yes	Customer email address
`customer_phone`	string	Yes	Customer phone number (max 20)
`customer_country_code`	string	Yes	Phone country code (max 10)
`coupon_code`	string	No	Coupon code to apply
`customer_note`	string	No	Customer note (max 500 characters)
`fields`	object	No	Custom product field values

curl -X POST "https://embed.rmz.gg/api/embed/guest/checkout" \
  -H "X-Embed-Key: your_embed_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 42,
    "quantity": 1,
    "customer_first_name": "Ahmed",
    "customer_last_name": "Ali",
    "customer_email": "ahmed@example.com",
    "customer_phone": "501234567",
    "customer_country_code": "966"
  }'

The response format is identical to the authenticated checkout response above.

Initiate Payment

After creating a checkout session, initiate the actual payment with the customer’s chosen payment method.

Authenticated Payment

POST /api/embed/payment/initiate

Requires Authorization: Bearer <token> with embed:checkout ability.

Guest Payment

POST /api/embed/guest/payment/initiate

No authentication required.

Request Body (Both Endpoints)

Field	Type	Required	Description
`checkout_url`	string	Yes	The `checkout_url` from the checkout response
`payment_method`	string	Yes	One of: `card`, `mada`, `stcpay`, `applepay`, `paypal`, `bank`, `coinbase`

curl -X POST "https://embed.rmz.gg/api/embed/payment/initiate" \
  -H "Authorization: Bearer 1|abc123xyz..." \
  -H "X-Embed-Key: your_embed_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_url": "ck_abc123",
    "payment_method": "card"
  }'

Response Types

The response varies by payment method: Card, Mada, STC Pay, Apple Pay, Coinbase, PayPal (with PayPal.me link)

{
  "success": true,
  "data": {
    "type": "redirect",
    "redirect_url": "https://..."
  }
}

Redirect the customer to redirect_url to complete payment. PayPal (manual, email only)

{
  "success": true,
  "data": {
    "type": "paypal_manual",
    "paypal_email": "merchant@paypal.com",
    "amount": 149.00,
    "checkout_url": "ck_abc123"
  }
}

Bank Transfer

{
  "success": true,
  "data": {
    "type": "bank_transfer",
    "bank_details": {
      "bank_name": "Al Rajhi Bank",
      "account_name": "Store Owner Name",
      "account_number": "1234567890",
      "iban": "SA1234567890123456789012"
    },
    "amount": 149.00,
    "checkout_url": "ck_abc123"
  }
}

Error Responses

Status	Description
404	Checkout session expired or not found
400	Order already created for this checkout
400	Payment method not configured for this store
422	Invalid payment method

Checkout sessions expire after a period of time. If a customer takes too long, you may need to create a new checkout session.

Product Fields

Products can have custom fields that customers fill in during checkout. Pass field values in the fields object, keyed by the field’s array index from the product data.

Field Types

Type	Value Format	Notes
`text`	string	Free text input
`number`	number	Numeric input
`date`	string	Date string
`datetime`	string	Date and time string
`color`	string	Color value
`select`	integer	Index of the selected option (may add to price)
`image`	file	Upload via `field_files.{index}` (JPG, PNG, GIF, max 10MB)
`file`	file	Upload via `field_files.{index}` (PDF, DOC, DOCX, TXT, ZIP, max 20MB)

Select fields can include price add-ons. The add-on amount is added to the unit price before calculating the total. Check the product info response to see if options have prices.

Embed API

Webhooks

​Authenticated Checkout

​Headers

​Request Body

​Success Response - Payment Required (200)

​Success Response - Free Order (200)

​Available Payment Methods

​Guest Checkout

​Headers

​Request Body

​Initiate Payment

​Authenticated Payment

​Guest Payment

​Request Body (Both Endpoints)

​Response Types

​Error Responses

​Product Fields

​Field Types

Authenticated Checkout

Headers

Request Body

Success Response - Payment Required (200)

Success Response - Free Order (200)

Available Payment Methods

Guest Checkout

Headers

Request Body

Initiate Payment

Authenticated Payment

Guest Payment

Request Body (Both Endpoints)

Response Types

Error Responses

Product Fields

Field Types