GuidesAPI Reference
DocumentationLog In

Cryptocurrency payments

About

Payments today rely on customers populating forms with credit card information. This information is then used to pull payments directly from the customer. Cryptocurrencies are different. Instead, a wallet is used to push payments directly to the merchant. A customer specifies the amount of cryptocurrency along with an address before sending funds. In this way, cryptocurrency payments are push payments.

When a customer requests to pay with cryptocurrency, we create a charge representing the expected payment. A charge can be thought of as a request for payment in one or more cryptocurrencies. Since cryptocurrency payments are made over a separate network, a unique payment address per cryptocurrency is generated on charge creation so we can associate customers to their payments. When a customer makes a cryptocurrency payment, they generate a transaction that is then broadcast to the cryptocurrency network for validation/confirmation.

Once a charge is created we start monitoring these unique addresses on the respective networks to detect any inbound payments. Each charge has an associated payment status.

When we detect the customer’s transaction on the blockchain, the payment status changes to Pending. This means the payment has been detected but it has not yet been validated by the network. When the transaction is fully validated and confirmed by the blockchain network, the payment status changes to Completed. These unique payment addresses are monitored for up to 60 minutes. If no payment is detected after 60 minutes then the payment status changes to Expired.

In some cases, a customer may make a payment after the 60 minutes has passed. In this case the payment status changes to Unresolved with a reason of Delayed.

In other cases a customer may overpay, underpay, or pay more than once. When this happens the payment status changes to Unresolved with reasons Overpaid, Underpaid, or Multiple respectively. The Unresolved payment status can be manually updated to Resolved by the merchant to indicate that the payment issue has been resolved.

Payment Statuses

A list of all payment statuses can be found below:

Payment StatusDescription
NewThe payment has been created
PendingThe transaction has been detected
CompletedThe transaction has been confirmed by the blockchain network
ExpiredThe payment request has expired (requests expire after 60 minutes if no payment has been detected)
UnresolvedThe transaction has been confirmed but the payment diverged from what was expected
Unresolved (Underpaid)The amount received was less than the amount requested
Unresolved (Overpaid)The amount received was more than the amount requested
Unresolved (Delayed)The amount received arrived after the payment request expired
Unresolved (Multiple)Multiple payments were made to the same address
Unresolved (Other)The transaction is of an unknown type
ResolvedThe merchant has marked the payment as resolved
CancelledThe request has been cancelled. Only new charges can be cancelled. Once a payment has been detected a charge cannot be cancelled.
Pending RefundA refund has been initiated for this charge. Once a payment has been refunded it cannot be undone.
RefundedA refund has been broadcasted and confirmed by the blockchain network

Here's a visual representation of how all this works: