Coinbase Commerce employs two primary systems to track and confirm cryptocurrency payments: the Charge API and webhook events. These tools provide merchants with real-time updates and detailed transaction histories for seamless payment processing.
Charge API: Detailed Payment Tracking
When a payment request (charge) is initiated, Coinbase Commerce monitors the blockchain for related transactions. The Charge API documents each charge's progression through several statuses, recorded in the timeline field—an array of status objects with timestamps.
Key Charge Statuses
| Status | Description |
|---|---|
| New | Charge created but no further action taken. |
| Signed | Transaction signed by the wallet owner; funds ready to transfer. |
| Pending | Transaction detected on-chain; funds received in the merchant wallet. |
| Completed | Transaction finalized and protected against blockchain reorganizations. |
The most recent entry in the timeline array reflects the charge's current status.
Webhook Events: Real-Time Notifications
Webhooks deliver instant updates about charge status changes, triggering automated actions (e.g., order fulfillment).
Common Webhook Events
| Event | Description |
|---|---|
charge:created | New charge initiated. |
charge:pending | Transaction posted to the blockchain; funds received. |
charge:confirmed | Payment finalized and secure. |
charge:failed | Charge could not be completed. |
Charge API vs. Webhooks: Use Cases
- Charge API: Best for backend systems requiring historical data (e.g., audits, reconciliations).
- Webhooks: Ideal for real-time workflows (e.g., unlocking downloads upon
charge:pending).
The Importance of the PENDING Status
Why PENDING Matters
- Speed: Reached within 2–10 seconds of purchase.
- Security: Failure after this status is exceptionally rare (<1 in 1,000,000).
- Operational Efficiency: Merchants can safely fulfill orders at this stage.
COMPLETED/CONFIRMED Status
- Finality: Achieved after ~15 minutes; protects against blockchain reorgs.
Choosing Between Statuses
- For Speed: Use
PENDINGto accelerate order processing. - For Certainty: Wait for
COMPLETEDif finality is prioritized.
FAQ: Coinbase Commerce Payment Status
Q: How long does a charge stay in PENDING status?
A: Typically transitions to COMPLETED within 15 minutes.
Q: Can a PENDING transaction fail?
A: Extremely unlikely—odds are less than one in a million.
Q: Are webhooks mandatory for status updates?
A: No, but they streamline automation. The Charge API can also poll for updates.
👉 Learn more about crypto payment best practices
Q: What happens if a charge fails?
A: Merchants receive a charge:failed webhook and must handle refunds or retries.
👉 Explore secure blockchain payment solutions
Keywords: Coinbase Commerce, Charge API, payment status, cryptocurrency payments, webhook events, PENDING status, blockchain transactions
### Key Features:
- **SEO Optimization**: Keywords naturally integrated (e.g., "Coinbase Commerce," "cryptocurrency payments").