Documentation

FlowwPay API documentation

Everything you need to accept USDT deposits and send payouts — written so a first-time integrator or a QA tester can follow it end to end. No blockchain knowledge required.

Overview

1. Start here

FlowwPay lets you collect and send USDT over TRON or BNB Chain. Your server creates an invoice or payout, then receives signed status events.

  1. You call us to create a payment. We give you back a hosted payment page link and a deposit address.
  2. Your client pays on that page.
  3. We call you with a signed invoice.completed webhook once the money lands. That is your signal to credit the client in your CRM.
  4. To pay a client back, you create a payout. FlowwPay approves it in the admin portal and broadcasts it; the recipient gets the full amount and a flat $1 fee is debited on top.
Base URLs
  • Live: https://flowwpay.trade/api/public
  • All API paths below are relative to the live base URL.
  • Hosted payment page: https://payments.flowwpay.trade/pay/<code>

Everything is JSON over HTTPS. Amounts are plain decimal numbers in USDT (e.g. 25.5 means 25.5 USDT) — no wei, no satoshis.

Authentication

2. Get an API key

Create keys in the merchant portal under APIs. The key is shown once — store it in your backend secrets, and never in browser or mobile code.

Send it on every request as this header:

headers
Authorization: Bearer xp_live_xxxxxxxxxxxxxxxx
Never send funds on a test API key

Test keys (xp_test_…) create real deposit addresses on the live blockchain. Any USDT sent to a test invoice is treated as test activity — it will not be credited as merchant balance and cannot be recovered. Only switch to a xp_live_ key once your integration is fully verified.

Keys carry scopes. Payout approval is never done by API — it happens in the FlowwPay admin portal with 2FA:

FieldType / requiredWhat it means
paymentsscopeCreate deposits, read invoice status, and read balance.
withdrawals:createscopeCreate a payout, read its status, and read balance.
withdrawals:readscopeRead payout status and balance.
Deposits

3. Collect a deposit

POST /xp/v1/invoices — creates an invoice and returns a hosted payment link plus a deposit address.

curl
curl -X POST https://flowwpay.trade/api/public/xp/v1/invoices \
  -H "Authorization: Bearer $FLOWWPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "USDT",
    "network": "tron",
    "clientId": "trader_8412",
    "orderId": "order_1001",
    "redirectUrl": "https://your-site.com/thanks",
    "webhookUrl": "https://your-site.com/hooks/flowwpay"
  }'
FieldType / requiredWhat it means
amountnumber — requiredAmount in USDT you expect the client to send.
networkstring — requiredtron or bsc.
currencystring — optional (default USDT)Only USDT is supported.
clientIdstring — optional, 1–120 charsYour identifier for the trader/customer.
orderIdstring — optional, 1–120 charsYour idempotency key. Reusing it returns the original invoice with HTTP 200.
redirectUrlurl — optionalWhere the payer is sent after paying.
webhookUrlhttps url — optionalPer-invoice webhook override.
201 response
{
  "success": true,
  "invoiceId": "0f6b...c21",
  "code": "Ab12Cd34",
  "payUrl": "https://payments.flowwpay.trade/pay/Ab12Cd34",
  "depositAddress": "TXk...9fA",
  "network": "tron",
  "currency": "USDT",
  "amount": 500,
  "amountReceived": 0,
   "fee": 0,
   "feeRule": { "percent": 0.5, "minimum": 1 },
   "net": 0,
  "status": "pending",
  "orderId": "order_1001",
  "clientId": "trader_8412",
   "txHash": null,
   "expiresAt": "2026-08-03T12:30:00Z",
   "completedAt": null,
   "createdAt": "2026-08-03T00:30:00Z"
}

Redirect the client to payUrl, or show depositAddress in your own UI. Check status any time with GET /xp/v1/invoices/<invoiceId> — statuses are pending, completed, expired and under_review.

Deposits

4. Check payment status

Use the invoice ID or pay code. Webhooks are the fastest signal, while this endpoint is useful for reconciliation.

curl
curl https://flowwpay.trade/api/public/xp/v1/invoices/<invoiceId-or-code> \
  -H "Authorization: Bearer $FLOWWPAY_API_KEY"
Payment matching
  • Full payment: an invoice completes when the cumulative amount received is within 0.5% of the requested amount (with a 0.01 USDT allowance).
  • Partial payment: the same address remains assigned until expiry, so the payer can top up.
  • Expiry: the address is reserved for 12 hours. A final chain check runs before expiry.
  • Late or partial funds: they are held for manual review rather than credited automatically.

Statuses you will see:

FieldType / requiredWhat it means
pendingstatusWaiting for funds or a partial-payment top-up.
completedstatusFunds confirmed and the merchant ledger credited.
under_reviewstatusPartial or late funds need manual review. Do not credit the client yet.
expiredstatusThe 12-hour payment window ended without a completed deposit.
Payouts

5. Send a payout

Create a payout by API. It stays pending until FlowwPay approves it in the admin portal (with 2FA) — there is no approval endpoint. The recipient receives the full amount; a flat $1 fee is added, so amount + $1 is debited from your balance.

1. create
curl -X POST https://flowwpay.trade/api/public/xp/v1/payouts \
  -H "Authorization: Bearer $FLOWWPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150,
    "currency": "USDT",
    "network": "tron",
    "recipientAddress": "TXk...9fA",
    "referenceId": "payout_7781"
  }'

referenceId is optional, 1–120 characters, and idempotent. Reusing it returns the original payout. The amount must be greater than $1.

201 response
{
  "success": true,
  "payoutId": "7b54...9a1",
  "network": "tron",
  "currency": "USDT",
  "amount": 150,
  "fee": 1,
  "netAmount": 149,
  "recipientAddress": "TXk...9fA",
  "referenceId": "payout_7781",
  "status": "pending",
  "txHash": null,
  "failureReason": null,
  "approvedAt": null,
  "completedAt": null
}
2. read status
curl https://flowwpay.trade/api/public/xp/v1/payouts/<payoutId> \
  -H "Authorization: Bearer $FLOWWPAY_API_KEY"
FieldType / requiredWhat it means
pendingstatusCreated, awaiting FlowwPay approval.
approved / broadcastingstatusApproved and being sent.
completedstatusSent on-chain.
rejectedstatusDeclined before broadcast. Balance restored.
failedstatusNot sent. Balance restored.
Ledger

6. Read your balance

GET /xp/v1/ledger/balance returns the merchant's current position and all-time completed totals.

curl
curl https://flowwpay.trade/api/public/xp/v1/ledger/balance \
  -H "Authorization: Bearer $FLOWWPAY_API_KEY"
200 response
{
  "success": true,
  "currency": "USDT",
  "availableBalance": 824.5,
  "pendingPayouts": 150,
  "totalVolume": 1250,
  "totalWithdrawn": 275,
  "totalSent": 273,
  "depositFees": 1.5,
  "withdrawalFees": 2,
  "totalFees": 3.5
}

totalWithdrawn includes the flat payout fees; totalSent is what recipients received.

availableBalance is the combined total. availableByNetwork.tron and availableByNetwork.bsc are the chain-specific balances. Withdrawals and settlements are limited to the selected chain; other-chain or unallocated funds cannot cover them.

Webhooks

7. Webhooks

Add your endpoint under Webhooks and copy the signing secret (whsec_…). A configured active endpoint is required to sign deliveries, including invoice-specific URL overrides. We POST JSON and retry up to 3 times total, 2 seconds apart, with a 10 second timeout per attempt. Any 2xx response means delivered.

headers we send
Content-Type: application/json
 X-FlowwPay-Event: invoice.completed
X-FlowwPay-Signature: 9f2a...   # hex hmac-sha256 of the raw body, no prefix
X-FlowwPay-Timestamp: 1754225400000
 X-FlowwPay-Attempt: 1
 X-FlowwPay-Resend: true   # present only on a manual resend
FieldType / requiredWhat it means
invoice.createdeventInvoice created and address assigned.
invoice.completedeventFunds confirmed and merchant ledger credited.
invoice.expiredeventInvoice expired without a completed payment.
invoice.under_revieweventPartial or late funds require manual review.
payout.createdeventPayout reserved and awaiting admin approval.
payout.completedeventPayout completed on-chain.
payout.rejectedeventPayout rejected before broadcast; reserved balance restored.
payout.failedeventPayout failed; reserved balance restored.
invoice.completed body
{
   "event": "invoice.completed",
  "timestamp": 1754225400000,
  "data": {
     "invoiceId": "0f6b...c21",
     "code": "xp_9xQ2",
     "payUrl": "https://payments.flowwpay.trade/pay/xp_9xQ2",
     "depositAddress": "TXk...9fA",
     "amountReceived": 500,
    "amount": 500,
     "fee": 2.5,
     "feeRule": { "percent": 0.5, "minimum": 1 },
     "net": 497.5,
     "currency": "USDT",
    "network": "tron",
    "status": "completed",
    "txHash": "a91f...",
     "orderId": "order_1001",
     "clientId": "trader_8412",
    "completedAt": "2026-08-03T12:10:22Z",
     "createdAt": "2026-08-03T00:30:00Z"
  }
}
payout.completed body
{
   "event": "payout.completed",
  "timestamp": 1754225400000,
  "data": {
     "payoutId": "7b54...9a1",
    "network": "tron",
     "currency": "USDT",
     "amount": 150,
     "fee": 1,
     "netAmount": 149,
     "recipientAddress": "TXk...9fA",
     "referenceId": "payout_7781",
     "status": "completed",
    "txHash": "a91f...",
     "failureReason": null,
     "completedAt": "2026-08-03T12:10:22Z"
  }
}

Rules of thumb: reply 200 immediately and process asynchronously; treat events as at-least-once (deduplicate on invoiceId or payoutId + event); never trust a webhook you have not signature-verified.

Security

8. Verify the signature

Compute an HMAC-SHA256 of the raw request body using your webhook secret and compare it to X-FlowwPay-Signature.

node.js / express
import crypto from "node:crypto";

app.post("/hooks/flowwpay",
  express.raw({ type: "application/json" }),   // raw body is required
  (req, res) => {
    const expected = crypto
      .createHmac("sha256", process.env.FLOWWPAY_WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

    const given = req.get("X-FlowwPay-Signature") ?? "";
    const ok =
      given.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));

    if (!ok) return res.status(401).send("bad signature");

    const { event, data } = JSON.parse(req.body.toString());
    res.sendStatus(200);          // ack first
    handleEvent(event, data);     // then process
  });
python / flask
import hmac, hashlib

expected = hmac.new(SECRET.encode(), request.get_data(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-FlowwPay-Signature", "")):
    abort(401)
Testing

9. Integration checklist

Complete this checklist before processing client funds. Use credentials and an environment supplied by FlowwPay for testing; never assume a test-prefixed key makes a live-chain transfer fake.

  1. Create an API key with the scopes you need; save it in your test config.
  2. Register your test webhook URL and copy the secret.
  3. Create a deposit via API — assert you get 201 and a payUrl.
  4. Send the exact amount — assert invoice.completed arrives and your CRM credits the client once.
  5. Test partial payment and expiry — assert no automatic client credit is applied.
  6. Send a deliberately wrong signature — assert your endpoint returns 401.
  7. Replay the same webhook twice — assert the client is credited only once.
  8. Create a payout — assert it returns pending and your balance drops.
  9. Have FlowwPay reject a test payout — assert the reserved balance is restored.
  10. Use a fresh live key and re-run the happy path with a small amount.
Tooling

10. Postman collection

Download the collection, import it into Postman (File → Import), then open the Variables tab and set baseUrl and apiKey. Every request is pre-wired; the included scripts save invoiceId and payoutId from create responses.

Download flowwpay-xp-v2.postman_collection.json
variables
baseUrl     = https://flowwpay.trade/api/public
apiKey      = <key with payments + withdrawals:create + withdrawals:read>
Reference

11. Errors & troubleshooting

Errors always look like { "success": false, "error": { "code": "<code>", "message": "<detail>" } } with a matching HTTP status.

FieldType / requiredWhat it means
unauthorized — 401authAuthorization header is missing, malformed, invalid, or revoked.
insufficient_scope — 403authThe key lacks every scope accepted by this endpoint.
invalid_request — 400requestA field is missing, invalid, or outside its allowed length/range.
invalid_address — 400payoutThe recipient address does not match the selected network.
amount_too_small — 400payoutPayout amount must be greater than the flat $1 fee.
merchant_inactive — 403invoiceThe merchant account is not active.
not_found — 404requestThe id does not exist for this merchant.
insufficient_balance — 422payoutThe merchant's available USDT on the requested network cannot cover the recipient amount plus the $1 fee. Funds on another network cannot be used.
pool_exhausted — 503invoiceNo deposit address is currently available; retry shortly.
internal_error — 500serverUnexpected error; retry safely using the same orderId or referenceId.

Still stuck? Send us the invoiceId or payoutId and the approximate timestamp — every API call and webhook delivery is logged on our side.