Cipay developer documentation

Add Saudi-first recurring billing and gateway-hosted payments to your product.

Cipay is the billing layer between your application and licensed payment gateways. It manages products, subscriptions, invoices, retries, and customer self-service while the gateway collects card details through hosted checkout.

How an integration works

Configure Cipay

Create a sandbox API key, publish a product and price, approve your application origin, and copy the storefront locator.

Connect your server

Use @cipay/client-sdk/api for trusted commerce operations and mount one browser-safe /api/cipay endpoint.

Build the buyer UI

Use @cipay/client-sdk/react hooks or components. They call your endpoint and never receive the API key.

Confirm asynchronously

Verify signed webhook bytes before changing order, invoice, or subscription state.

React SDK → your /api/cipay route → Cipay → hosted gateway checkout
                                      ↓
                         signed webhook → your server

Start in sandbox

Follow the quickstart

Install the SDK, mount a server route, list a product, and create checkout.

Configure Cipay Platform

Find the API key, approved origin, storefront locator, and published product.

Choose your SDK

Server SDK

Manage products, customers, subscriptions, discounts, checkout, orders, invoices, and webhooks.

React SDK

Load buyer data with TanStack Query hooks or render accessible components you can style.

Core terms

Term	Meaning
API key	Secret server credential scoped to sandbox or production.
Storefront locator	Public identifier that selects an environment, merchant, and storefront.
Buyer endpoint	Your same-origin `/api/cipay` route for browser-safe catalog and account operations.
Capability	Short-lived secret returned for one checkout’s protected status.
Webhook secret	Server-only secret used to verify exact delivery bytes.

Every guide is available as Markdown. Agents can read /llms.txt for the page map or /llms-full.txt for the complete public documentation set.