Overview

The Cray Payment Gateway provides a simple hosted checkout experience.

Payment Flow

Create an API key and configure your webhook from the Cray Merchant Dashboard.
Create a payment session.
Redirect the customer to the hosted payment page.
The customer completes the payment.
The customer is redirected back to your redirectUrl.
Receive payment status updates via webhook or query the Order Status API.

Authentication

All API requests require the following header:

Authorization: Bearer <API_KEY_ID>:<API_SECRET>

Example:

Authorization: Bearer 6a5fc17290236d44e4c9720b:83bb5f87-26e2-46fc-8d35-fbf560f00b23

1. Create API Credentials

Before integrating:

Create an API Key from the Merchant Dashboard.
Configure your webhook endpoint.

You’ll receive:

API Key ID
API Secret

These credentials are required for all API requests.

2. Create a Payment Session

Creates a hosted checkout session.

Endpoint

POST https://merchant-api.cray.pro/payment-gateway/order

Request

curl --request POST \
  --url https://merchant-api.cray.pro/payment-gateway \
  --header "Authorization: Bearer <API_KEY_ID>:<API_SECRET>" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 0.01,
    "currency": "AED",
    "redirectUrl": "https://your-domain.com/payment/callback"
  }'

Request Body

Field	Type	Required	Description
amount	number	Yes	Payment amount.
redirectUrl	string	Yes	URL where the customer will be redirected after payment completes.
currency	string	No	Currency for the payment. Defaults to `USD`.
orderType	string	no	Set to `POS` if you are using it as a hosted payment page for a POS machine.

Supported Currencies

USD (default)
AED
EUR
INR

Supported orderType

PG (default)
POS

Response

{
  "success": true,
  "url": "https://payment.cray.pro/payment-gateway/4oG3wvhYBvW0XZnwWCpDg",
  "orderId": "6a61b7348c3662a2bc1559fb"
}

Field	Description
success	Indicates whether the payment session was created successfully.
url	Hosted payment page URL. Redirect the customer to this URL.
orderId	Unique order identifier. Save this to track payment status.

3. Redirect the Customer

Redirect your customer to the url returned from the Create Payment Session API. The customer completes the payment on the hosted Cray checkout page.

4. Customer Redirect

Once the payment completes (success or failure), the customer is redirected to the redirectUrl provided during payment session creation.

Important: Do not rely solely on the redirect to determine payment success. Always verify the payment using either the webhook or the Order Status API.

Webhooks

Configure your webhook URL from the Merchant Dashboard to receive payment status updates.

Order Status

The following statuses may be received:

Initialized
Processing
Completed
Failed
Cancelled

Webhook Payload

{
  "_id": "6a61b7348c3662a2bc1559fb",
  "status": "Completed"
}

Field	Description
_id	Order ID
status	Current payment status

Verify Webhook Signature

Each webhook request includes an HMAC signature in the Authorization header.

Authorization: <hmac>

Generate the expected HMAC using your API Secret.

Node.js Example

import crypto from "crypto";

const expectedSignature = crypto
  .createHmac("sha1", apiSecret)
  .update(JSON.stringify(payload))
  .digest("hex");

Only process the webhook if the generated signature matches the value received in the Authorization header.

Order Status API

Retrieve the latest payment status for an order.

Endpoint

GET https://merchant-api.cray.pro/payment-gateway/order/{orderId}

Example:

GET https://merchant-api.cray.pro/payment-gateway/order/6a5b71f7c5cf24d63529c04c

By default, this endpoint uses Server-Sent Events (SSE) and streams live status updates.

Server-Sent Events (Default)

GET /payment-gateway/order/{orderId}

Example response:

data: {
  "status": "Processing"
}

When the order status changes, another event is sent automatically. Example:

data: {
  "status": "Completed"
}

Standard HTTP Response

If you prefer polling instead of SSE, append ?sse=false.

GET https://merchant-api.cray.pro/payment-gateway/order/{orderId}?sse=false

Example response:

{
  "status": "Completed"
}

Possible Status Values

Initialized
Processing
Completed
Failed
Cancelled

Complete Integration Flow

Merchant Backend
        │
        │ Create Payment Session
        ▼
 Cray Merchant API
        │
        │ Returns payment URL + orderId
        ▼
Redirect Customer
        │
        ▼
 Cray Hosted Checkout
        │
        ├── Customer completes payment
        │
        ├── Redirect customer to redirectUrl
        │
        ├── Send webhook to merchant
        │
        └── Order Status API available (SSE or Polling)
                 │
                 ▼
         Merchant verifies HMAC
                 │
                 ▼
        Update order status in database

Best Practice

Use both:

Webhook as the primary source of truth for payment status.
Order Status API to recover from missed webhooks or to display live payment progress.

Getting Started

Integration Guide

Overview

Payment Flow

Authentication

1. Create API Credentials

2. Create a Payment Session

Endpoint

Request

Request Body

Supported Currencies

Supported orderType

Response

3. Redirect the Customer

4. Customer Redirect

Webhooks

Order Status

Webhook Payload

Verify Webhook Signature

Node.js Example

Order Status API

Endpoint

Server-Sent Events (Default)

Standard HTTP Response

Possible Status Values

Complete Integration Flow

Best Practice

​Overview

​Payment Flow

​Authentication

​1. Create API Credentials

​2. Create a Payment Session

​Endpoint

​Request

​Request Body

​Supported Currencies

​Supported orderType

​Response

​3. Redirect the Customer

​4. Customer Redirect

​Webhooks

​Order Status

​Webhook Payload

​Verify Webhook Signature

​Node.js Example

​Order Status API

​Endpoint

​Server-Sent Events (Default)

​Standard HTTP Response

​Possible Status Values

​Complete Integration Flow

​Best Practice

Overview

Payment Flow

Authentication

1. Create API Credentials

2. Create a Payment Session

Endpoint

Request

Request Body

Supported Currencies

Supported orderType

Response

3. Redirect the Customer

4. Customer Redirect

Webhooks

Order Status

Webhook Payload

Verify Webhook Signature

Node.js Example

Order Status API

Endpoint

Server-Sent Events (Default)

Standard HTTP Response

Possible Status Values

Complete Integration Flow

Best Practice