In the world of digital finance, a cryptocurrency invoice acts as a formal request for payment. It is directly linked to a unique digital currency address and specifies the exact amount required to be paid within its validity period. This amount can be denominated either in a specific cryptocurrency, like Bitcoin or Ethereum, or in a traditional fiat currency, such as US Dollars or Euros.
Due to the decentralized nature of cryptocurrency transactions, which occur on independent networks, each invoice requires the generation of a unique payment address for every supported digital currency. This crucial step ensures that payments can be accurately matched to the correct customer and invoice. Once a payment is initiated by a customer, the transaction is broadcast to the respective cryptocurrency network to await validation and confirmation.
How Cryptocurrency Invoices Work
The lifecycle of an invoice begins the moment it is created. The system immediately starts monitoring its unique address for any incoming transactions. Throughout its lifecycle, an invoice progresses through various statuses, which indicate its current state. Significant changes in status trigger automated callbacks—notifications sent to a pre-configured Callback URL.
The process typically follows these steps:
- A customer sends cryptocurrency to the invoice's address.
- The system detects this incoming transaction and sends a callback with a
transaction_createdevent. This signals that a payment has been identified but is still pending network validation. - Once the network has sufficiently confirmed and verified the transaction, a second callback is sent with a
transaction_confirmedevent. - Subsequently, the invoice's status automatically updates from
newtocompleted.
Invoice Validity and Time Limits
A critical aspect of cryptocurrency invoices is their limited validity window, which is typically a maximum of 10 minutes. This short timeframe is directly tied to the exchange rate. When an invoice is generated, the exchange rate between the chosen fiat amount and the cryptocurrency is locked in for this 10-minute period to protect both the merchant and the customer from market volatility.
If a customer sends a payment after this window has closed, the invoice will no longer be considered valid. In such cases, the status will be updated to unresolved with a specific paid_late context, indicating the nature of the issue.
Handling Payment Amount Discrepancies
Sometimes, the amount received does not exactly match the invoice amount. Customers may accidentally overpay or underpay.
- Overpayment: The customer sends more than the required amount.
- Underpayment: The customer sends less than the required amount.
In both scenarios, the invoice status will change to unresolved, with the context clearly marked as either overpaid or underpaid. 👉 Explore more strategies for handling payment discrepancies
Managing Unresolved Invoice Statuses
An invoice with an unresolved status requires manual intervention to determine its final outcome. A business can choose to either:
- Manually mark the invoice as
completed(e.g., accepting an overpayment or a late payment as a gesture of goodwill). - Initiate a
refundfor the overpaid amount or the entire late payment.
Alternatively, the process can be automated. By defining specific rules on the integration settings page—such as automatically completing late payments or refunding overpayments—the system can handle these unresolved cases without manual input, updating the status automatically once the payment is validated by the network.
Frequently Asked Questions
What exactly is a cryptocurrency invoice?
A cryptocurrency invoice is a payment request that contains a unique digital address and a specified amount due. It allows merchants to receive payments in digital currencies, with the amount fixed in either crypto or fiat for a short period.
Why does an invoice have a short expiration time?
The expiration time, usually 10 minutes, is in place to lock in a specific exchange rate. Cryptocurrency prices are highly volatile, and this timeframe ensures the value of the payment remains stable for the duration of the invoice's validity.
What should I do if a customer pays after the invoice expires?
The invoice status will become unresolved with a paid_late context. You can then manually choose to either accept the payment by marking it as completed or refund it to the customer.
How are overpayments and underpayments handled?
The system flags them as unresolved with the appropriate context (overpaid or underpaid). You must then manually decide to accept, partially accept, or refund the transaction based on your business policies.
What are callbacks and why are they important?
Callbacks are automated notifications sent to your server when key invoice events occur (like a new transaction or a confirmation). They are essential for keeping your system updated in real-time without needing to constantly poll the API.
Can the process for unresolved invoices be automated?
Yes, you can configure automatic rules in your account settings to define how the system should handle common unresolved scenarios, such as automatically completing late payments or refunding overpayments.