Payment gateway integration

Quick start

1. Create a Bit2Fiat account and open Settings → Payment gateway.
2. Enable SCI and copy your api_key and api_secret (secret is shown once).
3. From your server, POST https://bit2fiat.com/sci with amount, coin, and order details.
4. Redirect the buyer to payment_url from the response.
5. Listen for IPN webhooks (and/or poll status) to mark the order paid.

Authentication

All create-payment requests must authenticate the merchant. Prefer HMAC signatures in production so the secret never leaves your server in query strings.

Option A — API secret (server-to-server)

Send credentials in the JSON/form body or headers:

Option B — HMAC signature

Build a message and sign with your secret using HMAC-SHA256 (hex):

api_key|coin|amount|order_id|timestamp|nonce

$message = implode('|', [$apiKey, $coin, $amount, $orderId, $timestamp, $nonce]);
$signature = hash_hmac('sha256', $message, $apiSecret);

Create a payment

CSRF is not required for this endpoint (server-to-server). Send JSON with Content-Type: application/json and Accept: application/json for a JSON response. Without JSON headers, a successful create redirects to the pay page.

Request fields

cURL example

curl -X POST 'https://bit2fiat.com/sci' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "api_key": "b2f_YOUR_KEY",
    "api_secret": "YOUR_SECRET",
    "coin": "USDT_TRC20",
    "amount": "25.00",
    "order_id": "ORD-1042",
    "success_url": "https://yoursite.com/paid",
    "cancel_url": "https://yoursite.com/cancel",
    "ipn_url": "https://yoursite.com/webhooks/bit2fiat"
  }'

Success response

{
  "ok": true,
  "payment_id": "uuid",
  "payment_url": "https://bit2fiat.com/pay/uuid",
  "address": "T…",
  "coin": "USDT_TRC20",
  "amount": "25",
  "order_id": "ORD-1042",
  "expires_at": "2026-08-06T14:00:00+00:00",
  "status": "pending"
}

Checkout page & status

Hosted pay page (QR, address, countdown, partial payment progress).

JSON status for polling (the pay page polls this every few seconds).

{
  "payment_id": "uuid",
  "order_id": "ORD-1042",
  "status": "pending",
  "status_label": "Awaiting payment",
  "coin": "USDT_TRC20",
  "address": "T…",
  "amount_expected": "25",
  "amount_received": "0",
  "amount_remaining": "25",
  "progress_pct": 0,
  "success_url": null,
  "expires_at": "…"
}

IPN (merchant webhooks)

When a payment status changes in a way that settles (paid / overpaid) or reports underpaid, Bit2Fiat POSTs form fields to your ipn_url. Respond with HTTP 200 (body containing ok is preferred). Failed deliveries are retried with backoff.

IPN fields

Verify IPN signature

Sort all fields except signature by key ascending, join as key=value with &, then:

ksort($payload);
unset($payload['signature']);
$pairs = [];
foreach ($payload as $k => $v) {
    if (is_array($v)) continue;
    $pairs[] = $k.'='.$v;
}
$expected = hash_hmac('sha256', implode('&', $pairs), $apiSecret);
hash_equals($expected, $receivedSignature);

Payment statuses

Supported coins

Pass the exact code in the coin field. Currently active:

Errors

JSON error shape:

{ "ok": false, "error": "Human readable message" }

Security checklist

1. Keep api_secret only on your server — never in browser JS or mobile apps.
2. Prefer HMAC signatures for create requests in production.
3. Always verify IPN signature before fulfilling orders.
4. Use HTTPS for success_url, cancel_url, and ipn_url.
5. Make fulfillment idempotent: the same payment_id may notify more than once.