Commerce Payment Status
Coinbase Commerce utilizes two main mechanisms to monitor and confirm cryptocurrency payments: the Charge API and webhook events.
Charge API
Once a payment request (charge) is created, Commerce's system begins monitoring the blockchain for any incoming transactions related to the charge. Each charge goes through several statuses, which are tracked in the timeline field of the Charge API model. This field contains an array of status objects, each with a status and timestamp, documenting the progression of the charge.
| Charge Status | Description |
|---|---|
| New | Charge has been created but no further action has occurred. |
| Signed | Transaction has been signed by the wallet owner, and the funds are ready to be sent. |
| Pending | Transaction detected on the blockchain and funds are received in the merchant wallet. |
| Completed | Transaction is finalized and is protected against forks or reorgs. |
The last entry in the timeline array is the current status of the Charge.
Webhook Events
Our system also utilizes webhook events to provide real-time updates about the status of a charge. Each event type corresponds to a specific stage in the payment process.
| Event | Description |
|---|---|
| charge:created | A new charge has been initiated. |
| charge:pending | The charge has been posted to the blockchain and funds are received by the merchant. |
| charge:confirmed | The charge has been fully confirmed, and the payment is considered finalized. |
| charge:failed | The charge could not be completed. |
Comparing Charge Status and Webhook Events
- The Charge API provides a detailed history of each transaction through its timeline array, useful for backend integration where continuous status tracking is needed.
- Webhooks deliver real-time notifications directly to servers, ideal for immediate action like fulfilling orders once payments reach the "PENDING" status.
Understanding the PENDING Status
PENDING
In both tools, the PENDING status plays a crucial role. It signifies that the transaction has been included in a blockchain block, indicating a successful transfer of funds. A charge typically shifts to PENDING within 2-10 seconds of purchase. The probability of a transaction failing after reaching this status is incredibly low — we believe it is less than one in a million. Given this reliability, merchants can choose to deliver goods when orders are PENDING.
COMPLETED/CONFIRMED
This status means that the payment is finalized and securely protected against any blockchain reorganization risks. Transactions usually transition from PENDING to COMPLETED/CONFIRMED within about 15 minutes.
Choosing a Status
For operational efficiency and enhanced customer satisfaction, you can use the PENDING status to expedite order fulfillment, as it provides timely delivery while maintaining a high degree of transaction security and confidence. However, you can wait for the transaction to reach the COMPLETED/CONFIRMED status of you prefer finality over speed.
See Also: