API Docs

Payment States

Each payment can exist in one of the following states:

NEW

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

UNDERPAID

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

UNCONFIRMED

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

CONFIRMED

Payment was fully paid and confirmed. These payments will appear on the statement.

EXPIRED

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

INVALID

There are few cases when payment can end up in this state, for example customer paid to little BTC and didn't send the rest in time.

Merchants should wait for the related Anomaly notification before releasing the product.

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 BTC
NEW UNCONFIRMED Received correct amount of BTC, but transaction requires more confirmations
UNCONFIRMED CONFIRMED Got required number of confirmations from the Bitcoin network
UNCONFIRMED INVALID Transaction turned out to be invalid or we received another transaction to that address
UNDERPAID INVALID Remaining amount was not received within expiration time
UNDERPAID UNCONFIRMED Received rest of the BTC, but more confirmations are required
UNDERPAID CONFIRMED Received rest of the BTC

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, BitcoinPayGate immediately changes Payment status to CONFIRMED and REGULAR notification is sent
  4. Merchant is free to release the product to the client because BitcoinPayGate 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, paidBtc and remainingToPayBtc are updated accordingly
  5. BitcoinPayGate sends REGULAR 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
  8. BitcoinPayGate sends REGULAR notification in status INVALID
  9. BitcoinPayGate sends ANOMALY notification for the Bitcoin transaction of 0.5 BTC
  10. Depending on the scenario merchant might release the product, only part of it, or completely reject the payment
  11. BitcoinPayGate 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, paidBtc and remainingToPayBtc are updated accordingly
  5. BitcoinPayGate sends REGULAR 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. BitcoinPayGate immediately changes Payment status to CONFIRMED and REGULAR notification is sent
  9. Merchant is free to release the product to the client because BitcoinPayGate 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 we wait few Bitcoin blockchain confirmations in UNCONFIRMED state
  4. BitcoinPayGate sends REGULAR notification in status UNCONFIRMED
  5. After few minutes the transaction status in settled and Payment is moved to CONFIRMED
  6. BitcoinPayGate sends REGULAR notification in status CONFIRMED
  7. Merchant is free to release the product to the client because BitcoinPayGate 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 we wait few Bitcoin blockchain confirmations in UNCONFIRMED state
  4. BitcoinPayGate sends REGULAR notification in status UNDERPAID
  5. Because it was a fraudulent transaction, BitcoinPayGate after some time will move it to INVALID state updating remainingToPayBtc to what the original amount reduced by what was correctly paid to that address
  6. BitcoinPayGate sends REGULAR 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. BitcoinPayGate sends REGULAR notification in status UNDERPAID
  6. When User notices the problem, the remaining BTC is sent
  7. BitcoinPayGate observes that Payment was now paid correctly, but due to high amount payment is now UNCONFIRMED
  8. BitcoinPayGate sends REGULAR notification in status UNCONFIRMED
  9. After receiving enough Bitcoin blockchain notifications transaction goes into CONFIRMED state
  10. BitcoinPayGate sends REGULAR notification in status CONFIRMED
  11. Merchant is free to release the product to the client because BitcoinPayGate guarantees that Merchant will be paid $50 000