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.
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.
- You call us to create a payment. We give you back a hosted payment page link and a deposit address.
- Your client pays on that page.
- We call you with a signed
invoice.completedwebhook once the money lands. That is your signal to credit the client in your CRM. - 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.
- 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.
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:
Authorization: Bearer xp_live_xxxxxxxxxxxxxxxxTest 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:
| Field | Type / required | What it means |
|---|---|---|
| payments | scope | Create deposits, read invoice status, and read balance. |
| withdrawals:create | scope | Create a payout, read its status, and read balance. |
| withdrawals:read | scope | Read payout status and balance. |
3. Collect a deposit
POST /xp/v1/invoices — creates an invoice and returns a hosted payment link plus a deposit address.
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"
}'| Field | Type / required | What it means |
|---|---|---|
| amount | number — required | Amount in USDT you expect the client to send. |
| network | string — required | tron or bsc. |
| currency | string — optional (default USDT) | Only USDT is supported. |
| clientId | string — optional, 1–120 chars | Your identifier for the trader/customer. |
| orderId | string — optional, 1–120 chars | Your idempotency key. Reusing it returns the original invoice with HTTP 200. |
| redirectUrl | url — optional | Where the payer is sent after paying. |
| webhookUrl | https url — optional | Per-invoice webhook override. |
{
"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.
4. Check payment status
Use the invoice ID or pay code. Webhooks are the fastest signal, while this endpoint is useful for reconciliation.
curl https://flowwpay.trade/api/public/xp/v1/invoices/<invoiceId-or-code> \
-H "Authorization: Bearer $FLOWWPAY_API_KEY"- 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:
| Field | Type / required | What it means |
|---|---|---|
| pending | status | Waiting for funds or a partial-payment top-up. |
| completed | status | Funds confirmed and the merchant ledger credited. |
| under_review | status | Partial or late funds need manual review. Do not credit the client yet. |
| expired | status | The 12-hour payment window ended without a completed deposit. |
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.
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.
{
"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
}curl https://flowwpay.trade/api/public/xp/v1/payouts/<payoutId> \
-H "Authorization: Bearer $FLOWWPAY_API_KEY"| Field | Type / required | What it means |
|---|---|---|
| pending | status | Created, awaiting FlowwPay approval. |
| approved / broadcasting | status | Approved and being sent. |
| completed | status | Sent on-chain. |
| rejected | status | Declined before broadcast. Balance restored. |
| failed | status | Not sent. Balance restored. |
6. Read your balance
GET /xp/v1/ledger/balance returns the merchant's current position and all-time completed totals.
curl https://flowwpay.trade/api/public/xp/v1/ledger/balance \
-H "Authorization: Bearer $FLOWWPAY_API_KEY"{
"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.
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.
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| Field | Type / required | What it means |
|---|---|---|
| invoice.created | event | Invoice created and address assigned. |
| invoice.completed | event | Funds confirmed and merchant ledger credited. |
| invoice.expired | event | Invoice expired without a completed payment. |
| invoice.under_review | event | Partial or late funds require manual review. |
| payout.created | event | Payout reserved and awaiting admin approval. |
| payout.completed | event | Payout completed on-chain. |
| payout.rejected | event | Payout rejected before broadcast; reserved balance restored. |
| payout.failed | event | Payout failed; reserved balance restored. |
{
"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"
}
}{
"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.
8. Verify the signature
Compute an HMAC-SHA256 of the raw request body using your webhook secret and compare it to X-FlowwPay-Signature.
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
});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)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.
- Create an API key with the scopes you need; save it in your test config.
- Register your test webhook URL and copy the secret.
- Create a deposit via API — assert you get 201 and a
payUrl. - Send the exact amount — assert
invoice.completedarrives and your CRM credits the client once. - Test partial payment and expiry — assert no automatic client credit is applied.
- Send a deliberately wrong signature — assert your endpoint returns 401.
- Replay the same webhook twice — assert the client is credited only once.
- Create a payout — assert it returns
pendingand your balance drops. - Have FlowwPay reject a test payout — assert the reserved balance is restored.
- Use a fresh live key and re-run the happy path with a small amount.
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.
baseUrl = https://flowwpay.trade/api/public
apiKey = <key with payments + withdrawals:create + withdrawals:read>11. Errors & troubleshooting
Errors always look like { "success": false, "error": { "code": "<code>", "message": "<detail>" } } with a matching HTTP status.
| Field | Type / required | What it means |
|---|---|---|
| unauthorized — 401 | auth | Authorization header is missing, malformed, invalid, or revoked. |
| insufficient_scope — 403 | auth | The key lacks every scope accepted by this endpoint. |
| invalid_request — 400 | request | A field is missing, invalid, or outside its allowed length/range. |
| invalid_address — 400 | payout | The recipient address does not match the selected network. |
| amount_too_small — 400 | payout | Payout amount must be greater than the flat $1 fee. |
| merchant_inactive — 403 | invoice | The merchant account is not active. |
| not_found — 404 | request | The id does not exist for this merchant. |
| insufficient_balance — 422 | payout | The 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 — 503 | invoice | No deposit address is currently available; retry shortly. |
| internal_error — 500 | server | Unexpected 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.