Quickstart

A payment goes from your server to the buyer’s wallet in three steps: you create it, the buyer pays on the hosted checkout, and FlowPayra posts the settlement to the ledger and notifies you.

Install the SDK

npm add @flowpayra/sdk

Node 18 or newer. The SDK signs every request with the exact scheme the server enforces, so you never assemble the canonical string yourself.

Create a payment

import { FlowpayraClient } from '@flowpayra/sdk';

const flowpayra = new FlowpayraClient({
  baseUrl: 'https://api.flowpayra.com',
  keyId: process.env.FLOWPAY_KEY_ID!,
  secret: process.env.FLOWPAY_SECRET!,
});

const payment = await flowpayra.payments.create({
  merchant_order_no: 'order-1042',
  quotes: {
    cur_usdc: { amount: '125.00', chain_ids: ['base'] },
    cur_usdt: { amount: '125.00', chain_ids: ['tron'] },
  },
  memo: 'Pro plan · 12 months',
  redirect_url: 'https://your-store.example/orders/1042',
});

console.log(payment.checkout_url);

Three fields deserve attention:

• merchant_order_no is unique per merchant. Reusing it returns the existing payment rather than creating a second one, which makes retries safe.
• quotes is an explicit map of currency to amount. FlowPayra never converts between currencies on your behalf and never widens the set of accepted assets. You state exactly what you will accept. See Amounts and precision.
• redirect_url is where the checkout sends the buyer when they are done. It must be an absolute http(s) URL without credentials. Omitting it leaves the buyer on a terminal page with no way back to you.

Send the buyer to checkout

Redirect to payment.checkout_url, or open it in a new tab. The page is hosted by FlowPayra and shows your merchant name, the order reference, the exact amount to send, and the network warning for the asset the buyer picks.

Append ?mode=light or ?mode=dark to force a theme. Without it the checkout follows the buyer’s system preference.

Know when it is paid

Poll the payment, or receive a signed webhook:

const settled = await flowpayra.payments.get(payment.id);
if (settled.status === 'settled') {
  // Release the goods.
}

Treat settled as the only status that means the money is yours. paid means the chain confirmed it; settled means the ledger posted it, including splits and fees. Hosted checkout lifecycle walks through every status, including underpayment.