Accept stablecoin payments

Before you start: Create your API credentials and configure your webhook URL in the Cray Merchant Dashboard.

1. Create a payment POST

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

Header

Authorization: Bearer <API_KEY_ID>:<API_SECRET>

Body

{
  "amount": 250,
  "currency": "AED"
}

Response

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

2. Generate QR Code POST

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

Header

Authorization: Bearer <API_KEY_ID>:<API_SECRET>

Response

data:image/jpeg;base64,......

QR will expire in 2 minutes

Test Payer Flow

Once you can create a payment and generate its QR code, test the complete customer experience by scanning the QR code with any crypto wallet and approving a testnet payment.

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
QR_Scanned //in pos only
QR_Expired //in pos only
QR_Rejected //in pos only

Complete Integration Flow

Create Payment Session
        │
        ▼
Generate QR Code
        │
        ▼
Subscribe to Status API (SSE)
        │
        ▼
Display QR Code
        │
        ├
        │                                      
        ▼                                     
Payer scans QR Code                           
        │                                      
        ▼                                     
QR_Scanned event is triggered                 
        │                                      
        ▼                        
Payer signs the transaction                  
        │                                    
        ▼                                  
Processing event is triggered                
        │                                   
        ├───────────────┐                 
        │               │                  
        ▼               ▼                
Receive Webhook     Receive SSE Status       
        │               │                     
        ▼               ▼                    
Verify HMAC        Update UI / Status        
        │                                      
        ▼                                    
Update Order Status in Database               
        │                                    
        ▼                                    
Payment Completed                             

Important

The SSE connection is primarily for real-time status updates to the client, while the webhook should be treated as the authoritative server-to-server notification.

The recommended architecture is:

                    ┌───────────────┐
                    │     cray      │
                    └───────┬───────┘
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
       SSE Status API                 Webhook
              │                           │
              ▼                           ▼
        Frontend/UI               Backend Server
                                          │
                                          ▼
                                    Verify HMAC
                                          │
                                          ▼
                                  Update Database                           

Getting Started

POS integration

Accept stablecoin payments

Test Payer Flow

Order Status API

Endpoint

Server-Sent Events (Default)

Standard HTTP Response

Possible Status Values

Complete Integration Flow

Important

​Accept stablecoin payments

​Test Payer Flow

​Order Status API

​Endpoint

​Server-Sent Events (Default)

​Standard HTTP Response

​Possible Status Values

​Complete Integration Flow

​Important

Accept stablecoin payments

Test Payer Flow

Order Status API

Endpoint

Server-Sent Events (Default)

Standard HTTP Response

Possible Status Values

Complete Integration Flow

Important