Settlement

Where your money goes, how you prove the wallet is yours, and what we cannot do once it is sent.

A settlement destination is a wallet you control. We resolve it, we snapshot it onto every payment, and the buyer's transaction pays it directly. We never hold what passes through.

Three controls, and why each exists

You prove you hold the wallet

Pasting an address proves nothing. Before a destination can receive anything you sign a message with that wallet — no gas, nothing on chain — which demonstrates you hold the key. A settlement address nobody controls is money burnt on every future payment.

// Adding a destination needs a signed-in owner and a fresh password.
// This is the panel's job, not your server's — an API key cannot do it.
//
// You prove you hold the wallet by signing the message we give you:
const { verification } = await call('GET', '/v1/destinations/dst_9k2Qm');

const signature = await wallet.signMessage(verification.message);
await call('POST', '/v1/destinations/dst_9k2Qm/verify', { signature });

{
  "id": "dst_9k2Qm",
  "object": "settlement_destination",
  "kind": "address",
  "resolved_address": "0x8f2a4c...",
  "chains": [8453, 1],
  "asset": "USDC",
  "status": "pending_verification",
  "usable_at": "2026-09-05T09:00:00Z",
  "verification": {
    "method": "signature",
    "message": "UnifiWallet Payment Gateway\nVerify settlement destination\norg: org_7Kd2mQx9\ndestination: dst_9k2Qm\naddress: 0x8f2a4c...",
    "instructions": "Sign this message with the destination wallet and POST it to /verify."
  }
}

A new destination waits

Once verified it sits in a cooling period, and every owner is emailed — including the address being replaced. That mail is the point: somebody who did not authorise the change hears about it while it can still be stopped.

A stolen API key cannot get around this. Registering a destination needs a person in the panel with their password re-entered, so the worst a compromised server can do is point payments at a wallet you already proved you own.

The address is frozen onto the payment

When a payment is created we write the resolved address into its snapshot. Changing your default afterwards does not move a payment already on its way — which is what stops a compromised account redirecting money that is in flight.

Nothing about a settlement address is recoverable.

We are not in the path of the funds, so we cannot reverse a transfer, cannot recall one sent to an address you no longer control, and cannot recover anything sent to an exchange deposit address that does not credit arbitrary tokens. Check the address, and use a wallet you will still hold in a year.

Shields

A Shield is a named alias in UnifiWallet that resolves to an address and the networks it can receive on. Register one with {"kind":"shield","shield_code":"…"} and we check it can receive on your settlement chain before accepting it.

Because a Shield's address can be changed by its owner, we re-resolve at payment time and compare against the snapshot. A mismatch aborts the payment rather than paying a new address.

Marketplace routing

If you are paying sellers rather than yourself, a payment can name its own destination:

{
  "amount": "49.99",
  "currency": "USD",
  "settlement": { "destination_id": "dst_seller_4482" }
}

That settles each sale to the seller who made it, with no pooling and no moment where the money is yours. Registered destination ids only — a raw address per payment bypasses the cooling period entirely, so it is off unless an owner turns it on in the panel, and even then an API key cannot enable it.

What arrives

Every settlement records what the merchant actually received, not what was asked for:

Field	Meaning
`gross`	What the transaction produced.
`fee`	Our share, taken in the same transaction.
`net`	What reached your wallet.
`excess_returned`	Anything over the required amount, sent back to the buyer.
`tx_hash`	Check it yourself on a block explorer.
`fiat_value`	A valuation at the moment of settlement, with its source.

The fiat valuation is recorded at the settlement timestamp rather than recomputed later, because most jurisdictions treat receiving crypto as a disposal and you cannot file on a number that moves.

What appears on your statement

GET /v1/statements is the flow record your accountant wants: one line per movement, each with the fiat value at the time. Three kinds:

Type	Direction	When
`settlement_net`	in	Money that reached you.
`platform_fee`	out	Our share, taken in the same transaction.
`network_gas`	out	A network fee we paid on your behalf for something that settled nothing — a cancelled hold, one that expired, a deposit returned to a buyer.
`refund`	out	A refund you sent, once we verified it on chain.

direction is in or out, from your side of the ledger. There are no balances here to derive — the money is in your wallet, not with us.

Refused settlements

A payment id is public — it is in the checkout URL and in your own logs. If a transaction arrives carrying one but disagreeing with that payment's terms, it is quarantined rather than credited, and you get payment.settlement_rejected.

These never appear in your settlement list or your volume totals. Ask for them explicitly with ?status=quarantined if you want to see what was attempted.

Reorgs

A confirmed settlement can be undone by a chain reorganisation. We watch for it, mark the settlement reorged, and send payment.reorged. This is the entire reason to wait for completed rather than settled — confirmations are how far back that window reaches.

← Testing Holds and captures →