API Docs

Payment States

Each payment can exist in one of the following states:

NEW

Payment waiting for Cryptocurrency to be send by the customer. All payments start in this state.

UNDERPAID

Customer did send Cryptocurrency, but it was not enough, Bitclear API is waiting for the rest of the payment. These are usually cases when user types amount by hand and makes a mistake.

UNCONFIRMED

Received a Cryptocurrency transaction, but Bitclear API is still awaiting confirmations from Cryptocurrency network. For example this can happen for high-amount transactions or other cases when we require confirmation from Cryptocurrency network.

CONFIRMED

Payment was fully paid and confirmed.

EXPIRED

This happens when no Cryptocurrency transaction has been received before the expiration time.

INVALID

There are few cases when payment can end up in this state:

  • Customer paid to little Cryptocurrency and didn't send the rest in time (Underpayment)
  • Customer paid too much Cryptocurrency (Overpayment)
  • Customer send Cryptocurrency after expiration time (Paid after expiration)

State transitions

From To Condition
NEW EXPIRED Did not received any transaction within expiration time
NEW UNDERPAID Received transaction, but amount paid was too low
NEW CONFIRMED Received correct amount of Cryptocurrency
NEW UNCONFIRMED Received correct amount of Cryptocurrency, but transaction requires more confirmations
NEW INVALID Too much of the Cryptocurrency
UNCONFIRMED CONFIRMED Got required number of confirmations from the Bitcoin network
UNCONFIRMED INVALID Transaction turned out to be invalid or Bitclear API received another transaction to that address
UNDERPAID INVALID Remaining amount was not received within expiration time
UNDERPAID UNCONFIRMED Received rest of the Cryptocurrency, but more confirmations are required
UNDERPAID CONFIRMED Received rest of the Cryptocurrency
EXPIRED INVALID Received Cryptocurrency after expiration time

State transitions

Payment State Transition Examples

Regular payment

  1. Client requests the payment of $50
  2. API returns amount of BTC that is requested to be sent to address X
  3. BTC is received correctly, Bitclear API immediately changes Payment status to CONFIRMED and notification is sent
  4. Merchant is free to release the product to the client because Bitclear guarantees Merchant will be paid $50

Underpayment - case 1

  1. Client requests the payment of $50
  2. API returns that 0.55 BTC is requested to be sent to address X
  3. User sends only 0.5 BTC
  4. Payment moves to UNDERPAID state, priceAmount and transferAmount are updated accordingly
  5. Bitclear API sends notification in status UNDERPAID
  6. User doesn't send the remaining 0.05 BTC
  7. When payment reaches expiration time, it moves into INVALID state and notification is sent
  8. Depending on the scenario merchant might release the product, only part of it, or completely reject the payment
  9. Bitclear guarantees that Merchant will receive a fraction of the payment that was paid - $45.45

Underpayment - case 2

  1. Client requests the payment of $50
  2. API returns that 0.55 BTC is requested to be sent to address X
  3. User sends only 0.5 BTC
  4. Payment moves to UNDERPAID state, priceAmount and transferAmount are updated accordingly
  5. Bitclear API sends notification in status UNDERPAID
  6. API client notifies the user about the mistake that too little was paid.
  7. User sends the remaining 0.05 BTC
  8. Bitclear API immediately changes Payment status to CONFIRMED and notification is sent
  9. Merchant is free to release the product to the client because Bitclear guarantees Merchant will be paid $50

Risky payment paid correctly

  1. Client requests the payment of $50 000
  2. API returns amount of BTC that is requested to be sent to address X
  3. BTC is received correctly, but due to high value of the Payment Bitclear API will wait few Bitcoin blockchain confirmations in UNCONFIRMED state
  4. Bitclear API sends notification in status UNCONFIRMED
  5. After few minutes the transaction status in settled and Payment is moved to CONFIRMED
  6. Bitclear sends notification in status CONFIRMED
  7. Merchant is free to release the product to the client because Bitclear guarantees that Merchant will be paid $50 000

Risky payment paid incorrectly

  1. Client requests the payment of $50 000
  2. API returns amount of BTC that is requested to be sent to address X
  3. BTC is received correctly, but due to high value of the Payment Bitclear API will wait few Bitcoin blockchain confirmations in UNCONFIRMED state
  4. Bitclear API sends notification in status UNDERPAID
  5. Because it was a fraudulent transaction, Bitclear API after some time will move it to INVALID state updating paidPriceAmount and paidTransferAmount to what the original amount reduced by what was correctly paid to that address
  6. Bitclear API sends notification in status INVALID
  7. Merchant shouldn't release the product to the client until there's a CONFIRMED notification

Underpaid And Unconfirmed

  1. Client requests the payment of $50 000
  2. API returns amount of BTC that is requested to be sent to address X
  3. User sends too little BTC
  4. The transaction moves into UNDERPAID because too little BTC was received
  5. Bitclear API sends notification in status UNDERPAID
  6. When User notices the problem, the remaining BTC is sent
  7. Bitclear API observes that Payment was now paid correctly, but due to high amount payment is now UNCONFIRMED
  8. Bitclear API sends notification in status UNCONFIRMED
  9. After receiving enough Bitcoin blockchain notifications transaction goes into CONFIRMED state
  10. Bitclear API sends notification in status CONFIRMED
  11. Merchant is free to release the product to the client because Bitclear guarantees that Merchant will be paid $50 000