Payment Lifecycle

This guide is the reference for payment statuses: what each status means, how a payment moves between them, and when you can hand over the goods.

A customer can pay in two ways, and the way they pay changes how a payment reaches paid:

From the GoBTC Pay app. The customer confirms the payment in the app.
From an external wallet. The customer sends bitcoin from any other Bitcoin wallet to the payment address.

The one thing to understand

Tip

Fulfil the order when the payment status is paid. paid is final: a payment never leaves it, whichever way the customer paid.

Payment statuses

GoBTC Pay sets five statuses on a payment:

Status	What it means	Final?	What you should do
`initiated`	The payment is created and waiting for the customer to pay.	No	Wait.
`detected`	External wallet only. Funds covering the amount are visible on the Bitcoin network, but they do not have the required number of confirmations yet. It can still fall back to `initiated`.	No	Wait. Do not hand over the goods yet.
`paid`	The payment is complete.	Yes	Fulfil the order.
`expired`	The payment window (`expiresAt`) closed before the payment was completed. A payment from an external wallet can still become `paid`; see Expired is not final.	No	Do not fulfil yet. If the order is no longer valid, cancel the payment.
`canceled`	The payment was canceled.	Yes	Nothing. Late funds do not change the payment.

Note

The status list in the API also contains cleared and failed. GoBTC Pay does not currently set either of them on a payment.

Rendering diagram…

How a payment reaches `paid`

From the GoBTC Pay app

The customer reviews the amount and confirms it in the app.
The payment becomes paid in about a second. It never passes through detected.
You hand over the goods. From your side, the sale is complete.

The Bitcoin network settles the payment later, usually within a few hours. Until then the payment's paidAt field is empty. When the settlement transaction reaches the required number of confirmations, paidAt is filled in and you receive another payment.status.updated webhook. The status stays paid; settlement does not change whether you got paid. Once settled on Bitcoin, the payment is final: no chargebacks, no disputes, no reserves, ever.

Think of it like a card payment: the terminal says "approved" right away, and the funds settle into your account afterward.

From an external wallet

The customer sends bitcoin to the payment address.
When funds covering the amount become visible on the network, the payment moves to detected.
When the received amount has the required number of confirmations, the payment becomes paid, and paidAt is set at the same moment.

A detected payment can go back to initiated. This happens when its transaction disappears before it is confirmed, for example because the sender replaced it or it dropped out of the mempool. If the payment window has already closed by then, the payment becomes expired again.

Expired is not final

expired only means the payment window closed. What happens next depends on how the customer pays:

External wallet: GoBTC Pay keeps watching the payment address for 12 hours after expiresAt. If funds arrive and get the required number of confirmations within that time, the payment still becomes paid. After those 12 hours, funds arriving at the address no longer change the payment.
GoBTC Pay app: the app cannot pay a payment once its expiresAt has passed.

If the order is no longer valid on your side, cancel the expired payment: that closes the 12-hour window.

Canceling a payment

You can cancel a payment through the API while it is initiated or expired. A payment that is detected or paid cannot be canceled. Canceling a payment that is already canceled succeeds and changes nothing.

After a payment is canceled, funds that arrive at its address do not change it, and it can no longer be paid from the GoBTC Pay app.

How long settlement takes

GoMining produces about two blocks per day, so a GoBTC Pay app payment usually settles on Bitcoin within a few hours. This wait is expected; it does not affect the payment, which is already paid.

If GoMining's mining is briefly unavailable, the pending transactions can be sent to the public Bitcoin network instead, where any miner can record them. Settlement is never stuck indefinitely.

What does it cost you?

Customers paying from the GoBTC Pay app: no fee. A customer paying from an external wallet pays that wallet's own Bitcoin network fee.
Merchants: a 0.2% acquiring fee (split as 0.1% to miners and 0.1% to wallet providers).

Where your money lands

How a payment settles on-chain depends on your chosen settlement mode:

Operator-settled: GoMining receives the on-chain payment and reconciles your payout afterward. Simplest to run.
Direct-to-merchant (default): the payment goes straight to a single-signature Bitcoin address derived from your own xpub, whose private key only you hold, for full Layer 1 finality.

See Settlement Modes for the full comparison and fees.

Under the hood (technical details)

The rest of this page explains the mechanics of GoBTC Pay app payments for readers integrating the protocol. You don't need any of it to accept payments.

Cumulative pre-authorization

Instead of signing a fixed spending limit, the customer signs a growing running total with each payment. Every new payment is signed for the previous total plus the new amount:

new total = previous total + this payment

Each signed total must be strictly larger than the last. This gives GoMining an upper bound it cannot exceed, and makes rollback and double-spend impossible inside the instant-payment subsystem: the wallet refuses to sign a total that is smaller than, or inconsistent with, the previous one.

Custody during the lifecycle

The customer's funds sit at the 2-of-3 multisig address of their GoBTC Pay app wallet, under the customer's cryptographic co-control. GoMining cannot move them alone.
An incoming multisig UTXO becomes spendable only after it is confirmed on the Bitcoin main chain, which protects against chain reorganizations.
At settlement, the authorized amount moves on-chain. Any residual value above that amount and the network fee returns as change to the same multisig, so it stays self-custodied.

Settlement transactions

The customer's latest authorized amount settles in its own compact Bitcoin transaction, grouped with other users' transactions into a block GoMining mines itself. Because every settlement transaction is a standard, independently valid Bitcoin transaction, GoMining absorbs and amortizes the on-chain fee across the whole batch, which is why customers pay no network fee.