Overview

RazCrypto provides two integration methods:

  • JavaScript SDK (Simple Mode): Public Key only, easiest for most merchants.
  • Server-to-Server API (Advanced Mode): Uses gateway_id + secret_key, more secure and customizable.

This page explains the advanced backend flow.

When to Use Server-to-Server API

  • You want extra security (secret never touches browser).
  • You want to control order creation from your own backend.
  • You are building enterprise integrations (ERP, SaaS billing, marketplaces).

Authentication

Every request must include:

  • gateway_id (string) → found in Dashboard
  • secret_key (string) → keep in server .env file
⚠️ Important: Never expose secret_key in frontend code.

Endpoints

4.1 Create Payment

POST /api/v1/payments/create

Headers:

Content-Type: application/json
Accept: application/json

Request Body:

{
  "gateway_id": "UID123456",
  "secret_key": "rz_sec_xxxxx",
  "amount": 15.75,
  "callback_url": "https://yourdomain.com/webhook",
  "email": "[email protected]",
  "mobile": "9876543210",
  "username": "john_doe",
  "product_id": "PROD001",
  "subscription_id": "SUB123",
  "return_json": "true"
}

Success Response:

{
  "status": "success",
  "payment_id": "payid_abc123def456",
  "amount": 15.75000321,
  "currency": "USDT",
  "chain": "BSC",
  "payment_url": "https://razcryptogateway.com/pay/payid_abc123def456?m=30",
  "qr_url": "https://razcryptogateway.com/qr?address=0x...&amount=15.75000321",
  "expiry_minutes": 30
}

4.2 Check Payment Status

GET /api/v1/payments/status/{payment_id}

Example:

curl "https://razcryptogateway.com/api/v1/payments/status/payid_abc123def456"

4.3 Webhook Handling

Webhook payloads are same as SDK mode. See Webhook Docs.

Security Best Practices

  • Store gateway_id and secret_key in .env.
  • Verify webhooks with HMAC-SHA256.
  • Always use HTTPS endpoints.
  • Rotate API keys periodically.
  • Never log raw secret keys.

Integration Examples

6.1 cURL Example

curl -X POST "https://razcryptogateway.com/api/v1/payments/create" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway_id": "UID123456",
    "secret_key": "rz_sec_xxxxx",
    "amount": 20.00,
    "callback_url": "https://yourdomain.com/webhook"
  }'
PHP (Laravel)
Node.js
Python
C#
Java

6.2 PHP (Laravel Guzzle)

<?php  
// ====================================================================  
// RazCrypto Server-to-Server Example (PHP + Guzzle)  
// ====================================================================  
// STEP 1: Install Guzzle  
//   composer require guzzlehttp/guzzle  
//  
// STEP 2: Store your API credentials in .env (never hardcode)  
//   RAZ_GATEWAY_ID=UID123456  
//   RAZ_SECRET_KEY=rz_sec_xxxxx  
//  
// STEP 3: Use this code in your backend (controller / API route)  
// ====================================================================  
  
require 'vendor/autoload.php';  
  
use GuzzleHttp\Client;  
  
try {  
    // Create client instance  
    $client = new Client([  
        'base_uri' => 'https://razcryptogateway.com/api/v1/',  
        'timeout'  => 10.0, // seconds  
    ]);  
  
    // Payment request payload  
    $payload = [  
        'gateway_id'   => getenv('RAZ_GATEWAY_ID'),   // from .env  
        'secret_key'   => getenv('RAZ_SECRET_KEY'),   // from .env  
        'amount'       => 25.50,                      // USD(T) amount  
        'callback_url' => 'https://yourdomain.com/webhook', // your server webhook  
        'email'        => '[email protected]',  
        'mobile'       => '9876543210',  
        'product_id'   => 'PROD001',  
        'subscription_id' => 'SUB123',  
        'return_json'  => 'true'  
    ];  
  
    // Call API  
    $response = $client->post('payments/create', [  
        'json' => $payload  
    ]);  
  
    // Parse response  
    $data = json_decode($response->getBody(), true);  
  
    // Handle response  
    if ($data['status'] === 'success') {  
        echo "✅ Payment created successfully\n";  
        echo "Payment ID: " . $data['payment_id'] . "\n";  
        echo "Payment URL: " . $data['payment_url'] . "\n";  
    } else {  
        echo "❌ Payment failed: " . ($data['message'] ?? 'Unknown error') . "\n";  
    }  
  
} catch (\Exception $e) {  
    echo "❌ Exception: " . $e->getMessage() . "\n";  
}

6.3 Node.js (Axios)

const axios = require("axios");

(async () => {
  const res = await axios.post("https://razcryptogateway.com/api/v1/payments/create", {
    gateway_id: process.env.RAZ_GATEWAY_ID,
    secret_key: process.env.RAZ_SECRET_KEY,
    amount: 30.00,
    callback_url: "https://yourdomain.com/webhook"
  });
  console.log(res.data);
})();

6.4 Python (Requests)

import requests, os

url = "https://razcryptogateway.com/api/v1/payments/create"
data = {
    "gateway_id": os.getenv("RAZ_GATEWAY_ID"),
    "secret_key": os.getenv("RAZ_SECRET_KEY"),
    "amount": 12.50,
    "callback_url": "https://yourdomain.com/webhook"
}
resp = requests.post(url, json=data)
print(resp.json())

6.5 C# (ASP.NET Core HttpClient)

using System.Net.Http.Json;

var client = new HttpClient();
var payload = new {
    gateway_id = Environment.GetEnvironmentVariable("RAZ_GATEWAY_ID"),
    secret_key = Environment.GetEnvironmentVariable("RAZ_SECRET_KEY"),
    amount = 40.00,
    callback_url = "https://yourdomain.com/webhook"
};
var res = await client.PostAsJsonAsync("https://razcryptogateway.com/api/v1/payments/create", payload);
var body = await res.Content.ReadAsStringAsync();
Console.WriteLine(body);

6.6 Java (OkHttp)

import okhttp3.*;

public class RazCryptoExample {
  public static void main(String[] args) throws Exception {
    OkHttpClient client = new OkHttpClient();
    MediaType JSON = MediaType.parse("application/json; charset=utf-8");
    String json = "{ \"gateway_id\": \""+System.getenv("RAZ_GATEWAY_ID")+"\", \"secret_key\": \""+System.getenv("RAZ_SECRET_KEY")+"\", \"amount\": 50.00, \"callback_url\": \"https://yourdomain.com/webhook\" }";
    RequestBody body = RequestBody.create(json, JSON);
    Request request = new Request.Builder()
      .url("https://razcryptogateway.com/api/v1/payments/create")
      .post(body)
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}

Error Handling

Error Code Description
RZ_001 Invalid amount
RZ_002 Invalid gateway_id or secret_key
RZ_005 DB insert failed
RZ_008 Invalid expiry_minutes

Error Response:

{
  "status": "error",
  "message": "Invalid secret key",
  "error_code": "RZ_002",
  "timestamp": "2025-10-06T14:00:00Z"
}

FAQ & Support

Can I use both SDK and Server API?

→ Yes.

Which is recommended?

→ SDK (simple) for most, Server API for advanced.

Is secret key required?

→ Yes, only for server mode.

Support