API Reference#

curl -X POST https://fintrapay.io/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: xfp_key_abc123def456" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <hmac-sha256-signature>" \
  -d '{
    "amount": "100.00",
    "currency": "USDT",
    "blockchain": "tron",
    "mode": "custodial"
  }'

# Compute signature on your server (any language), then call:
curl -X POST https://fintrapay.io/v1/invoices \
  -H "X-API-Key: xfp_key_abc123..." \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"amount":"100.00","currency":"USDT","blockchain":"tron"}'

Authenticate with email and password. Returns JWT access token (15min) and refresh token (7 days).

{
  "email": "merchant@example.com",
  "password": "your_password"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 900,
  "merchant": {
    "id": "uuid",
    "company_name": "Acme Corp",
    "email": "merchant@example.com"
  }
}

Exchange a valid refresh token for a new access/refresh token pair.

{ "refresh_token": "eyJhbGciOiJIUzI1NiIs..." }

{
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG...",
  "expires_in": 900
}

{
  "error": "insufficient balance for withdrawal",
  "code": "INSUFFICIENT_BALANCE"
}

{
  "invoices": [ ... ],
  "total": 142,
  "page": 1,
  "page_size": 20
}

Create a new stablecoin invoice. Returns a checkout URL. If currency/blockchain are omitted, the customer selects their preferred token and chain on the hosted checkout page.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "awaiting_selection",
  "amount": "100.00000000",
  "currency": "",
  "blockchain": "",
  "mode": "custodial",
  "payment_address": "",
  "checkout_url": "https://fintrapay.io/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accepted_tokens": ["USDT","USDC","DAI","FDUSD","TUSD","PYUSD"],
  "accepted_chains": ["tron","bsc","ethereum","solana","base","arbitrum","polygon"],
  "fee_amount": "0.40000000",
  "expires_at": "2026-03-30T13: 00: 00Z",
  "created_at": "2026-03-30T12: 00: 00Z"
}

Retrieve a specific invoice by ID. Returns full details including payment status, TX hash, confirmations, and fee breakdown.

{
  "id": "inv_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "confirmed_overpaid",
  "amount": "100.00000000",
  "received_amount": "110.00000000",
  "currency": "USDT",
  "blockchain": "tron",
  "payment_address": "TXyz123abc456def789...",
  "payment_tx_hash": "abc123def456...",
  "confirmations": 20,
  "fee_rate": "0.00400",
  "fee_amount": "0.40000000",
  "refunded_amount": "0.00000000",
  "overpayment_status": "pending_decision",
  "overpayment_amount": "10.00000000",
  "sender_address": "TCustomerSenderAddress...",
  "paid_at": "2026-03-29T12: 05: 32Z"
}

List all invoices with optional filters: status, currency, blockchain, date range. Paginated response.

Keep an overpayment. The surplus stays on your balance and the invoice's overpayment_status becomes accepted. No request body — the invoice ID identifies the decision.

{
  "invoice_id": "uuid",
  "overpayment_status": "accepted",
  "overpaid_amount": "12.50000000",
  "fee_amount": "0.05000000",
  "credited_amount": "12.45000000"
}

Send an overpayment back to the customer. Your balance is debited immediately and the surplus is reserved while the refund is in flight, so it cannot be withdrawn from underneath the refund. No request body.

{
  "invoice_id": "uuid",
  "overpayment_status": "refund_pending",
  "overpaid_amount": "12.50000000",
  "gas_estimate": "0.27600000",
  "refund_amount": "12.22400000",
  "to_address": "TCustomerAddress..."
}

Create a single payout to any external wallet address.

{
  "id": "pay_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "status": "pending",
  "amount": "50.00000000",
  "currency": "USDT",
  "blockchain": "bsc",
  "to_address": "0xabc123def456...",
  "reason": "payment",
  "created_at": "2026-03-29T14: 00: 00Z"
}

Create a batch payout with multiple recipients. All must be on the same blockchain and currency.

{
  "currency": "USDT",
  "blockchain": "bsc",
  "fee_deduction": "from_amount",
  "recipients": [
    { "to_address": "0xabc...", "amount": "50.00", "reference": "salary-001" },
    { "to_address": "0xdef...", "amount": "75.00", "reference": "salary-002" },
    { "to_address": "0x123...", "amount": "100.00", "reference": "reward-001" }
  ]
}

{
  "batch": {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending",
    "total_amount": "225.00000000",
    "total_count": 3,
    "currency": "USDT",
    "blockchain": "bsc",
    "created_at": "2026-03-29T14: 00: 00Z"
  },
  "payouts": [ ... ]
}

Retrieve a specific payout. Returns status, TX hash, gas fee, and timestamps.

List all payouts with optional filters: status, blockchain, currency. Paginated.

List all batch payouts. Paginated.

Get batch payout details with all individual payout items.

Create a withdrawal. Destination is automatically set to your registered wallet for that blockchain.

{
  "id": "wdr_d4e5f6a7-b8c9-0123-defa-456789012345",
  "status": "pending",
  "amount": "500.00000000",
  "currency": "USDT",
  "blockchain": "tron",
  "to_address": "TYourRegisteredWallet...",
  "created_at": "2026-03-29T15: 00: 00Z"
}

Retrieve a specific withdrawal by ID.

List all withdrawals with optional filters. Paginated.

Create a refund for a paid invoice. Specify the amount to refund (partial or full).

{
  "id": "ref_uuid",
  "invoice_id": "inv_uuid",
  "amount": "50.00000000",
  "currency": "USDT",
  "blockchain": "tron",
  "status": "pending",
  "created_at": "2026-03-29T16: 00: 00Z"
}

List every refund issued against one invoice, including partial refunds. Use this to reconcile how much of an invoice has been returned before issuing another.

List all refunds across every invoice. Paginated.

{
  "refunds": [ ... ],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "total_pages": 3,
  "summary": {
    "refunded_amount": "1234.50000000",
    "pending_count": 2,
    "completed_count": 38
  }
}

Retrieve a specific refund by ID.

Create an earn contract. Locks stablecoins from your custodial balance for a specified duration.

{
  "id": "ern_uuid",
  "status": "active",
  "principal_amount": "1000.00000000",
  "currency": "USDT",
  "blockchain": "tron",
  "duration_months": 6,
  "term_days": 180,
  "apy": "7.00",
  "daily_interest_amount": "0.19178082",
  "accrued_interest": "0.00000000",
  "start_date": "2026-03-29T16: 00: 00Z",
  "maturity_date": "2026-09-25T16: 00: 00Z"
}

List all earn contracts. Filter by status (active, matured, broken).

Get earn contract details including accrued interest.

Withdraw accrued interest. Minimum $10. Sent from treasury wallet to your registered wallet.

{ "amount": "15.00" }

Break contract early. Principal returned minus already withdrawn interest. Undrawn interest forfeited.

Daily interest accrual history for a specific contract.

List every interest withdrawal you've requested, across all of your earn contracts, with its current status.

{
  "withdrawals": [
    {
      "id": "uuid",
      "contract_id": "ern_uuid",
      "amount": "15.00000000",
      "type": "interest",
      "status": "requested",
      "currency": "USDT",
      "blockchain": "tron",
      "created_at": "2026-03-29T16: 00: 00Z"
    }
  ]
}

Current APY by term. Public — no authentication required, so you can render live rates on a marketing page before a merchant signs in.

{
  "rates": [
    { "duration_months": 1,  "apy": 4.00,  "label": "1 Month" },
    { "duration_months": 3,  "apy": 6.00,  "label": "3 Months" },
    { "duration_months": 6,  "apy": 8.00,  "label": "6 Months" },
    { "duration_months": 12, "apy": 12.00, "label": "12 Months" }
  ]
}

Retrieve your full merchant profile: company info, enabled modes, KYC status, registered wallet addresses, and settings.

{
  "id": "uuid",
  "company_name": "Acme Corp",
  "email": "merchant@example.com",
  "status": "active",
  "kyc_status": "approved",
  "custodial_enabled": true,
  "non_custodial_enabled": true,
  "payout_auto_approve": false,
  "webhook_url": "https://example.com/webhooks",
  "wallet_tron": "TXyz...",
  "wallet_bsc": "0xabc...",
  "wallet_ethereum": "0xdef...",
  "wallet_solana": "...",
  "wallet_base": "0x...",
  "wallet_arbitrum": "0x...",
  "wallet_polygon": "0x..."
}

Update merchant settings: webhook URL, wallet addresses, company name.

{
  "webhook_url": "https://example.com/webhooks",
  "wallet_tron": "TNewWalletAddress..."
}

Get merchant dashboard stats: total invoices, volume, active contracts, etc.

Aggregated payment analytics: revenue per day, totals, and recurring-revenue figures. This is the data behind the dashboard Overview.

{
  "daily_revenue": [
    { "date": "2026-09-19", "amount": "1842.37000000", "count": 14 },
    { "date": "2026-09-20", "amount": "960.10000000", "count": 8 }
  ],
  "today": { "amount": "960.10000000", "count": 8 },
  "timezone": "Asia/Kolkata"
}

Submit KYC documents for review. An individual account supplies identity documents; a company account supplies five, including incorporation papers.

{
  "documents": [
    { "label": "passport", "data": "data:application/pdf;base64,JVBERi0..." }
  ]
}

List all your API keys with settings.

Create a new API key. Returns the secret ONCE — it cannot be retrieved later.

{
  "display_name": "Production",
  "base_currency": "USD",
  "checkout_theme": "dark"
}

{
  "api_key": "xfp_key_...",
  "api_secret": "xfp_secret_...",
  "display_name": "Production",
  "warning": "Save your API secret now. It cannot be retrieved later."
}

Update API key settings (display_name, base_currency, checkout_theme).

Revoke an API key. Takes effect immediately. All requests using this key will be rejected.

Rotate your primary API key and secret. The previous pair stops working the moment this returns, so deploy the new credentials before calling it.

{
  "api_key": "xfp_key_...",
  "api_secret": "xfp_secret_...",
  "created_at": "2026-09-20T10: 00: 00Z",
  "warning": "Save your API secret now. It cannot be retrieved later."
}

Get your custodial balance across all chains and tokens.

{
  "balances": [
    { "chain": "tron", "token": "USDT", "balance": "1250.50000000" },
    { "chain": "bsc", "token": "USDT", "balance": "340.00000000" },
    { "chain": "ethereum", "token": "USDC", "balance": "2100.75000000" },
    { "chain": "solana", "token": "USDT", "balance": "500.00000000" }
  ]
}

Every manual credit or debit an administrator has applied to your balance, newest first. Use it to reconcile a balance that moved without a matching invoice, payout or withdrawal.

{
  "adjustments": [
    {
      "id": "b1c2d3e4-...",
      "chain": "bsc",
      "token": "USDT",
      "amount": "25.00000000",
      "direction": "credit",
      "reason": "Goodwill credit for delayed settlement",
      "created_at": "2026-09-14T09: 12: 00Z"
    }
  ],
  "total": 1, "page": 1, "page_size": 20
}

Your permanent deposit address per chain. These are the addresses to send funds to in order to top up your custodial balance directly, without creating an invoice.

{
  "wallets": [
    { "blockchain": "bsc", "address": "0xbd2242..." },
    { "blockchain": "tron", "address": "TXyzAbc..." }
  ]
}

The per-invoice deposit addresses derived for you, with the invoice each one belongs to. Useful for reconciling an on-chain transfer back to the invoice that generated the address.

List all whitelisted withdrawal wallets.

Add a new whitelisted wallet address.

{ "blockchain": "tron", "address": "TNewAddress..." }

Remove a whitelisted wallet.

Create a support ticket.

{ "subject": "Payout stuck", "category": "technical", "message": "..." }

List your support tickets. Paginated.

Get ticket details with messages.

Reply to a ticket.

{ "message": "Thank you, the issue is resolved." }

Estimate fees for an invoice or payout before creating it.

{ "amount": "100.00", "currency": "USDT", "blockchain": "tron", "type": "invoice" }

POST https://your-domain.com/webhooks/fintrapay
Content-Type: application/json
User-Agent: FintraPay-Webhook/2.0
X-FintraPay-Event:      invoice.paid
X-FintraPay-Event-Id:   3f8b2a4d-1234-4abc-9def-0123456789ab
X-FintraPay-Timestamp:  2026-04-23T10:00:00Z
X-FintraPay-Signature:  <hex(HMAC-SHA256(timestamp + "\n" + body, webhook_secret))>

{
  "id":        "3f8b2a4d-1234-4abc-9def-0123456789ab",
  "event":     "invoice.paid",
  "timestamp": "2026-04-23T10:00:00Z",
  "data": {
    "invoice_id":  "inv_uuid",
    "external_id": "your-order-ref-123",
    "status":      "paid",
    "amount":      "100.00000000",
    "currency":    "USDT",
    "blockchain":  "tron",
    "tx_hash":     "abc123...",
    "paid_at":     "2026-04-23T09:59:58Z"
  }
}

import hmac, hashlib, time
from datetime import datetime

def verify_webhook(timestamp, body_bytes, signature, webhook_secret, max_age=300):
    # 1. Reject stale or future-dated deliveries to defeat replay attacks.
    ts = int(datetime.fromisoformat(timestamp.replace("Z", "+00:00")).timestamp())
    if abs(time.time() - ts) > max_age:
        return False
    # 2. Recompute signature: HMAC-SHA256 over (timestamp + "\n" + body).
    msg = timestamp.encode() + b"\n" + body_bytes
    expected = hmac.new(webhook_secret.encode(), msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# Use X-FintraPay-Event-Id for idempotency: store the ID, skip duplicates.

List your per-event toggles. Events not listed are enabled by default.

Upsert one (event, enabled) pair.

{ "event": "earn.interest_accrued", "enabled": false }

List your webhook deliveries. Filters: status, event, invoice_id, created_after, created_before. Paginated (page, page_size up to 100).

Get full delivery details including request payload and last response body (truncated to 1024 bytes).

Re-deliver the same envelope (same event_id) with a fresh signed timestamp. Eligible: failed or delivered. Limits: 10 resends/min per merchant, 30s cooldown per delivery, 20 lifetime resends per delivery.

GET /v1/invoices?status=paid&updated_after=2026-04-26T10:00:00Z&page_size=100

Create a new payment link

{
  "id": "abc-123",
  "slug": "coffee-shop",
  "title": "Coffee Shop Payment",
  "fixed_amount": true,
  "amount": "5.00",
  "status": "active",
  "link_url": "https://fintrapay.io/p/coffee-shop",
  "total_paid": "0",
  "total_payments": 0
}

List your payment links

Retrieve one payment link, including total_paid and total_payments. Those counters are maintained inside the settlement transaction that credits your balance, so they never disagree with the invoices beneath them.

Update a payment link

Get payment link by slug (public, no auth). Returns only what the payment page shows — no IDs or totals — plus display_name, fee_bearer, and fee_rate when the payer pays the platform fee.

Create invoice from payment link (public, no auth)

{
  "invoice_id": "901694b9-...",
  "checkout_url": "https://fintrapay.io/pay/901694b9-...",
  "link": { "slug": "...", "title": "...", "display_name": "...", "fee_bearer": "receiver" }
}

Create a subscription plan

{
  "id": "abc-123",
  "slug": "pro-plan",
  "name": "Pro Plan",
  "amount": "9.99",
  "interval": "monthly",
  "trial_days": 7,
  "subscribe_url": "https://fintrapay.io/subscribe/pro-plan"
}

List your plans

Retrieve one subscription plan.

Update plan (name, amount, status)

Create a subscription (merchant-initiated)

{
  "subscription": { "id": "...", "status": "active", "current_period_end": "..." },
  "invoice_id": "...",
  "checkout_url": "https://fintrapay.io/pay/..."
}

List subscriptions (filterable by status, plan_id)

Get subscription detail + invoice history

Cancel a subscription

Pause billing

Resume paused subscription

Get plan info (public, no auth). Returns only what the subscribe page shows — no IDs, subscriber counts or revenue — plus display_name, fee_bearer, and fee_rate when the payer pays the platform fee.

Customer subscribes (public)

Register a merchant-side end user

{ "id": "uuid", "external_user_id": "user_12345", "is_active": true }

Get user with addresses and balances

Generate deposit address for one chain

{
  "address": "0xabc...",
  "blockchain": "bsc",
  "network": "BEP-20",
  "supported_tokens": ["USDT", "USDC", "DAI", "FDUSD", "TUSD"],
  "is_active": true
}

Generate addresses for all 7 chains at once

List deposits for a user (filterable by token, chain, status)

Per-token per-chain balances for a user

List all of your end users. Paginated.

Update an end user: email, label, is_active, is_blocked, block_reason. A blocked or deactivated user is refused new deposit addresses.

List the deposit addresses already issued to one user, across every chain.

List deposits across all of your users. Filterable by token, blockchain and status.

Get single deposit detail

<script src="https://fintrapay.io/js/fintrapay-deposit.js"></script>
<div id="deposit"></div>
<script>
  FintraPay.deposit({
    target: '#deposit',
    apiKey: 'xfp_key_...',
    userId: 'user_12345',
    theme: 'dark',
    onDeposit: function(data) {
      console.log('Deposit confirmed!', data.token, data.amount);
    }
  });
</script>

Resolve a recipient email to a display name before sending, so the sender can confirm who they are paying.

Email a one-time confirmation code to the authenticated sender. Required before a transfer can be created.

Transfer custodial balance to another merchant. Debit and credit happen in one transaction, so the two balances can never disagree.

{
  "to_email": "recipient@example.com",
  "amount": "100.00",
  "currency": "USDT",
  "blockchain": "bsc",
  "note": "invoice 4412",
  "otp": "123456"
}

{
  "id": "uuid",
  "direction": "out",
  "to_email": "recipient@example.com",
  "amount": "100.00000000",
  "currency": "USDT",
  "blockchain": "bsc",
  "status": "completed",
  "created_at": "2026-08-22T10: 00: 00Z"
}

List transfers in both directions. Each row carries a direction field of in or out.

<script src="https://fintrapay.io/js/fintrapay-checkout.js"></script>

curl -X POST https://fintrapay.io/v1/invoices \
  -H "X-API-Key: xfp_key_xxx" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <computed>" \
  -H "Content-Type: application/json" \
  -d '{"amount": "25.00", "mode": "custodial"}'

# Response includes: { "id": "abc-123-...", "checkout_url": "..." }

// After your backend creates the invoice and returns the invoice_id:

FintraPay.checkout({
  invoiceId: 'abc-123-...',   // Required — from your backend
  theme: 'dark',               // Optional — 'dark' or 'light'

  onSuccess: function(data) {
    // Payment confirmed!
    console.log('Paid! TX:', data.txHash);
    window.location.href = '/order-confirmed';
  },

  onCancel: function(data) {
    // Customer closed modal or clicked cancel
    // data.reason: 'closed' | 'backdrop' | 'escape' | 'cancel_button'
    console.log('Cancelled:', data.reason);
  },

  onExpired: function(data) {
    // 30-minute timer expired
    alert('Payment expired, please try again');
  }
});

// To programmatically close the modal:
FintraPay.close();

<!DOCTYPE html>
<html>
<head>
  <title>My Store</title>
  <script src="https://fintrapay.io/js/fintrapay-checkout.js"></script>
</head>
<body>
  <h1>Order #1234 — $25.00</h1>
  <button id="pay-btn">Pay with Crypto</button>

  <script>
    document.getElementById('pay-btn').onclick = async function() {
      // 1. Your backend creates the invoice
      var res = await fetch('/api/create-payment', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ order_id: 1234, amount: 25.00 })
      });
      var data = await res.json();

      // 2. Open FintraPay checkout modal
      FintraPay.checkout({
        invoiceId: data.invoice_id,
        theme: 'dark',
        onSuccess: function() {
          window.location.href = '/thank-you?order=1234';
        },
        onCancel: function() {
          // Customer can try again
        },
        onExpired: function() {
          alert('Payment expired — click Pay again');
        }
      });
    };
  </script>
</body>
</html>

Public view of an invoice: amount, accepted tokens and chains, the payment address once a coin has been selected, expiry, and current status. Safe to expose in a browser — it carries no merchant-private fields.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mode": "custodial",
  "amount": "100.00000000",
  "currency": "USDT",
  "blockchain": "tron",
  "payment_address": "TXyz123abc456def789...",
  "status": "underpaid",
  "received_amount": "60.00000000",
  "confirmations": 0,
  "accepts_top_up": true,
  "expires_at": "2026-03-30T13: 00: 00Z"
}

Customer picks the coin and chain they want to pay with. This is what assigns the payment address and starts a 30-minute payment window — never later than the invoice's existing expiry.

{ "currency": "USDT", "blockchain": "tron" }

Clear the customer's coin selection so they can choose a different chain — for example after realising they hold USDT on TRON rather than BSC.

• New: a plain-text rendering of this entire reference at https://fintrapay.io/llms-full.txt, and a short overview at /llms.txt. This page is a client-side app, so a crawler or LLM that does not run JavaScript previously read nothing from it at all. Both files render from the same source as the OpenAPI spec, so they cannot fall out of step with it.
• The OpenAPI spec is now also served at https://fintrapay.io/openapi.json. It was previously reachable only at /v1/docs.json, which robots.txt disallowed — so the one file built for machines was the one machines were told not to read.
• The spec gained 12 endpoints that this page already documented but it did not: the four per-contract Earn operations, wallet listing and creation, the three webhook-delivery endpoints, webhook subscriptions, and the three support-ticket endpoints.
• Documented endpoints that existed but were missing from this page: GET /v1/merchants/analytics, GET /v1/merchants/me/balance-adjustments, GET /v1/merchants/me/funding-wallets, GET /v1/merchants/me/deposit-wallets, POST /v1/merchants/me/kyc and POST /v1/merchants/me/regenerate-keys.

• New fee_deduction field on POST /v1/payouts/batch, applied to every recipient. The default, from_amount, keeps existing behaviour: each recipient receives their amount minus the per-recipient fee. Set from_balance when every recipient must receive exactly the amount listed — each recipient's fee is then debited from your balance on top, and batch.total_amount (the total debited) includes those fees.
• Corrected the documented POST /v1/payouts/batch response shape: the batch is returned under "batch" (with its id) next to the "payouts" array, not as top-level batch_id fields.

• GET /v1/invoices/{id} and GET /v1/invoices now document fee_rate (the rate stamped on the invoice at creation, not your current platform_fee_rate), refunded_amount (running total of pending/processed/completed refunds, which caps a further refund), and overpayment_status / overpayment_amount / sender_address, present once an invoice has been overpaid.
• GET /v1/refunds and its per-invoice counterpart now document the blockchain filter (accepted since it shipped, previously undocumented and silently ignored) and the summary object (refunded_amount, pending_count, completed_count — computed over every matching refund, not just the current page).
• New endpoint: GET /v1/earn/withdrawals — every interest withdrawal you have requested, across all your earn contracts, with its status. Interest withdrawals are paid by hand from the treasury wallet, so use this to track a request instead of assuming it completed.
• POST /v1/payouts/batch: documented the 8-decimal-place cap on each recipient's amount, and the per-recipient error shape on a 422 — one field error per bad row, keyed by array position (recipients[0].amount, recipients[2].to_address).
• GET /v1/checkout/{id} now documents accepts_top_up: true only when your invoice key's partial-payment policy is 'wait', so the checkout UI knows whether prompting the customer to send the remainder of an underpaid invoice is meaningful.
• New mode query param on GET /v1/merchants/stats: restricts invoice counts and volume to "custodial" or "non_custodial". Omit for both modes combined, the previous default behavior. Payout/withdrawal/earn counts are always custodial-only.

• PATCH /v1/payment-links/{id} now validates amount, min_amount and max_amount. Previously it validated nothing at all while POST /v1/payment-links did, so values the create call refused could be set on an existing link a moment later. A negative amount was accepted and stored, which did not create a negative invoice — it silently broke the link, so every customer hit an error at checkout while the link looked healthy in your dashboard. A non-numeric amount returned 500; it now returns 422 with a field error.
• min_amount and max_amount are validated as a pair against the values already stored, so updating only one of them can no longer leave a link whose minimum exceeds its maximum — a state in which every amount a customer entered was rejected.
• POST /v1/deposit-api/users rejects malformed metadata with 422 instead of 500. metadata is stored as JSON, and anything that was not valid JSON previously surfaced as a database error.
• Documented endpoints that already existed but were missing from this page: overpayment accept and refund, per-invoice refund history, public Earn rates, single payment link and subscription plan reads, the deposit-API list and update calls, internal transfers, and the three public checkout endpoints the hosted modal is built on.

• Withdrawal pricing changed: there is no flat withdrawal fee any more. You pay the network fee only, returned as est_gas_fee_usd. It was previously $0.05 plus the network fee.
• Payout pricing changed: $0.01 per payout plus the network fee, down from $0.04. On a batch the $0.01 applies per recipient, not once per batch.
• A network fee is charged on sweeps, payouts and withdrawals to cover the on-chain cost of moving your funds. POST /v1/fees/estimate returns the exact figure and the resulting net amount before you commit to a transfer.
• New fee_deduction field on POST /v1/withdrawals and POST /v1/payouts. The default, from_amount, keeps existing behaviour: the recipient receives the amount minus fees. Set from_balance when the recipient must receive exactly the amount you specified — fees are then debited from your balance on top.
• Invoice and payout responses carry the fee breakdown explicitly, so the amount that moves and the amount recorded always agree.

• Deposit crediting is now exactly-once and atomic. A confirmed deposit credits the user ledger, your merchant balance and the user total in a single transaction, and re-seeing an already-credited deposit moves no money and fires no webhook. deposit.confirmed previously fired again on every rescan.
• TRON and Solana deposits are detected. Addresses were issued on all seven chains but only the EVM chains were being watched, so a user paying USDT-TRC20 to their assigned address was never credited.
• A single transaction paying two of your users now records both. The deposit key is (tx_hash, destination) rather than tx_hash alone.
• Over-length external_user_id, email or label on deposit-API users return 422 rather than 500.
• Subscription billing anchors to the original billing day, so a subscription started on the 31st no longer drifts earlier each month.

• New webhook events: kyc.approved and kyc.rejected — fire when an admin decides on your identity verification. kyc.rejected carries a reason so you can surface it to the account owner and prompt a resubmission. Both include previous_status and an RFC3339 timestamp. Nothing signalled a KYC decision before this: no webhook, and no email either.
• KYC decision emails now actually send. Approval and rejection notices were written but never wired to the endpoint that changes the status, so merchants only discovered a decision by logging in.
• KYC document uploads are validated server-side: PNG, JPEG, WebP, GIF and PDF only, confirmed against the file’s magic bytes rather than the declared type. Limits are 10 documents, 5 MB each, 15 MB total. The stored file_type and file_size are now the server’s verified values, not the values you sent.
• The KYC submission endpoint accepts bodies up to 24 MB (other endpoints stay at the standard limit). A five-document company submission previously failed at the edge with an opaque error.

• Webhook retry: 3 attempts → 8 attempts over ~36h. New schedule [1m, 5m, 30m, 2h, 6h, 12h, 15h] — your endpoint can be down for a maintenance window without losing events.
• Withdrawal velocity caps per merchant — default $10K/24h + 5/hour. Admin override via PATCH /v1/admin/merchants/{id}/fees with new fields withdrawal_velocity_24h_usd and withdrawal_velocity_1h_count.
• New webhook event: merchant.security_alert — fires on admin password reset and 2FA reset. Payload includes action, actor_role, timestamp, and a hint string. Wire to PagerDuty / Slack so admin actions on your account are immediately visible.
• Bulk approve gating: items above $5K force per-item review. Bulk approve/reject now goes through the service layer so every item gets its own audit log row + webhook fire.
• Admin RBAC: 4 seeded roles (super_admin, finance_admin, support_admin, viewer) and 24 granular permissions. JWT now carries the perms array; 17 high-value admin routes (wallet transfers, payout/withdrawal approve, KYC, password/2FA reset) are gated per-permission. Existing admin tokens fall through to AdminOnly until next refresh.
• Wallet transfer dual-approval: any admin transfer above $1K is flagged requires_dual_approval=TRUE and stays pending until a SECOND admin (different from initiator) approves it. New routes: GET/POST /v1/admin/wallet/transfers/pending, /{id}/approve, /{id}/reject. Self-approval blocked at service + DB. 24h auto-expiry.
• JWT in browser sessions migrated to httpOnly cookies — xfp_session, xfp_refresh (HttpOnly+Secure+SameSite=Lax) plus xfp_csrf (readable double-submit token). New CSRFProtect middleware chained before JWTAuth. Bearer-token (SDK / server-to-server) path bypasses CSRF — no behaviour change for HMAC API callers.
• New endpoint: POST /v1/logout — blacklists current JWT and clears the session cookies. Body optional; identity comes from cookie or Authorization header.
• GET /v1/merchants/refresh now reads the xfp_refresh cookie if no body is supplied — refresh works without ever touching the token in JS.
• Stdlib DB migration runner shipped — scripts/migrations/{date}_{seq}_{name}.up.sql + scripts/migrate.sh. 5 migrations tracked in schema_migrations.

• Merchant-facing webhook delivery log — GET /v1/merchants/me/webhook-deliveries with filters: status, event, invoice_id, created_after, created_before
• Single-delivery detail — GET /v1/merchants/me/webhook-deliveries/{id} returns full payload + last response body
• Manual resend — POST /v1/merchants/me/webhook-deliveries/{id}/resend re-delivers the same envelope (same event_id) with a fresh signed timestamp
• Resend limits: 10/min per merchant, 30s cooldown per delivery, 20 lifetime resends per delivery
• Atomic resend — single SQL UPDATE enforces ownership + status + cooldown + cap (no TOCTOU race)
• Cross-merchant access returns 404 (not 403) to prevent ID enumeration
• Time-range filters added to GET /v1/invoices — created_after, created_before, updated_after, updated_before (RFC3339)
• Replay path on manual resends now uses fresh X-FintraPay-Timestamp — passes ±5 min freshness checks even when resending old deliveries
• New "Webhooks" page in merchant dashboard with delivery log + one-click resend

• Webhook subsystem rewrite — every declared event now actually fires (was 0 of 12 before)
• New v2 envelope: {id, event, timestamp, data} with unique event_id UUID for idempotency
• New headers: X-FintraPay-Event, X-FintraPay-Event-Id, X-FintraPay-Timestamp, X-FintraPay-Signature
• Signing changed: HMAC-SHA256 over (timestamp + "\n" + body) — defeats replay attacks
• 18 events now wired: invoice.{paid,confirmed,expired}, payout.{approved,broadcast,confirmed,failed}, withdrawal.{approved,broadcast,confirmed,failed}, earn.{interest_accrued,matured}, deposit.{detected,confirmed}, subscription.{created,cancelled}, payment.received (legacy alias)
• Per-merchant per-event subscription toggles — GET/PUT /v1/merchants/me/webhook-subscriptions (opt-out model, default = all enabled)
• Redis SETNX dedup on event_id (24h TTL) — duplicate publishes silently dropped
• Persisted delivery history — every attempt writes a webhook_deliveries row with full payload
• Durable retry — DB-backed fallback catches retries when Redis flushes
• New invoice.expired cron — fires within 60s of expires_at
• New invoice.confirmed cron — promotes paid → confirmed after per-chain time-based lag (CLAUDE.md confirmations × avg block time)
• Backward compatible: payment.received still emitted alongside invoice.paid

• Deep Integration API — persistent deposit addresses for merchant end-users
• New endpoints: /deposit-api/users (CRUD), /addresses (generate), /deposits (list), /balances
• Static address per user per chain — receives any supported stablecoin
• Deposit widget (fintrapay-deposit.js) — white-label embeddable UI with network selector, QR, copy
• Blockchain pollers enhanced to watch deposit_destinations alongside invoice addresses
• Deposit events: detecting → confirmed → swept, with 0.4% fee + gas fee
• Merchant dashboard: Deposit Users + Deposits pages
• Admin panel: Deposits overview with platform stats

• Subscriptions / Recurring Billing — plans, subscribers, auto-invoicing, trial periods, grace period, retry logic
• New endpoints: subscription-plans (CRUD), subscriptions (CRUD + cancel/pause/resume), /subscribe/{slug} (public)
• Billing cron: hourly — creates invoices, handles overdue, cancels after max retries, activates trials
• Merchant dashboard: Subscriptions page with plans + subscribers tabs
• Admin panel: Subscriptions overview with platform MRR stats
• Public subscribe page at /subscribe/{slug}

• Payment Links — reusable payment URLs with fixed or flexible amounts, QR codes, auto-invoice creation
• New endpoints: POST/GET /v1/payment-links, PATCH /v1/payment-links/{id}, GET/POST /v1/p/{slug}
• Merchant dashboard: Payment Links page with create/edit modal, copy URL, QR download, pause/archive
• Admin panel: Payment Links overview page with platform-wide stats
• Invoice source now includes "payment_link" alongside "api" and "manual"
• Public payment link page at /p/{slug} — branded, themed, mobile-responsive

• Hosted Checkout — drop-in iframe SDK (fintrapay-checkout.js) for embedded payments
• Invoice expiry changed from 60 minutes to 30 minutes
• Address reuse — re-selecting same coin+chain on multi-token invoice reuses cached address
• Multi-token invoices now expire after 30 minutes (previously never expired until selection)
• success_url and cancel_url now correctly applied from API key settings on all invoice types
• Cancel payment button on checkout page
• Return to merchant button after payment confirmation

• currency and blockchain now optional — omit both to let customer choose on checkout
• checkout_url returned in every invoice response
• success_url and cancel_url — per API key + per invoice override for redirects
• OpenAPI 3.0 spec at GET /v1/docs.json — machine-readable API documentation
• POST /checkout/{id}/reset — customer can change payment method after selecting
• Webhook secret visible in API Management page per key
• All 5 SDKs updated (Python, Node.js, PHP, Go, Java)

• Email OTP verification on registration
• KYC document upload (individual: 2 docs, company: 5 docs)
• Terms & conditions checkbox on signup
• Welcome email sent after account creation
• API base URL corrected to https://fintrapay.io/v1
• 5 EVM splitter contracts deployed on mainnet

• Initial API release
• 30+ endpoints across 6 resource types
• Python SDK (pip install fintrapay)
• HMAC-SHA256 authentication
• 7 blockchains, 6 stablecoins
• Per API key: display_name, base_currency, checkout_theme
• Fiat-to-stablecoin conversion (12 currencies)
• Real-time webhooks with HMAC verification