> ## Documentation Index
> Fetch the complete documentation index at: https://cray.pro/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guide

## Overview

The Cray Payment Gateway provides a simple hosted checkout experience.

### Payment Flow

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

***

# Authentication

All API requests require the following header:

```text theme={null}
Authorization: Bearer <API_KEY_ID>:<API_SECRET>
```

Example:

```text theme={null}
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

```text theme={null}
POST https://merchant-api.cray.pro/payment-gateway/order
```

## Request

```shellscript theme={null}
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

```text theme={null}
{
  "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:

```text theme={null}
Initialized
Processing
Completed
Failed
Cancelled
```

## Webhook Payload

```text theme={null}
{
  "_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.

```text theme={null}
Authorization: <hmac>
```

Generate the expected HMAC using your API Secret.

### Node.js Example

```text theme={null}
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

```text theme={null}
GET https://merchant-api.cray.pro/payment-gateway/order/{orderId}
```

Example:

```text theme={null}
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)

```text theme={null}
GET /payment-gateway/order/{orderId}
```

Example response:

```text theme={null}
data: {
  "status": "Processing"
}
```

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

Example:

```text theme={null}
data: {
  "status": "Completed"
}
```

***

## Standard HTTP Response

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

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

Example response:

```text theme={null}
{
  "status": "Completed"
}
```

***

## Possible Status Values

```text theme={null}
Initialized
Processing
Completed
Failed
Cancelled
```

***

# Complete Integration Flow

```text theme={null}
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.