Payment gateway documentation

$body = json_encode([
    'coin'        => 'BTC',
    'amount'      => '0.01',
    'externalRef' => 'order-4821',                        // your order id — makes retries safe
    'callbackUrl' => 'https://exchange.example/webhook',  // optional
]);

$ch = curl_init('https://coinrail.net/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . API_KEY,
        'Content-Type: application/json',
    ],
]);
$invoice = json_decode(curl_exec($ch), true);
// store $invoice['invoiceId'] + $invoice['address'] on your side

import requests

body = {
    'coin': 'BTC',
    'amount': '0.01',
    'externalRef': 'order-4821',                          # your order id — makes retries safe
    'callbackUrl': 'https://exchange.example/webhook',    # optional
}

res = requests.post(
    'https://coinrail.net/v1/invoices',
    json=body,
    headers={'Authorization': f'Bearer {API_KEY}'},
    timeout=15,
)
invoice = res.json()
# store invoice['invoiceId'] + invoice['address'] on your side

const res = await fetch("https://coinrail.net/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    coin: "BTC",
    amount: "0.01",
    externalRef: "order-4821",                        // your order id — makes retries safe
    callbackUrl: "https://exchange.example/webhook",  // optional
  }),
});

const invoice = await res.json();
// store invoice.invoiceId + invoice.address on your side

HttpClient http = HttpClient.newHttpClient();

String body = """
    { "coin": "BTC",
      "amount": "0.01",
      "externalRef": "order-4821",
      "callbackUrl": "https://exchange.example/webhook" }""";   // callbackUrl is optional

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://coinrail.net/v1/invoices"))
    .header("Authorization", "Bearer " + API_KEY)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
// store invoiceId + address on your side

function validV2(string $rawBody, ?string $header): bool {
    if ($header === null) return false;
    $t = null; $sigs = [];
    foreach (explode(',', $header) as $part) {                      // t=1752226802,v1=9f86d0…
        $kv = explode('=', trim($part), 2);
        if (count($kv) !== 2) continue;
        if ($kv[0] === 't')  $t = (int) $kv[1];
        if ($kv[0] === 'v1') $sigs[] = $kv[1];                      // may be several after a secret rotation
    }
    // Reject stale deliveries — this is what makes a captured request non-replayable
    if ($sigs === [] || $t === null || abs(time() - $t) > 300) return false;

    $expected = hash_hmac('sha256', $t . '.' . $rawBody, WEBHOOK_SECRET);
    $ok = false;
    foreach ($sigs as $sig) $ok = hash_equals($expected, $sig) || $ok;  // any of them may match
    return $ok;                                                     // constant-time compare
}

// RAW body — read it before any framework parses the request into an array
$raw = file_get_contents('php://input');
if (!validV2($raw, $_SERVER['HTTP_X_GATEWAY_SIGNATURE_V2'] ?? null)) {
    http_response_code(401);
    exit;
}
http_response_code(200);                                            // acknowledge immediately
handleEvent(json_decode($raw, true));                               // crediting must be IDEMPOTENT

import hashlib, hmac, time

def valid_v2(raw_body: bytes, header: str | None) -> bool:
    if not header:
        return False
    t, sigs = None, []
    for part in header.split(','):                                  # t=1752226802,v1=9f86d0…
        k, _, v = part.strip().partition('=')
        if not v:
            continue
        if k == 't':
            t = v
        elif k == 'v1':
            sigs.append(v)                                          # may be several after a secret rotation
    # Reject stale deliveries — this is what makes a captured request non-replayable
    if not t or not sigs or abs(int(time.time()) - int(t)) > 300:
        return False

    signed = f'{t}.'.encode() + raw_body                            # signed string is "<t>.<rawBody>"
    expected = hmac.new(WEBHOOK_SECRET.encode(), signed, hashlib.sha256).hexdigest()
    ok = False
    for sig in sigs:                                                # any of them may match
        ok = hmac.compare_digest(expected, sig) or ok
    return ok                                                       # constant-time compare

# Flask: request.get_data() returns the RAW body — never use request.json here
@app.post('/webhook')
def webhook():
    raw = request.get_data()
    if not valid_v2(raw, request.headers.get('X-Gateway-Signature-V2')):
        return '', 401
    handle_event(json.loads(raw))                                   # crediting must be IDEMPOTENT
    return '', 200                                                  # acknowledge immediately

import crypto from "node:crypto";
import express from "express";

function validV2(rawBody, header) {
  if (!header) return false;
  let t; const sigs = [];
  for (const part of header.split(",")) {                       // t=1752226802,v1=9f86d0…
    const [k, v] = part.trim().split("=", 2);
    if (!v) continue;
    if (k === "t") t = v;
    else if (k === "v1") sigs.push(v);                          // may be several after a secret rotation
  }
  // Reject stale deliveries — this is what makes a captured request non-replayable
  if (!t || !sigs.length || Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) return false;

  const signed = Buffer.concat([Buffer.from(`${t}.`), rawBody]);  // "<t>.<rawBody>"
  const expected = Buffer.from(crypto.createHmac("sha256", WEBHOOK_SECRET).update(signed).digest("hex"));
  return sigs.reduce((ok, sig) => {                             // any of them may match
    const b = Buffer.from(sig);
    return (b.length === expected.length && crypto.timingSafeEqual(expected, b)) || ok;
  }, false);                                                    // constant-time compare
}

// express.raw — the RAW body; express.json() would destroy the bytes we sign
app.post("/webhook", express.raw({ type: "*/*" }), (req, res) => {
  if (!validV2(req.body, req.get("X-Gateway-Signature-V2"))) return res.sendStatus(401);
  res.sendStatus(200);                                            // acknowledge immediately
  handleEvent(JSON.parse(req.body.toString("utf8")));             // crediting must be IDEMPOTENT
});

boolean validV2(byte[] rawBody, String header) throws Exception {
    if (header == null) return false;                              // missing header => 401, not a crash
    long t = 0; List<String> sigs = new ArrayList<>();
    for (String part : header.split(",")) {                        // t=1752226802,v1=9f86d0…
        String[] kv = part.trim().split("=", 2);
        if (kv.length != 2) continue;
        if (kv[0].equals("t"))  t = Long.parseLong(kv[1]);
        if (kv[0].equals("v1")) sigs.add(kv[1]);                   // may be several after a secret rotation
    }
    // Reject stale deliveries — this is what makes a captured request non-replayable
    if (sigs.isEmpty() || Math.abs(Instant.now().getEpochSecond() - t) > 300) return false;

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(WEBHOOK_SECRET.getBytes(UTF_8), "HmacSHA256"));
    mac.update((t + ".").getBytes(UTF_8));                          // signed string is "<t>.<rawBody>"
    String hex = HexFormat.of().formatHex(mac.doFinal(rawBody));
    boolean ok = false;
    for (String sig : sigs)                                        // any of them may match
        ok = MessageDigest.isEqual(hex.getBytes(), sig.getBytes()) || ok;
    return ok;                                                     // constant-time compare
}

function pollUntilFinal(string $invoiceId): string {
    while (true) {
        $ch = curl_init('https://coinrail.net/v1/invoices/' . $invoiceId);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . API_KEY],
        ]);
        $body = curl_exec($ch);
        $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        curl_close($ch);
        // 429 (rate limit) or 5xx — back off; hammering a limited endpoint keeps it limited
        if ($code !== 200) { sleep(30); continue; }
        $status = json_decode($body, true)['status'];
        // Only these two end the poll. UNDERPAID is NOT final: the customer
        // may still top up, and the invoice moves UNDERPAID -> SEEN -> CONFIRMED.
        if ($status === 'CONFIRMED' || $status === 'EXPIRED') return $status;
        sleep(15);                                                   // poll interval
    }
}

import time, requests

def poll_until_final(invoice_id: str) -> str:
    while True:
        res = requests.get(
            f'https://coinrail.net/v1/invoices/{invoice_id}',
            headers={'Authorization': f'Bearer {API_KEY}'},
            timeout=15,
        )
        # 429 (rate limit) or 5xx — back off. Without this res.json()['status'] raises KeyError
        if res.status_code != 200:
            time.sleep(30)
            continue
        status = res.json()['status']
        # Only these two end the poll. UNDERPAID is NOT final: the customer
        # may still top up, and the invoice moves UNDERPAID -> SEEN -> CONFIRMED.
        if status in ('CONFIRMED', 'EXPIRED'):
            return status
        time.sleep(15)                                               # poll interval

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function pollUntilFinal(invoiceId) {
  for (;;) {
    const res = await fetch(`https://coinrail.net/v1/invoices/${invoiceId}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` },
    });
    // 429 (rate limit) or 5xx — back off instead of looping at full speed
    if (!res.ok) { await sleep(30_000); continue; }
    const { status } = await res.json();
    // Only these two end the poll. UNDERPAID is NOT final: the customer
    // may still top up, and the invoice moves UNDERPAID -> SEEN -> CONFIRMED.
    if (status === "CONFIRMED" || status === "EXPIRED") return status;
    await sleep(15_000);                                          // poll interval
  }
}

HttpClient http = HttpClient.newHttpClient();

String pollUntilFinal(String invoiceId) throws Exception {
    while (true) {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://coinrail.net/v1/invoices/" + invoiceId))
            .header("Authorization", "Bearer " + API_KEY)
            .GET().build();
        HttpResponse<String> res = http.send(req, ofString());
        // 429 (rate limit) or 5xx — back off instead of parsing an error body
        if (res.statusCode() != 200) { Thread.sleep(30_000); continue; }
        String status = parseStatus(res.body());                         // your JSON parser
        // Only these two end the poll. UNDERPAID is NOT final: the customer
        // may still top up, and the invoice moves UNDERPAID -> SEEN -> CONFIRMED.
        if (status.equals("CONFIRMED") || status.equals("EXPIRED")) return status;
        Thread.sleep(15_000);                                            // poll interval
    }
}

// Run as a worker process (CLI), not inside a web request — the connection stays open.
$tail = '';                                                     // carry-over between chunks
while (true) {                                                // auto-reconnect on drop
    $ch = curl_init('https://coinrail.net/v1/events');
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . API_KEY],
        CURLOPT_TIMEOUT    => 0,                              // no timeout: the stream is long-lived
        // Called for every chunk as it arrives — that is what makes it real-time
        // TCP cuts the stream anywhere: a chunk often ends mid-line. Keep the tail
        // until the next chunk — otherwise an event landing on the seam is dropped
        // silently, and the order stays unpaid while the invoice is paid.
        CURLOPT_WRITEFUNCTION => function ($ch, string $chunk) use (&$tail): int {
            $lines = explode("\n", $tail . $chunk);
            $tail  = array_pop($lines);                       // last piece may be incomplete
            foreach ($lines as $line) {
                if (!str_starts_with($line, 'data:')) continue;   // ": ping" lines keep it alive
                $json = trim(substr($line, 5));
                if ($json !== '' && $json !== '{}') {
                    handleEvent(json_decode($json, true));    // update the order IDEMPOTENTLY
                }
            }
            return strlen($chunk);                            // must return bytes handled
        },
    ]);
    curl_exec($ch);
    curl_close($ch);
    sleep(3);                                                 // network dropped — pause and reconnect
}

import json, time, requests

def run_event_stream():                                       # run in a worker process/thread
    while True:                                               # auto-reconnect on drop
        try:
            with requests.get(
                'https://coinrail.net/v1/events',
                headers={'Authorization': f'Bearer {API_KEY}'},
                stream=True,                                  # keep the connection open
                timeout=(10, None),                           # connect timeout only — never read timeout
            ) as res:
                # 401/402/429 never become a stream — reconnecting at full speed makes it worse
                if res.status_code != 200:
                    time.sleep(30)
                    continue
                for line in res.iter_lines(decode_unicode=True):
                    if not line or not line.startswith('data:'):
                        continue                              # ': ping' lines keep it alive
                    payload = line[5:].strip()
                    if payload and payload != '{}':
                        handle_event(json.loads(payload))     # update the order IDEMPOTENTLY
        except requests.RequestException:
            pass                                              # network failed — fall through to the pause
        time.sleep(3)                                         # pause and reconnect

async function runEventStream() {                     // keep one process on it
  for (;;) {                                          // auto-reconnect on drop
    try {
      const res = await fetch("https://coinrail.net/v1/events", {
        headers: { "Authorization": `Bearer ${API_KEY}` },
      });
      let buf = "";
      // The body is an async iterable — chunks arrive as events happen
      for await (const chunk of res.body) {
        buf += Buffer.from(chunk).toString("utf8");
        const lines = buf.split("\n");
        buf = lines.pop() ?? "";                      // keep the unfinished tail
        for (const line of lines) {
          if (!line.startsWith("data:")) continue;    // ": ping" lines keep it alive
          const json = line.slice(5).trim();
          if (json && json !== "{}") handleEvent(JSON.parse(json));  // IDEMPOTENTLY
        }
      }
    } catch {
      // network failed — pause and reconnect
    }
    await new Promise((r) => setTimeout(r, 3000));
  }
}

void runEventStream() {                       // run in a separate thread
    HttpClient http = HttpClient.newHttpClient();
    while (true) {                            // auto-reconnect on drop
        try {
            HttpRequest req = HttpRequest.newBuilder()
                .uri(URI.create("https://coinrail.net/v1/events"))
                .header("Authorization", "Bearer " + API_KEY)
                .GET().build();
            // ofLines() yields lines as they arrive — the connection stays open
            http.send(req, HttpResponse.BodyHandlers.ofLines()).body()
                .filter(line -> line.startsWith("data:"))
                .map(line -> line.substring(5).trim())
                .filter(json -> !json.isEmpty() && !json.equals("{}"))
                .forEach(this::handleEvent);  // parse, update the order (idempotently)
        } catch (Exception e) {
            // network failed — pause and reconnect
        }
        try { Thread.sleep(3_000); } catch (InterruptedException ie) { return; }
    }
}

$body = json_encode([
    'coin'           => 'BTC',
    'toAddress'      => 'bc1q...',
    'amount'         => '0.0009',
    'feeRate'        => 8,                        // sat/vByte — you choose it, we do not
    'idempotencyKey' => 'withdraw-91422',         // your withdrawal id — never sends twice
]);

$ch = curl_init('https://coinrail.net/v1/payouts');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . API_KEY,
        'Content-Type: application/json',
    ],
]);
$payout = json_decode(curl_exec($ch), true);
// 202 Accepted -> { "payoutId": "...", "status": "QUEUED", "feeRate": 8, ... }

import requests

body = {
    'coin': 'BTC',
    'toAddress': 'bc1q...',
    'amount': '0.0009',
    'feeRate': 8,                                 # sat/vByte — you choose it, we do not
    'idempotencyKey': 'withdraw-91422',           # your withdrawal id — never sends twice
}

res = requests.post(
    'https://coinrail.net/v1/payouts',
    json=body,
    headers={'Authorization': f'Bearer {API_KEY}'},
    timeout=15,
)
payout = res.json()
# 202 Accepted -> { "payoutId": "...", "status": "QUEUED", "feeRate": 8, ... }

const res = await fetch("https://coinrail.net/v1/payouts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    coin: "BTC",
    toAddress: "bc1q...",
    amount: "0.0009",
    feeRate: 8,                              // sat/vByte — you choose it, we do not
    idempotencyKey: "withdraw-91422",        // your withdrawal id — never sends twice
  }),
});

const payout = await res.json();
// 202 Accepted -> { "payoutId": "...", "status": "QUEUED", "feeRate": 8, ... }

String body = """
    { "coin": "BTC",
      "toAddress": "bc1q...",
      "amount": "0.0009",
      "feeRate": 8,
      "idempotencyKey": "withdraw-91422" }""";

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://coinrail.net/v1/payouts"))
    .header("Authorization", "Bearer " + API_KEY)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
// 202 Accepted -> { "payoutId": "...", "status": "QUEUED", "feeRate": 8, ... }