Accept crypto payments

curl -X POST https://easycryptopay.xyz/api/crypto/deposits \
  -H "Authorization: Bearer ecp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 99.99,
    "metadata": { "order_id": "order_12345" }
  }'

{
  "invoiceId": "clx...",
  "paymentToken": "inv_xK9mP2rT",
  "expectedAmountUSD": 99.99,
  "expiresAt": "2026-04-30T10:41:00Z",
  "status": "pending",
  "isTest": true,
  "metadata": { "order_id": "order_12345" },
  "paymentLink": "https://easycryptopay.xyz/xK9m"
}

curl -X POST https://easycryptopay.xyz/api/pay/pay_xK9mP2rT/create-deposit \
  -H "Content-Type: application/json" \
  -d '{ "currency": "USDT", "networkCode": "TRC20" }'

# Drive the sandbox deposit to completed and fire the full
# deposit.confirming → deposit.completed (+ invoice.paid) webhook sequence.
# Pass the depositId from the previous step (a paymentToken works too once a
# deposit exists):
curl -X POST https://easycryptopay.xyz/api/crypto/deposits/<depositId>/test-complete \
  -H "Authorization: Bearer ecp_test_YOUR_KEY"

import { verifyWebhookSignature } from "@easycryptopay/node";

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyWebhookSignature({
    rawBody: req.body.toString("utf8"),
    signatureHeader: req.header("X-ECP-Signature") || "",
    secret: process.env.ECP_WEBHOOK_SECRET,
  });
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.event === "deposit.completed") {
    // event.data.metadata.order_id, event.data.receivedAmountUsd, ...
  }
  res.json({ ok: true });
});

curl -X POST https://easycryptopay.xyz/api/crypto/deposits \
  -H "Authorization: Bearer ecp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 99.99,
    "metadata": { "order_id": "order_12345" }
  }'

{
  "invoiceId": "clx...",
  "paymentToken": "inv_xK9mP2rT",
  "expectedAmountUSD": 99.99,
  "expiresAt": "2026-04-30T10:41:00Z",
  "status": "pending",
  "feePercent": 0.1,
  "feeUsd": 0.10,
  "isTrial": false,
  "isTest": false,
  "metadata": { "order_id": "order_12345" },
  "paymentLink": "https://easycryptopay.xyz/xK9m"
}

curl https://easycryptopay.xyz/api/crypto/deposits/pay_xK9mP2rT/check \
  -H "Authorization: Bearer ecp_live_YOUR_KEY"

{
  "status": "completed",
  "confirmations": 1,
  "txId": "a8f3e2b1c4d5...",
  "amountUsd": 100,
  "totalCreditedUsd": 99.90
}

curl -X POST https://easycryptopay.xyz/api/crypto/deposits/clx.../test-complete \
  -H "Authorization: Bearer ecp_test_YOUR_KEY"

{
  "status": "completed",
  "txId": "test_tx_abc123",
  "confirmations": 1,
  "amountUsd": 25,
  "totalCreditedUsd": 24.975,
  "isTest": true
}

curl -X POST https://easycryptopay.xyz/api/invoices \
  -H "Authorization: Bearer ecp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website Development",
    "amount_usd": 2500,
    "description": "Phase 1 deliverable",
    "recipient_email": "client@example.com",
    "send": true,
    "metadata": { "project_id": "proj_42" }
  }'

{
  "invoice": {
    "id": "clx...",
    "title": "Website Development",
    "payment_link": "https://easycryptopay.xyz/pay/inv_bN3qW7sY",
    "paymentLink": "https://easycryptopay.xyz/bN3q",
    "status": "sent",
    "expires_at": "2026-05-22T10:00:00Z",
    "expiresAt": "2026-05-22T10:00:00Z",
    "is_test": false,
    "isTest": false,
    "metadata": { "project_id": "proj_42" }
  },
  "emailSent": true
}

curl https://easycryptopay.xyz/api/invoices/clx... \
  -H "Authorization: Bearer ecp_live_YOUR_KEY"

curl "https://easycryptopay.xyz/api/payments?status=completed&limit=50&offset=0" \
  -H "Authorization: Bearer ecp_live_YOUR_KEY"

{
  "payments": [
    {
      "id": "clx...",
      "status": "completed",
      "currency": "USDT",
      "network": "TRC20",
      "networkDisplayName": "Tron (TRC20)",
      "amount": 100,
      "amount_usd": 100,
      "expected_amount_usd": 100,
      "expected_crypto_amount": 100,
      "deposit_address": "TXrk4as3waDADP2Q...",
      "deposit_tag": null,
      "tx_id": "a8f3e2b1c4d5...",
      "confirmations": 1,
      "required_confirmations": 1,
      "fee_usd": 0.10,
      "fee_percent": 0.1,
      "is_trial": false,
      "is_test": false,
      "metadata": { "order_id": "order_12345" },
      "payment_link": "https://easycryptopay.xyz/pay/pay_xK9mP2rT",
      "total_amount_usd": 99.90,
      "created_at": "2026-04-22T10:00:00Z",
      "completed_at": "2026-04-22T10:05:22Z",
      "expires_at": "2026-04-22T11:00:00Z"
    }
  ],
  "total": 42,
  "stats": {
    "totalReceived": 15420.50,
    "totalFees": 15.42,
    "completedCount": 38,
    "pendingCount": 4
  }
}

curl https://easycryptopay.xyz/api/payments/clx... \
  -H "Authorization: Bearer ecp_live_YOUR_KEY"

curl https://easycryptopay.xyz/api/balance \
  -H "Authorization: Bearer ecp_live_YOUR_KEY"

{
  "balance": 1542.30,
  "totalVolumeUsd": 15420.50,
  "totalReceived": 15425.72,
  "totalFees": 5.42,
  "pendingCount": 2,
  "currency": "USD"
}

curl "https://easycryptopay.xyz/api/customers?status=active&limit=50" \
  -H "Authorization: Bearer ecp_live_YOUR_KEY"

{
  "customers": [
    {
      "id": "cus_...",
      "email": "buyer@example.com",
      "name": "buyer",
      "totalPaidUsd": 240.5,
      "transactionCount": 3,
      "lastCurrency": "USDT",
      "lastActivity": "2026-04-22T10:05:22Z",
      "status": "active",
      "createdAt": "2026-03-01T09:00:00Z",
      "transactions": [
        { "id": "dep_...", "amountUsd": 100, "currency": "USDT", "status": "completed", "date": "2026-04-22" }
      ]
    }
  ],
  "total": 128,
  "stats": { "total": 128, "active": 42, "totalRevenue": 15420.5 }
}

curl https://easycryptopay.xyz/api/crypto/currencies \
  -H "Authorization: Bearer ecp_live_YOUR_KEY"

{
  "currencies": [
    {
      "coin": "USDT",
      "name": "Tether",
      "icon": "/images/crypto/usdt.png",
      "isStablecoin": true,
      "sortOrder": 0,
      "pricePerUnit": 1.0,
      "autoConvertEnabled": false,
      "networks": [
        {
          "code": "TRC20",
          "displayName": "Tron (TRC20)",
          "minConfirm": 1,
          "estimatedTime": "~1 min",
          "walletAddress": "TXrk4as3waDADP2Q...",
          "walletTag": null,
          "isDefault": true,
          "walletGenerated": true,
          "walletCount": 1,
          "wallets": [
            {
              "id": "wlt_...",
              "address": "TXrk4as3waDADP2Q...",
              "tag": null,
              "isDefault": true,
              "createdAt": "2026-04-22T10:00:00Z",
              "exchangeConfigId": "exc_...",
              "exchangeKey": "mexc",
              "exchangeName": "MEXC"
            }
          ]
        }
      ]
    }
  ],
  "exchangeConnected": true,
  "exchangeKey": "mexc",
  "tradingApiAvailable": true,
  "useAutoRanking": false
}

{
  "apiVersion": "1",
  "event": "deposit.completed",
  "timestamp": 1745311354,
  "data": {
    "id": "clx...",
    "paymentToken": "pay_xK9mP2rT",
    "paymentLink": "https://easycryptopay.xyz/xK9m",
    "status": "completed",
    "currency": "USDT",
    "network": "TRC20",
    "networkDisplayName": "Tron (TRC20)",
    "amountUsd": 100,
    "receivedAmountUsd": 100,
    "receivedCryptoAmount": 100,
    "feeUsd": 0.1,
    "confirmations": 1,
    "confirmationsRequired": 1,
    "txId": "a8f3e2b1c4d5...",
    "depositAddress": "TXrk4as3waDADP2Q...",
    "depositTag": null,
    "invoiceId": null,
    "customerEmail": null,
    "createdAt": "2026-04-22T10:00:00Z",
    "expiresAt": "2026-04-22T11:00:00Z",
    "completedAt": "2026-04-22T10:05:22Z",
    "isTest": false,
    "metadata": { "order_id": "order_12345" },
    "autoConvert": { "enabled": false }
  }
}

X-ECP-Signature: t=1776852322,v1=a8f3e2b1c4d5e6f7...

import { verifyWebhookSignature } from "@easycryptopay/node";

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyWebhookSignature({
    rawBody: req.body.toString("utf8"),
    signatureHeader: req.header("X-ECP-Signature") || "",
    secret: process.env.ECP_WEBHOOK_SECRET,
  });
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.event === "deposit.completed") {
    // event.data.metadata.order_id, event.data.receivedAmountUsd, ...
  }
  res.json({ ok: true });
});

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        return False
    if abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{t}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, v1)

<?php
function verify_ecp($raw_body, $header, $secret, $tolerance = 300) {
    $parts = [];
    foreach (explode(',', $header) as $seg) {
        [$k, $v] = array_pad(explode('=', $seg, 2), 2, null);
        if ($k && $v !== null) $parts[trim($k)] = trim($v);
    }
    if (empty($parts['t']) || empty($parts['v1'])) return false;
    if (abs(time() - (int)$parts['t']) > $tolerance) return false;
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $raw_body, $secret);
    return hash_equals($expected, $parts['v1']);
}

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "io"
    "net/http"
    "strconv"
    "strings"
    "time"
)

func verify(raw []byte, header, secret string, tolerance int64) bool {
    var t, v1 string
    for _, seg := range strings.Split(header, ",") {
        kv := strings.SplitN(strings.TrimSpace(seg), "=", 2)
        if len(kv) != 2 {
            continue
        }
        switch kv[0] {
        case "t":
            t = kv[1]
        case "v1":
            v1 = kv[1]
        }
    }
    if t == "" || v1 == "" {
        return false
    }

    ts, err := strconv.ParseInt(t, 10, 64)
    if err != nil {
        return false
    }
    if delta := time.Now().Unix() - ts; delta > tolerance || delta < -tolerance {
        return false
    }

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(t + "."))
    mac.Write(raw)

    expected, _ := hex.DecodeString(v1)

    // hmac.Equal, not bytes.Equal or ==: constant time.
    return hmac.Equal(mac.Sum(nil), expected)
}

func handler(w http.ResponseWriter, r *http.Request) {
    // io.ReadAll, NOT json.NewDecoder — the signature covers the raw bytes.
    raw, _ := io.ReadAll(r.Body)
    if !verify(raw, r.Header.Get("X-ECP-Signature"), os.Getenv("ECP_WEBHOOK_SECRET"), 300) {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }
    // json.Unmarshal(raw, &event)
    w.WriteHeader(http.StatusOK)
}

require "openssl"

def verify_ecp(raw_body, header, secret, tolerance = 300)
  parts = header.to_s.split(",").map { |seg| seg.strip.split("=", 2) }.to_h
  t, v1 = parts["t"], parts["v1"]
  return false if t.nil? || v1.nil?
  return false if (Time.now.to_i - t.to_i).abs > tolerance

  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{t}.#{raw_body}")
  # secure_compare, not ==
  OpenSSL.secure_compare(expected, v1)
end

# Rails: request.raw_post is the raw body. params is NOT — it has been parsed
# and re-ordered, and hashing it will never match.
post "/webhook" do
  halt 401 unless verify_ecp(request.body.read, request.env["HTTP_X_ECP_SIGNATURE"], ENV["ECP_WEBHOOK_SECRET"])
  event = JSON.parse(request.body.tap(&:rewind).read)
  status 200
end

using System.Security.Cryptography;
using System.Text;

static bool VerifyEcp(string rawBody, string header, string secret, int tolerance = 300)
{
    string? t = null, v1 = null;
    foreach (var seg in (header ?? "").Split(','))
    {
        var kv = seg.Trim().Split('=', 2);
        if (kv.Length != 2) continue;
        if (kv[0] == "t") t = kv[1];
        if (kv[0] == "v1") v1 = kv[1];
    }
    if (t is null || v1 is null) return false;
    if (!long.TryParse(t, out var ts)) return false;
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > tolerance) return false;

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var digest = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{rawBody}"));
    var expected = Convert.ToHexString(digest).ToLowerInvariant();

    // FixedTimeEquals, not string ==
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(v1));
}

// ASP.NET Core: EnableBuffering() then read the body as a string. Binding the
// request to a model gives you a re-serialised object, which will not verify.

npm install @easycryptopay/node
# or
yarn add @easycryptopay/node
# or
pnpm add @easycryptopay/node

import EasyCryptoPay from "@easycryptopay/node";

const client = new EasyCryptoPay({ apiKey: process.env.ECP_API_KEY });

// POST a USD amount. Customer picks currency + network on the hosted /pay page.
const payment = await client.createDeposit({
  amount: 99.99,
  metadata: { order_id: "order_12345" },
  idempotencyKey: "order_12345",
});

console.log(payment.paymentLink);
// → https://easycryptopay.xyz/pay/inv_xK9mP2rT

import { verifyWebhookSignature } from "@easycryptopay/node";

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyWebhookSignature({
    rawBody: req.body.toString("utf8"),
    signatureHeader: req.header("X-ECP-Signature") || "",
    secret: process.env.ECP_WEBHOOK_SECRET,
  });
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));
  // ... handle event.event
  res.json({ ok: true });
});

// Server-side (any runtime). Works on every plan.
const res = await fetch("https://easycryptopay.xyz/api/crypto/deposits", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ECP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 99.99, metadata: { order_id: "order_12345" } }),
});
const { paymentLink } = await res.json();

// Send the customer to the hosted checkout. They choose coin + network there;
// your server gets a signed deposit.completed webhook when the payment lands.
return Response.redirect(paymentLink, 303);
// (or, client-side: window.location.href = paymentLink)

<!-- Drop the SDK once, anywhere in your page. -->
<script src="https://easycryptopay.xyz/embed.js" defer></script>

<!-- Container the iframe will be injected into. -->
<div id="ecp-checkout"></div>

<script>
  // 1. Create the payment server-side with your API key. The response gives
  //    you a paymentToken — pass it to the SDK.
  // 2. Mount the iframe into your container. The SDK auto-resizes to fit
  //    the embedded page's content and relays lifecycle events.
  document.addEventListener("DOMContentLoaded", function () {
    EasyCryptoPay.checkout({
      token: "inv_xK9mP2rT",
      container: "#ecp-checkout",
      onPaid: function (event) {
        // event = { type: "ecp:paid", paymentToken, amountUsd, txId }
        window.location.href = "/thank-you?order=" + encodeURIComponent(event.paymentToken);
      },
      onExpired: function () {
        // 60-min window closed without payment. Offer to mint a fresh token.
      },
      onError: function (event) {
        console.error("[ECP]", event.message);
      },
    });
  });
</script>

// Same flow inside a React component. The SDK is browser-only — load it
// once via <script> in your <head> (or via next/script with strategy="afterInteractive").
import { useEffect, useRef } from "react";

export function CryptoCheckout({ token, onPaid }) {
    const containerRef = useRef(null);
    useEffect(() => {
        if (!containerRef.current) return;
        const handle = window.EasyCryptoPay.checkout({
            token,
            container: containerRef.current,
            onPaid,
        });
        return () => handle.destroy();
    }, [token, onPaid]);
    return <div ref={containerRef} />;
}

// Prefer your own UI over the iframe? Build the checkout yourself. Your API
// key is server-side ONLY (never ship it to the browser); the customer-facing
// steps use the PUBLIC /api/pay/<token> endpoints.
//
//   1. (server) Create a payment with your API key.
//   2. Fetch currencies for the customer to choose from.
//   3. POST the customer's choice to mint the deposit.
//   4. Render the depositAddress + expectedCryptoAmount in your own UI.
//   5. Poll status (server-side /check) or rely on the webhook.
//
// CORS: /api/pay/* sends Access-Control-Allow-Origin: *, so the customer-facing
// steps (2 + 3) can run in the browser on your own domain. Your API key never
// leaves the server. (Step 5's /check is a Bearer endpoint — keep it server-side.)

const create = await fetch("https://easycryptopay.xyz/api/crypto/deposits", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${process.env.ECP_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({ amount: 99.99, metadata: { order_id: "order_12345" } }),
});
const { paymentToken } = await create.json();

// Then, from the customer's browser (CORS-enabled) or your backend:
//   POST /api/pay/<paymentToken>/create-deposit  with { currency, networkCode }
// → { depositAddress, depositTag, expectedCryptoAmount, expiresAt }.

# Toggle auto-convert. Available on every plan.
# Browser session only — this is a management endpoint (not API-key accessible).
curl -X PUT https://easycryptopay.xyz/api/crypto/auto-convert \
  -H "Content-Type: application/json" \
  -H "Origin: https://easycryptopay.xyz" \
  --cookie "ecp_session=…" \
  -d '{ "all": true, "enabled": true }'

{
  "currency": "BTC",
  "all": false,
  "enabled": true,
  "autoConvertCurrencies": { "BTC": true }
}

// 400 Bad Request
{
  "error": "Trading permission missing on the connected exchange.",
  "code": "TRADING_PERMISSION_REQUIRED",
  "exchangeName": "MEXC",
  "help": {
    "permission": "Spot Trading",
    "path": "Account → API Management → Edit Key → Enable Spot Trading",
    "notes": "Save, then click \"Test connection\" again."
  }
}

{
  "apiVersion": "1",
  "event": "deposit.auto_converted",
  "timestamp": 1745311520,
  "data": {
    "id": "dep_abc123",
    "paymentToken": "inv_xK9mP2rT",
    "currency": "BTC",
    "receivedCryptoAmount": 0.00125,
    "receivedAmountUsd": 99.85,
    "status": "completed",
    "autoConvert": {
      "enabled": true,
      "status": "filled",
      "orderId": "1234567",
      "symbol": "BTCUSDT",
      "receivedUsdt": 99.87
    },
    "metadata": { "order_id": "order_12345" }
  }
}

// 409 Conflict
{
  "error": "Idempotency-Key was previously used with a different request body",
  "code": "IDEMPOTENCY_CONFLICT"
}

// 409 Conflict
{
  "error": "A request with this Idempotency-Key is currently in progress",
  "code": "IDEMPOTENCY_IN_PROGRESS"
}

# All list endpoints follow the same convention.
curl "https://easycryptopay.xyz/api/payments?limit=50&offset=100" \
  -H "Authorization: Bearer ecp_live_YOUR_KEY"

# Response shape:
# { "payments": [...], "total": 312, "stats": {...} }