Refunds
POST /v1/payments/:id/refund, with x-api-key. The body is optional:
{
"amount": "5",
"reason": "Customer request"
}
| Field | Rules |
|---|---|
amount | Optional decimal string in token units. Leave it out to refund everything that remains. |
reason | Optional, up to 1000 characters |
toAddress | Optional, up to 128 characters. The default is the address that sent the payment's first transfer. |
- Only payments in
confirmedoroverpaidcan be refunded; anything else returns409. Anunderpaidpayment cannot be refunded through the API. - The most you can refund is
receivedAmount− the platform fee thru keeps − earlier refunds.GET /v1/payments/:idreturns it asrefundableAmount("0"for a payment that cannot be refunded, including a token the refund route cannot send; see below). A largeramountreturns400with the maximum. A refund never returns the platform fee. The fee thru keeps isfeeAmountless any part thru decided not to collect (see "The platform fee" below); both are0for every account today. - To return only an overpayment, refund
receivedAmount−expectedAmount. - If the payer sent from an exchange, the default address belongs to the exchange. Ask the payer for an address and pass
toAddress. - Refunds currently send the chain's NATIVE asset only. The refund is sent on the payment's own chain, but if the payment's token is not that chain's native asset the call is a
400—"<Chain> withdrawals currently support native <TOKEN> only". In practice that means an Arc USDC payment can be refunded (USDC is Arc's native asset) while a USDC payment on Base or BNB Chain, a Sui USDC payment and a Robinhood USDG payment cannot. Use an off-platform transfer for those and reconcile it yourself. - A refund is funded from a payment address that still holds a balance — not from your settlement wallet and not from thru. thru looks for one of your own payments on that chain whose custodial address has not been swept yet and has enough for the amount plus gas. If none does, the call is a
409. So in an account where the auto-sweep is keeping up, refunds will usually fail: the money is already in your settlement wallet, and thru cannot pull it back. Plan refunds as something you send from your own wallet, and treat the API as a convenience for the window before a payment is swept. - If sending fails for any other reason the call returns
409with the reason. - A full refund (all that remains) moves the payment to
refundedand firespayment.refunded. If the payment came from a checkout session, the session moves tofailedandcheckout.session.failedfires. A partial refund fires no event. GET /v1/refundslists your newest 100 refunds. There is no pagination and noupdatedAfteron this endpoint, so it is not a complete recovery path for a missedpayment.refunded. A full refund also flips the payment torefunded, which moves that payment'supdatedAt— so the payments walk will show you the payment even when the refund list has rolled past 100. A partial refund emits no event at all; record it when you create it.
Receipts and credit notes
thru issues an accounting document whenever money is credited to a payment — on every path, not only invoices. You do not ask for it and the customer does not either.
| Document | Issued when | What its amount is |
|---|---|---|
receipt | The first money documented on a payment | The transfers it covers. One per payment, ever. |
supplement | Money arrives after a document already covered the earlier money | The delta only |
credit_ | Any refund, including a partial one | The amount refunded |
Nothing issued is ever rewritten, and that is the reason for the chain rather than one updatable document. A receipt has to follow the amount actually received AND stay true once a customer is holding the PDF; both cannot hold if the row is edited. Two ordinary situations grow the amount after a receipt exists — an underpaid payment topping up, and a late transfer recovered by support weeks later — so the chain is the common case, not an exotic one.
Every document also carries receivedAmountAtIssue, the running total as it stood. Show a
customer the newest document's total; do not add the amounts up yourself.
Reading them
| Endpoint | Returns |
|---|---|
GET / | Every document for one payment, oldest first, plus received, refunded and net |
GET / | Your newest 100, or the same keyset walk GET / has — updatedAfter, cursor, limit, same envelope, same 60-second lag. Optional kind filter |
GET / | One document |
Filtering this walk by kind is safe, unlike filtering the payments walk by status: a
document's kind is frozen at issue, so a row cannot leave the filtered set while you are walking it.
The hosted document
Every document has publicId, and https://thru.la/r/<publicId> renders it for anyone with the
link — no key. That page is also the PDF: it prints, and the browser's own "Save as PDF" produces
the file. There is no .pdf endpoint.
It shows the WHOLE chain whichever document was linked, so a customer holding an older email still
sees the current, complete story rather than a figure that understates what was received. It states
every transfer behind the total with its confirmation depth at issue and the threshold it was
judged against — the part a crypto receipt can do that a paper one cannot. Your reference is
never rendered there; it is often an internal id, so it stays in the API and the console.
Delivery, honestly
thru emails the document only when it has a customer address, which in practice means the invoice
path. A checkout session carries your own reference, not an email, and a payment link carries
nothing. Everywhere else the receipt.* webhook carries the document and your return page can
link it — forwarding it to your customer is yours to do. emailedAt on the document tells you
whether anything was actually sent.
The letterhead
A document prints the issuing entity from Settings → Business: legal name, address, tax identifier. Set it before you take real payments — the details are SNAPSHOTTED onto each document at issue, so filling them in later fixes future documents and not past ones. Until then a document prints "issuer details not set" rather than guessing from your workspace name.
Settlement: where your money goes
Each payment is received on an address thru controls. Once the payment is confirmed or overpaid, thru forwards the funds to your settlement address for that chain and network. settlement.completed fires when the funds have been sent to you, and settlement.failed if sending failed. The full payload, and the fields that matter when a payment pays out twice, are in webhooks.
- Set a settlement address for every chain and network you accept before you go live. If there is none, the funds stay on the payment address and nothing is forwarded.
- Native SUI is not forwarded automatically. Withdraw it from Treasury in the console. No platform fee is withheld on native SUI.
settlement.*events report treasury movements. Never use them as the signal to fulfil an order: the payer paid when the payment was confirmed, not when you were paid out.
A payment can pay out more than once
If money lands on a payment after it has already been paid out — a payer sent a second transfer, or support credited a late one — the payout is re-opened and the next run forwards the rest. You get a second settlement.completed for the same paymentId with sequence: 2. Dedupe on runId, order on sequence, and never key your ledger on paymentId alone.
Reading your payouts: GET /v1/sweeps
Newest 100 by default; add updatedAfter, cursor or limit for the same keyset walk (and the same 60-second lag) GET /v1/payments has — see payments, "Reconciliation". Each row is a payment's current payout state, plus:
| Field | Meaning |
|---|---|
runs | Every payout attempt for this payment, oldest first: { id, sequence, status, amount, toAddress, txHash, gasFundingTxHash, trigger, error, startedAt, completedAt, feeAmount, feeStatus, feeNotCollected, feeReason, feeTxHash, feeToAddress }. id here is the runId the webhook carries. The fee* fields are that run's platform fee as it stands now (see webhooks for each field). They match its settlement. event with one exception: a run whose fee transfer did not complete reads feeStatus: "failed" here (its event said pending). Its fee went back to outstanding, and the run that retried it carries the outcome. feeAmount is always what that run withheld, so summing it across runs is right. |
sweptTotal | Lifetime forwarded for this payment. amount is the LAST run's transfer, not the total. |
runCount | How many runs actually forwarded. |
payoutState | scheduled, reopened, paid_, held, awaiting_ or manual_. (A payment with no payout record yet has no row here at all, so you will never read a seventh not_ value from this endpoint.) |
requiresManualPayout | true only for manual_ — money no run will ever forward (a chain with no payout rail, native SUI, a payout past its retry cap). Everything else is already scheduled. |
payoutNote | Plain-language reason, whenever there is something to know. |
reopenedAt, reopenReason | Set while money is waiting for a further run. |
feeCollectedTotal | Lifetime platform fee withheld from this payment's payouts and sent to thru. "0" when nothing was withheld. |
feeNotCollectedTotal | Lifetime platform fee thru decided not to collect on this payment. It is final: never taken from later money. |
feePending | Platform fee not settled yet: being sent or confirmed, or held back for a scheduled retry of a fee transfer that did not complete. "0" otherwise. |
id on the row is the payout record for that payment (one per payment, overwritten by each run) — not a payout id. Use runs[].id.
One payment's payout: GET /v1/sweeps/:paymentId returns { sweep, feeLegs }: the same row as above (null when the payment has no payout record yet) and every platform-fee decision on that payment, oldest first. A payment that belongs to another workspace is a 404. Each fee decision reads:
| Field | Meaning |
|---|---|
status | collected (withheld and sent to thru), pending (being sent or confirmed), failed (the fee transfer did not happen; the fee is still outstanding and a later run tries again) or not_ (thru decided not to take it; final) |
reason | Why not, or why only part: one of the reason codes below. null on a fully collected decision |
receivedFrom, receivedTo | The slice of receivedAmount this decision covers: (receivedFrom, receivedTo]. A payment that pays out twice has one decision per run, covering what arrived since the previous one |
due, withheld, notCollected | The fee on that slice, the part withheld from you, and the part not taken. withheld + notCollected = due once decided |
toFeeAddress | What reached thru's fee address. Equal to withheld on token rails; on native coins it is withheld less the network fee of thru's own transfer, which thru pays |
feeToAddress, txHash, sharedTx | thru's fee address and the fee transaction. sharedTx: true on Sui, where your payout and the fee are one transaction |
runSequence, sweepRunId | The payout run that decided it; both null on a decision made without a run (for example a refund before payout) |
feeBps, token, rail, decidedAt, collectedAt, verifiedAt | The payment's rate, the token, how the fee was taken (none = your payout was sent exactly as before), and when it was decided, withheld and confirmed on chain |
How much has not been forwarded yet: receivedAmount (from GET /v1/payments) minus sweptTotal minus feeCollectedTotal (both here). There is no separate field, deliberately: a stored number could disagree with the ones it is derived from.
On a native-asset rail that difference is never zero, and that is correct. Where the asset being paid is the chain's own gas asset, the payout must leave enough behind to pay for itself, so the amount forwarded is the balance minus a gas reserve. Arc is the case that surprises people: its USDC is the native asset, so an Arc payout is net of roughly 0.0005 USDC and that dust stays on the payment address for good. The same applies to native ETH, BNB, SOL and TRX. On token rails — ERC-20, SPL, TRC-20, Sui coins — thru pays the gas from its own tank and the full balance is forwarded, so the difference really is zero.
The platform fee
feeBps and feeAmount are recorded on every payment (see payments). Today both are 0 for every account and nothing is withheld from any payout, so every fee* field below reads 0, none or null. Before thru withholds a fee on mainnet, a breaking changelog entry announces it.
When thru collects the fee, it takes it from the payout itself, in the same settlement: your net goes to your settlement address and the fee goes to thru's fee address for that chain and network. No invoice follows, and nothing is ever due afterwards.
- The fee is charged on the gross amount received, overpayment included, at the rate fixed when the payment was created, and rounded down to the token's smallest unit.
- A refund never returns the fee (see Refunds above).
- A fee thru did not collect is never taken later. Each decision not to collect is final and says why (
reason). On a chain or token that cannot split a payout safely, and whenever thru is not collecting, your payout is sent exactly as before and the fee is recorded as not collected. - Who pays the network fee of the fee transfer: thru. On token rails thru's gas tank pays it. On native coins (Arc USDC, BNB, ETH) it comes out of the fee, so
toFeeAddressis a little belowwithheld; your payout is the balance less the fee withheld and the network fee of your own transfer, as before. - Your payout on each
settlement.completed:amountstays the net sent to you,feeAmountis the fee withheld in that run, andfeeCollectedTotalthe lifetime total.
The reconciliation identity, per payment:
receivedAmount = sweptTotal + feeCollectedTotal + (native coins: network gas and reserve dust) + not yet forwarded
Reason codes (reason on a fee decision, feeReason on a run and an event). They are opaque strings and more may be added, so treat one you do not recognise as "not collected". When several apply, the first in this table wins.
| Code | Meaning | What you receive |
|---|---|---|
legacy_ | Payment created before rates were fixed at creation | the full amount |
created_ | A non-zero rate fixed before fee collection existed | the full amount |
not_ | Native SUI, never forwarded automatically | it stays on the payment address, as before |
chain_ | No automatic payout on this chain | as before |
token_ | Token not supported for payout | as before |
rail_ | This chain or token cannot split the fee safely | the full amount |
refunded_ | Fully refunded before the fee was collected | as before |
rate_ | The payment's rate is above thru's current rate cap | the full amount |
collection_ | thru was not collecting fees | the full amount |
rail_ | Fee collection not enabled for this token | the full amount |
no_ | No thru fee address for this chain and network | the full amount |
fee_ | thru's fee address for this chain is not active yet | the full amount |
fee_ | thru's fee address changed before collection | the full amount, in a second payout |
split_ | The split transfer failed on this payment | the full amount |
planner_ | The fee could not be worked out at payout | the full amount |
below_ | The fee was below the minimum worth sending | the full amount |
below_ | Native coin: the fee was below the cost of sending it | the full amount |
unit_ | A remainder below the token's smallest unit | that remainder |
insufficient_ | The payment address held less than the fee due | what was there, less what was collected |
forwarded_ | A payout sent this money before it was credited | already received |
operator_ | Waived by thru | the leftover fee is forwarded to you |
A payout run that finds nothing to send emits no event, and neither does a run that only sends thru a leftover platform fee (a fee_retry run after a fee transfer did not complete): your money did not move, so there is no settlement.* event. That run closes as completed with amount: "0" and no txHash, and you see it in runs[] but never as a settlement.completed. A fee_retry run that sends YOU money is announced like any payout: when the fee can no longer be collected (collection was turned off, the fee address changed, or the fee fell below the minimum), that money is yours, and the run forwards it with settlement.completed, trigger: "fee_retry" and feeStatus: "not_collected". Nor is there an event when a run merely starts, or when a payout is marked held or skipped — only the two terminal outcomes are announced.
Monthly fee receipts
When thru withholds platform fees from your payouts, it issues a fee receipt for each UTC calendar month in which something was withheld: a record of fees already taken, not a bill. Nothing is due on it.
- Numbered
FEE-YYYY-NNNN, one series across thru (thru is the issuer), restarting each calendar year of issue. - Issued from 00:15 UTC on the 1st for the month before. No receipt for a month with nothing withheld.
- One line per fee withheld on mainnet and confirmed on chain. A fee appears on exactly one receipt, ever. A fee confirmed on chain after its month's receipt was issued appears on the next receipt, with
carriedForward: true. - Totals are per chain, network and token (
totals[]), never added across tokens:legCount,paymentCount,feeBase(the gross amount the fees were charged on),feeandfeeAtomic(the same in the token's smallest unit). Each line's fee is rounded down on the payment's cumulative amount, so a line can differ by one smallest unit fromfeeBase×feeBps/ 10000. The exception is a line where only part of the fee could be withheld (the address held less than the fee due,insufficient_balance): itsfeeis what was withheld, belowfeeBase×feeBps/ 10000, and the rest is never taken.GET /v1/sweeps/:paymentIdshows that decision'sdueandnotCollected. notWithheldCountcounts the payments that month that carried a fee thru did not withhold. Nothing is owed for them.- Never edited after issue.
contentHashis a SHA-256 fingerprint of the frozen content, so two copies can be compared. - Email: the workspace's owners are emailed a copy only when thru's email delivery is configured;
emailedAtsays whether one went out. The receipt is in the API and the console either way. - A receipt with
network: "testnet"(test: true, numberedFEE-TEST-YYYY-NNNN) is a test document. It is never emailed. - Agent payments (HTTP 402) settle directly to you and carry no platform fee.
| Endpoint | Returns |
|---|---|
GET / | Your newest 100 receipts, or the same keyset walk GET / has (updatedAfter, cursor, limit, same envelope, same 60-second lag). Optional network filter |
GET / | This month so far (or an earlier month), live: the same totals[] plus verifiedFee and unverifiedLegCount, on every network. No number and no fingerprint: a preview is not a receipt, and it changes until the month closes |
GET / | One receipt with its lines[]: paymentId, chain, network, token, paymentCreatedAt, collectedAt, carriedForward, runSequence, feeBase, feeBps, fee, feeAtomic, feeTxHash, payoutTxHash, reference |
GET / | The receipt's lines as CSV |
A receipt also carries periodStart and periodEnd (exclusive: the first instant of the next month), issuedAt, issuer (thru's letterhead) and recipient (your workspace name and your Settings → Business details, snapshotted at issue). All four need permission to read settlement data, which every built-in role has, the same as GET /v1/sweeps.
Managing settlement addresses
Use the console: Treasury → Settlement. You can hold several addresses per chain and network (up to 20). One of them is the default, which receives everything not routed elsewhere, including all direct payments and invoices. You can route an individual product's sales to a different address.
The first address for a chain and network is active immediately. Adding another address, or changing an existing one, is staged behind a cool-down (24 hours by default) during which it can be cancelled. The events settlement.address.created, settlement.address.change_staged and settlement.address.change_cancelled report these changes. Subscribe to settlement.* so you notice a change you did not make.
The same operations are available with an API key:
Rails with nowhere to settle
GET /v1/settlement/routing also answers the question you would otherwise only discover by
noticing money had not arrived:
"coverage": {
"missing": [
{ "chain": "arc", "network": "mainnet", "productSlugs": [], "invoiceNumbers": ["INV-0007"], "reason": "invoice" },
{ "chain": "base", "network": "mainnet", "productSlugs": ["credit-9c2e"], "invoiceNumbers": [], "reason": "product_rail" }
],
"covered": [{ "chain": "sui", "network": "mainnet" }]
}
A rail is missing when you can receive money on it and it has no activated default settlement address. You can receive money on a rail when:
- an active product sells on it (
product_rail, with the product slugs); - an open invoice with no payment yet can be paid on it: the invoice's own chain or one of its
enabledChains(invoice); - a payment has been created on it (
payment_seen).
reason is the strongest of these for the rail, and invoiceNumbers lists the open invoices
payable there whatever the reason ([] when there are none). missing is ordered
most-exposed-first, counting products and open invoices together. Treat a reason you do not
recognise as a gap; new sources may be added.
Money on a missing rail is not lost, and you do not have to do anything to recover it. The
payment is detected, credited and receipted exactly as normal; only the payout is deferred. The
sweep records skipped with "No settlement wallet configured", and the retry scan re-selects
precisely those rows — so the moment you set an address, the money is forwarded on the next tick.
What you lose by leaving a gap open is time and visibility, not funds.
An address that exists but is not the activated default does not cover the rail: an unrouted payment falls back to the default, so a rail whose only address is still inside its change cool-down is correctly still a gap.
| Endpoint | Does |
|---|---|
GET / | Lists your settlement addresses and the products routed to each |
GET / | Addresses, products and current routes in one read, plus coverage — see below |
POST / { chain, network?, address, label? } | Adds an address |
PATCH / { label } | Renames it |
POST / | Makes it the default |
PUT / { address } | Stages a change of address |
POST / | Cancels a staged change |
DELETE / | Removes an address that is not the default and has no products routed to it |
PUT / { changes: [{ productId, chain, network?, settlementAccountId }] } | Routes products to addresses; settlementAccountId: null sends a product back to the default |
PUT / { chain, network?, address } | Sets the default address for a chain and network |
POST / { chain, network? } | Cancels a staged change of the default |
network defaults to mainnet on all of these. Because an API key can change where your money goes, guard it accordingly.