Crypto in, money in the bank

Your customer pays in crypto. Xfiat converts it and pays the amount into a bank account. You never hold crypto and never touch exchange rates.

Today the API does one thing: crypto to bank. Payouts: NGN (more currencies when enabled for your account).

Coins: USDT, USDC, BTC, ETH and BNB are received directly. Many other coins (for example LTC, SOL, DOGE, XRP) are accepted too: Xfiat converts them on the way in and pays the bank the same way. GET /assets lists them all in one list.

Base address: https://xfiat.app/api/v1

Quick start

1. Ask Xfiat for an account. You get test keys straight away.
2. Make a test payment (below). Nothing real moves in test mode.
3. Move it to completed with simulate and watch your webhook receive the events.
4. When it works, ask for live keys and change the key. Nothing else changes.

curl https://xfiat.app/api/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"coin":"USDT","payout_currency":"NGN","payout_amount":"50000",
       "bank":{"bank_code":"058","account_number":"0123456789"},
       "reference":"ORDER-1001"}'

$ch = curl_init('https://xfiat.app/api/v1/payments');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('XFIAT_SECRET_KEY'),
        'Idempotency-Key: order-1001',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'coin' => 'USDT', 'payout_currency' => 'NGN', 'payout_amount' => '50000',
        'bank' => ['bank_code' => '058', 'account_number' => '0123456789'],
        'reference' => 'ORDER-1001',
    ]),
]);
$res = json_decode(curl_exec($ch), true);
$payment = $res['data'];   // show $payment['deposit_address'] and $payment['crypto_amount']

const res = await fetch('https://xfiat.app/api/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.XFIAT_SECRET_KEY}`,
    'Idempotency-Key': 'order-1001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    coin: 'USDT', payout_currency: 'NGN', payout_amount: '50000',
    bank: { bank_code: '058', account_number: '0123456789' },
    reference: 'ORDER-1001',
  }),
});
const { data: payment } = await res.json();  // payment.deposit_address, payment.crypto_amount

Show the payer deposit_address, crypto_amount, coin and network_name. Then wait for the webhook.

Payment links

For a shop, an invoice or a social page. No server needed. Put your public key (pk_live_…) and the amount in a link:

https://xfiat.app/api/v1/pay/?key=pk_live_...&amount=50000&reference=INV-2041

As a button on your website:

<a href="https://xfiat.app/api/v1/pay/?key=pk_live_...&amount=50000&reference=INV-2041"
   style="display:inline-block;padding:12px 20px;background:#1d4ed8;color:#fff;border-radius:8px;text-decoration:none">Pay with crypto</a>

Hosted payment page

Create the page from your server with POST /checkouts and send the payer to its url. Xfiat handles the coin choice, the QR code, the countdown and the status.

Keys

Send the secret key in every request:

Authorization: Bearer sk_live_...

Keys are shown once when Xfiat creates them. If one leaks, ask Xfiat to replace it; the old key stops at once. Xfiat can also restrict live calls to your server addresses.

Requests and replies

Send JSON with Content-Type: application/json (32 KB at most). Amounts are strings with up to 8 decimals, e.g. "0.0015". Times are UTC, ISO 8601.

Every reply has the same shape:

{ "ok": true,  "data": { ... },  "request_id": "req_8Fq2..." }
{ "ok": false, "error": { "code": "invalid_request", "message": "...", "field": "payout_amount" }, "request_id": "req_..." }

Keep the request_id (also in the X-Request-Id header). Xfiat support can find any call with it.

Errors

Limits

Every reply carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). Over the limit you get 429 with Retry-After.

Your own values are in GET /account. Xfiat raises them on request. Test and live are counted apart.

Retries (Idempotency-Key)

POST /payments and POST /checkouts need an Idempotency-Key header: any unique text of 8 to 80 characters, such as your order id. If the connection drops, send the same request with the same key: you get the first answer back, never a second payment. The same key with a different body returns 409. Keys are kept for 7 days.

reference is separate: it is your own id for the payment and must be unique per account and mode.

Signed requests (optional)

For extra safety Xfiat can require every call to be signed with your signing secret. Add two headers:

X-Xfiat-Timestamp: 1760450000
X-Xfiat-Signature: hex( HMAC-SHA256( signing_secret, timestamp + "." + METHOD + "." + path + "." + body ) )

path is the part after /v1, e.g. /payments. body is the exact JSON you send (empty for GET). The time must be within 5 minutes.

$ts  = (string) time();
$sig = hash_hmac('sha256', $ts . '.POST./payments.' . $json, $signingSecret);

const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac('sha256', signingSecret).update(`${ts}.POST./payments.${json}`).digest('hex');

Endpoints

Check the service

No key needed. Returns {"service":"Xfiat API","version":"1.0.0","time":"…"}.

Your account

Status, whether live is allowed, open verification requests, your payout bank, your fee (fee_percent), your limits and the last 24 hours of use.

Coins, networks and the least amount

Every coin and network you can use, in one list, with min_amount: the least crypto worth paying after the network minimum, the bank fee and your account limit. memo_required means the payer must also send the memo (tag) shown on the payment.

{ "coins": [ { "coin": "USDT", "name": "Tether", "decimals": 2,
      "networks": [ { "network": "tron", "name": "Tron (TRC20)", "min_amount": "1.20" },
                    { "network": "ethereum", "name": "Ethereum (ERC20)", "min_amount": "5.00" } ] } ],
  "payout_currencies": ["NGN"], "min_amount_for": "NGN" }

Banks

Bank codes for payouts: [{"code":"058","name":"GTBank"}, …]. Cache it for a day.

Check a bank account

Returns account_name so your user can confirm it before paying. In test mode the name is TEST ACCOUNT.

Price a payment

Give coin, payout_currency and one of crypto_amount (what the payer sends) or payout_amount (what the bank gets). You get both amounts after every fee, plus min_crypto_amount. A quote is a guide for 60 seconds; the final amount is in the payment once paid.

Create a payment

Header Idempotency-Key is required. Reply 201, a payment:

{
  "id": "pay_3kQ9w2ZtY8bN1cV5xL0a", "object": "payment", "mode": "live", "status": "awaiting_payment",
  "coin": "USDT", "network": "tron", "network_name": "Tron (TRC20)",
  "deposit_address": "TQ7x...9fKp", "memo": null,
  "crypto_amount": "33.67", "crypto_received": null,
  "payout": { "currency": "NGN", "amount_estimate": "50000.00", "amount": null,
              "bank": { "bank_code": "058", "bank_name": "GTBank", "account_name": "ADA OBI", "account_number_last4": "6789" } },
  "reference": "ORDER-1001", "metadata": {}, "checkout_id": null,
  "expires_at": "2026-10-14T15:42:10Z", "completed_at": null,
  "created_at": "2026-10-14T14:42:10Z", "updated_at": "2026-10-14T14:42:10Z"
}

Converted coins work the same way. Their price moves until the coins arrive, so payout.amount_estimate is a guide and payout.amount is the exact amount once the bank is paid. A quote also returns max_crypto_amount for them.

List payments

Newest first. limit 1 to 100. Next page: starting_after= the last id. has_more says if there is one.

Get a payment

The latest state. Use webhooks rather than polling; if you must poll, once every 30 seconds is plenty.

Cancel a payment

Only while awaiting_payment. If crypto still arrives later it is paid out as normal and you get the webhooks.

Create a hosted page

Fields: payout_amount (required), payout_currency, coins (up to 10 codes; leave out to offer every coin: the main ones as buttons, the rest through a search box), reference (unique), description, success_url, cancel_url. Header Idempotency-Key required. Returns url to send the payer to, and payment_id once they start paying. Read it later with GET /checkouts/{id}. The page lasts 60 minutes and pays out to your registered bank.

Events

The events sent to your webhook, with delivery result. Handy to check what you missed.

Test your webhook

Sends a signed webhook.test event to your webhook now and tells you what your server answered.

Simulate (test mode)

Body {"status":"completed"}. Also confirming, processing, needs_review, expired, failed. Each step in between fires its own webhook, like a real payment.

Statuses

Webhooks

Give Xfiat an https address on your server. On every change Xfiat sends a POST with the event and the full payment. Events: payment.created, payment.confirming, payment.processing, payment.completed, payment.needs_review, payment.expired, payment.cancelled, payment.failed.

{ "id": "evt_Wq1...", "object": "event", "type": "payment.completed", "mode": "live",
  "created_at": "2026-10-14T14:51:03Z", "data": { ...payment... } }

Check the signature

Header Xfiat-Signature: t=TIMESTAMP,v1=SIGNATURE. SIGNATURE is hex HMAC-SHA256 of TIMESTAMP + "." + raw body with your webhook secret (whsec_…). Use the raw body, before any JSON parsing.

$body = file_get_contents('php://input');
$head = $_SERVER['HTTP_XFIAT_SIGNATURE'] ?? '';
if (!preg_match('/t=(\d+),v1=([a-f0-9]{64})/', $head, $m)
    || abs(time() - (int) $m[1]) > 300
    || !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, getenv('XFIAT_WEBHOOK_SECRET')), $m[2])) {
    http_response_code(400); exit;
}
$event = json_decode($body, true);
// ignore an event id you already handled, then update your order
http_response_code(200);

const crypto = require('crypto');
app.post('/xfiat-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(req.get('Xfiat-Signature') || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return res.sendStatus(400);
  const want = crypto.createHmac('sha256', process.env.XFIAT_WEBHOOK_SECRET).update(m[1] + '.' + req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]))) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // ignore an event id you already handled, then update your order
  res.sendStatus(200);
});

Reply 2xx within 8 seconds; do slow work afterwards. Webhooks only go to public https addresses and do not follow redirects.

Test mode

Test keys use the same endpoints and replies, with "mode": "test". No crypto is received and no bank is paid. Test addresses start with test_; do not send real crypto to them. Move a payment along with simulate. Test and live data never mix: a test id is not_found with a live key.

Going live

1. Your webhook checks the signature and ignores repeated event ids.
2. Every payment has a unique reference and every create call an Idempotency-Key.
3. Your secret key sits in server settings, not in code or a browser.
4. You show the payer the exact amount, coin and network, and the time left.
5. Ask Xfiat to allow live payments. You may be asked for business documents.
6. Swap sk_test_ for sk_live_.

Questions: support@xfiat.app with your account id and a request_id. This page in plain text: api.txt.