Wolf Pay API (v1)

Create stablecoin payments from your server, send customers to a hosted checkout, and get signed webhooks when payments settle.

Base URL: https://wolf-pay-five.vercel.app/api/v1 Status: test mode is open. Live mode is built and opens once our custodian (Bridge) goes live; until then live keys get live_mode_unavailable.

Pricing

1% per payment, at least 3.00, never more than the payment received (a 2.00 payment costs 2.00). The minimum applies once per payment, even if the customer pays in parts. No setup or monthly fees. Fees are kept in your balance as fees_owed and settled when you pay out. Refunds don't return the fee.

Authentication

Every request needs a secret key from Dashboard → Developers:

Authorization: Bearer wp_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• wp_test_… keys create test payments. No real money moves.
• wp_live_… keys create real payments. They need a business verified in Dashboard → Settings; until then (and until live mode opens) they get live_mode_unavailable.
• Keep keys on your server. Never put them in a browser, an app, or a public repo.
• The API is server-to-server: no CORS headers are sent.

Wolf Pay stores only a SHA-256 hash of each key, so a lost key can't be shown again. Revoke it and create a new one.

Requests and responses

• Send JSON with Content-Type: application/json.
• Amounts are decimal strings ("25.50") with up to 6 decimals, so nothing is lost to floating-point rounding. Plain numbers are accepted too.
• Responses are JSON. Every response has a Wolf-Request-Id header. Include it when you contact support.
• Timestamps are ISO 8601 in UTC.

Errors

{ "error": { "type": "invalid_request", "message": "amount: Use a positive decimal…", "param": "amount" } }

Idempotency

Send Idempotency-Key: <your unique id> (up to 255 printable characters, e.g. your order id) with POST /payments. Retrying with the same key returns the original payment instead of creating a second one, even if two requests race. Keys are scoped to your business and mode.

The payment object

{
  "id": "pay_8Hq2kZ0rT4mW9xV1cN7bL3sD",
  "object": "payment",
  "livemode": false,
  "status": "pending",
  "amount": "25.5",
  "amount_paid": "0",
  "amount_due": "25.5",
  "currency": "USDT",
  "network": "tron",
  "address": "TQ7m…9fKp",
  "checkout_url": "https://wolf-pay-five.vercel.app/pay/pay_8Hq2kZ0rT4mW9xV1cN7bL3sD",
  "order_id": "1001",
  "description": "Hoodie",
  "customer_email": "sam@example.com",
  "redirect_url": "https://yourstore.com/thanks",
  "metadata": { "cart": "42" },
  "paid_with": null,
  "expires_at": "2026-10-20T15:30:00+00:00",
  "paid_at": null,
  "canceled_at": null,
  "created_at": "2026-10-20T14:30:00+00:00"
}

status

Coins and networks

All of these work in test mode. Live mode supports USDT on tron, ethereum and solana, and USDC on ethereum, base, polygon, arbitrum and solana. Live amounts must be whole cents ("25.50", not "25.505").

paid_with is set when the customer paid with another coin at checkout (see Paying with other coins below), for example { "currency": "BTC", "amount": "0.00031875" }. You still received amount_paid in currency, exactly as with any payment; it's only there so you can show the customer what they sent. Otherwise it's null.

Create a payment

POST /payments → 201 with a payment object.

curl https://wolf-pay-five.vercel.app/api/v1/payments \
  -H "Authorization: Bearer $WOLF_PAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1001" \
  -d '{"amount": "25.50", "currency": "USDT", "network": "tron", "order_id": "1001", "redirect_url": "https://yourstore.com/thanks"}'

Send the customer to checkout_url, or show address and amount_due in your own UI.

Retrieve a payment

GET /payments/:id → 200 with a payment object.

List payments

GET /payments → 200

{ "object": "list", "data": [ { "id": "pay_…", "object": "payment", "…": "…" } ], "has_more": true }

Newest first. To page, pass the last id in data as starting_after while has_more is true.

Cancel a payment

POST /payments/:id/cancel → 200 with the payment, now canceled. Only pending payments can be canceled (otherwise 409 invalid_state).

Balance

GET /balance → 200

{
  "object": "balance",
  "livemode": false,
  "data": [
    {"currency": "USDT", "available": "97", "fees_owed": "3", "payouts_pending": "0"},
    {"currency": "USDC", "available": "0", "fees_owed": "0", "payouts_pending": "0"}
  ]
}

• available: what you can pay out now, after Wolf Pay's fee.
• fees_owed: Wolf Pay's fees so far. They're settled from your balance when you next send a payout in that coin.
• payouts_pending: requested payouts not yet delivered.

Payouts

Payouts send your balance to one of your own wallet addresses or, once your business is verified, your own bank accounts (ACH or wire in USD, SEPA in EUR). They're created in the dashboard only (Wallet → Send payout, by an owner or admin), never with an API key, so a leaked key can't move money. POST /payouts answers 405 method_not_allowed. The API can read them:

• GET /payouts/:id → the payout.
• GET /payouts?limit=20&starting_after=po_… → a list, newest first, paged like payments.

{
  "id": "po_8Hq2…",
  "object": "payout",
  "livemode": false,
  "status": "completed",
  "amount": "50",
  "amount_sent": "50",
  "fee_settled": "3",
  "currency": "USDT",
  "network": "tron",
  "address": "TDd…",
  "bank": null,
  "destination_id": "6c1f…",
  "source": "dashboard",
  "batch_id": null,
  "failure_reason": null,
  "tx_hashes": ["9f2c…"],
  "created_at": "2026-10-20T22:50:31.003Z",
  "completed_at": "2026-10-20T22:51:12.400Z"
}

A payout to a bank account has network and address set to null and a bank object instead. bank.currency is what arrives (usd or eur; our custody partner converts the stablecoin at its rate), and bank.label shows only the last 4 digits:

"network": null,
"address": null,
"bank": { "rail": "ach", "currency": "usd", "label": "Chase ••••9123 (ACH, USD)" },

For bank payouts tx_hashes lists the stablecoin side only. ACH and SEPA usually arrive in 1 to 2 business days, wires the same day.

Rules: at least 1.00, at most 2 decimals, up to your available balance. A new payout address or bank account can receive live payouts 24 hours after it's added. Live payouts of 1,000 or more need a code we email to the person sending them.

Bulk payouts (payroll, contractors, affiliates)

Pay many people at once from your balance: Dashboard → Payouts → New bulk payout. Upload a CSV (or paste one) with these columns, in any order:

• Every row is checked before anything is saved, and problems are listed by row number. Up to 500 payouts per batch, all in one coin (USDT or USDC).
• You get a draft to review. Nothing moves until an owner or admin sends it. Sending is all or nothing: every payout is created, or none is.
• New people are saved as recipients (Payouts → Recipients). Like your own payout addresses, a new recipient can receive live payouts 24 hours after being added, and owners get an email. Live batches of 1,000 or more need a code we email to the person sending them.
• Fee: $1 per payout (shown before you send), on top of the amounts.
• Each row becomes an ordinary payout with source: "batch" and the batch's batch_id, so payout.* webhooks and GET /payouts cover them too.
• Let people add their own wallet. Instead of typing an address, an owner or admin can use Payouts → Recipients → Ask by email. We email the person a one-time link (valid 7 days) where they pick the network and paste their address; no account needed. It's checked like any other address, owners get an email, and the 24-hour hold applies. New address on a recipient asks them for a replacement; the old address is removed once they save it.

Bulk payouts are read-only in the API (POST /payout_batches answers 405):

• GET /payout_batches?limit=20&starting_after=pb_… → a list, newest first, paged like payments.
• GET /payout_batches/:id → the batch plus its payouts (empty while it's a draft).

{
  "id": "pb_3kT9…",
  "object": "payout_batch",
  "livemode": false,
  "status": "submitted",
  "name": "October payroll",
  "currency": "USDT",
  "item_count": 3,
  "total_amount": "350.5",
  "fee_total": "3",
  "progress": { "completed": 2, "partially_completed": 0, "failed": 0, "in_progress": 1, "amount_sent": "300.5" },
  "created_at": "2026-10-27T09:12:44.120Z",
  "submitted_at": "2026-10-27T09:15:02.871Z",
  "payouts": [
    { "id": "po_…", "object": "payout", "status": "completed", "amount": "100", "recipient": "Ana Lopez", "reference": "INV-1", "batch_id": "pb_3kT9…", "…": "…" }
  ]
}

status is draft (nothing sent yet), submitted or canceled. Each entry in payouts is a full payout object plus recipient (the name) and reference.

Every owner gets an email for each live payout. Test payouts complete within a minute and move nothing real.

source is dashboard or schedule (automatic payouts, set up in Balances: daily or weekly, the whole available balance above a minimum).

Refunds

POST /refunds refunds a paid payment from your balance.

curl https://wolf-pay-five.vercel.app/api/v1/refunds \
  -H "Authorization: Bearer wp_test_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-1001" \
  -d '{"payment_id": "pay_…", "amount": "25.50", "reason": "Out of stock"}'

• Back to the payer (no address): sent right away, status: "pending".
• Any other address: status: "requires_approval". An owner or admin approves or rejects it on the payment's page in the dashboard; in live mode no sooner than approvable_after (24 hours later). This way a leaked API key can't redirect refunds to someone else's wallet. Owners are emailed about every live refund.
• You can refund up to what the payment received, minus earlier refunds, and up to your available balance. Wolf Pay's fee isn't returned.
• GET /refunds/:id, and GET /refunds?payment_id=pay_…&limit=20&starting_after=re_….
• Payments show amount_refunded (delivered so far).

{"id": "re_7Kq…", "object": "refund", "livemode": false, "status": "pending",
 "payment_id": "pay_…", "amount": "25.5", "amount_sent": "0", "currency": "USDT",
 "network": "tron", "address": "TPay…", "reason": "Out of stock", "source": "api",
 "approvable_after": null, "failure_reason": null, "tx_hashes": [],
 "created_at": "…", "completed_at": null}

Statuses are the payout ones (pending, processing, completed, partially_completed, failed, canceled) plus requires_approval.

Hosted checkout

checkout_url (/pay/<id>) is a mobile-friendly page with the amount, a QR code, the address, a countdown, and live status. It updates by itself and sends the customer to redirect_url five seconds after a successful payment.

The payment id is a 143-bit random token, so the link is safe to share with the customer but should be treated like a receipt link: anyone with it can see the amount and address (not your metadata or the customer's email).

Test mode: the checkout shows buttons to simulate Pay in full, Pay too little, Pay too much and Let it expire. They trigger the same events and webhooks as real payments will.

Paying with other coins

Customers can also pay with BTC, ETH, SOL, TRX, BNB, LTC, DOGE or XRP. Nothing changes for you: you create the payment in USDT or USDC as usual, and that's what you receive.

• At checkout the customer picks a coin and gives an address of theirs for refunds. Wolf Pay gets a quote from NEAR Intents, a conversion network, for exactly the amount still due.
• The customer sends the coin to the address shown. NEAR Intents converts it and sends the USDT/USDC straight to the payment's own address, so the payment turns paid the usual way, with the usual events and the usual 1% fee (at least $3).
• The price includes the network fees. Any coin not needed is sent back to the customer, and so is everything if the conversion can't go through before the quote's deadline (30 minutes, 60 for LTC/DOGE, 90 for BTC). The payment stays open while a conversion is in progress.
• Refunds of these payments need an address from you: the money came from the conversion network, not from the customer's own wallet, so Wolf Pay never refunds "to the sender".
• Owners and admins can turn this off in Settings → Checkout. In live mode it's switched on platform-wide once our custody partner has approved the flow, and a single payment can be at most $10,000.

In test mode the quote uses real market prices but a made-up address, and the checkout shows buttons to simulate the conversion working or failing.

Payment links and invoices (no code)

Merchants without a developer can get paid from Dashboard → Links & invoices:

• Payment link (/l/plink_…): a fixed price anyone with the link can pay, any number of times. Share it in a bio, a chat or an email. Turn it off at any time.
• Invoice (/i/inv_…): one bill for one customer with line items, a due date and a note. Numbered INV-0001, INV-0002… (TEST-0001 in test mode). Live invoices can be emailed to the customer from Wolf Pay; test invoices never are.

The customer picks one of the networks you allowed, and Wolf Pay creates a normal payment for it and opens the hosted checkout. Everything else is the same as an API payment: the payment.* webhooks, the ledger, refunds. You can tell these payments apart by metadata.payment_link (and metadata.invoice_number for invoices); order_id is the invoice number or link id.

• A link's checkout lasts 30 minutes. At most 25 live (50 test) payments can be open on one link at a time, so a shared link can't tie up your deposit addresses.
• An invoice has one payment open at a time; reopening the invoice continues it. It is marked paid, and an invoice.paid event is sent, when a payment for it is paid in full. Voiding an invoice cancels any payment still waiting for money.

Webhooks

Add an endpoint in Dashboard → Developers → Webhooks. You get a signing secret (whsec_…) once. Endpoints must be https:// on a public domain name (no IP addresses, custom ports, or localhost; use a tunnel like ngrok for local development).

Events

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: WolfPay-Webhooks/1.0
Wolf-Event-Id: evt_3kD9…
Wolf-Signature: t=1792500000,v1=5f2b…c9

{"id": "evt_3kD9…", "object": "event", "type": "payment.paid", "livemode": false,
 "created_at": "2026-10-20T14:31:02+00:00", "data": {"object": { …payment object… }}}

data.object is the payment, payout, refund or invoice as it was when the event happened.

Verify the signature

v1 is the hex HMAC-SHA256 of <t>.<raw request body> with your signing secret. Use the raw body exactly as received. Re-serialized JSON won't match.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWolfPay(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false; // reject replays older than 5 minutes

  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Delivery and retries

• Events go out within about 10 seconds.
• Answer with any 2xx within 10 seconds. Do slow work after responding.
• Anything else (non-2xx, timeout, connection error) is retried after 1 min, 5 min, 30 min, 2 h, 5 h, 10 h and 10 h: 8 attempts over about 28 hours. Then the delivery is marked failed.
• Deliveries can arrive more than once or out of order. Use Wolf-Event-Id to skip duplicates, and fetch the payment (GET /payments/:id) if you need the latest status.
• The dashboard shows the last deliveries with their HTTP status.

Limits (current)

• 25 active API keys and 10 webhook endpoints per business.
• 600 requests a minute per API key (429 rate_limited above that, with a Retry-After header). Ask us if you need more.