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 |
Payment State Transition Examples
Regular payment
- Client requests the payment of $50
- API returns amount of BTC that is requested to be sent to address X
- BTC is received correctly, BitcoinPayGate immediately changes Payment status to
CONFIRMED
andREGULAR
notification is sent - Merchant is free to release the product to the client because BitcoinPayGate guarantees Merchant will be paid $50
Underpayment - case 1
- Client requests the payment of $50
- API returns that 0.55 BTC is requested to be sent to address X
- User sends only 0.5 BTC
- Payment moves to
UNDERPAID
state,paidBtc
andremainingToPayBtc
are updated accordingly - BitcoinPayGate sends
REGULAR
notification in statusUNDERPAID
- User doesn't send the remaining 0.05 BTC
- When payment reaches expiration time, it moves into
INVALID
state - BitcoinPayGate sends
REGULAR
notification in statusINVALID
- BitcoinPayGate sends
ANOMALY
notification for the Bitcoin transaction of 0.5 BTC - Depending on the scenario merchant might release the product, only part of it, or completely reject the payment
- BitcoinPayGate guarantees that Merchant will receive a fraction of the payment that was paid - $45.45
Underpayment - case 2
- Client requests the payment of $50
- API returns that 0.55 BTC is requested to be sent to address X
- User sends only 0.5 BTC
- Payment moves to
UNDERPAID
state,paidBtc
andremainingToPayBtc
are updated accordingly - BitcoinPayGate sends
REGULAR
notification in statusUNDERPAID
- API client notifies the user about the mistake that too little was paid.
- User sends the remaining 0.05 BTC
- BitcoinPayGate immediately changes Payment status to
CONFIRMED
andREGULAR
notification is sent - Merchant is free to release the product to the client because BitcoinPayGate guarantees Merchant will be paid $50
Risky payment paid correctly
- Client requests the payment of $50 000
- API returns amount of BTC that is requested to be sent to address X
- BTC is received correctly, but due to high value of the Payment we wait few Bitcoin blockchain confirmations in
UNCONFIRMED
state - BitcoinPayGate sends
REGULAR
notification in statusUNCONFIRMED
- After few minutes the transaction status in settled and Payment is moved to
CONFIRMED
- BitcoinPayGate sends
REGULAR
notification in statusCONFIRMED
- Merchant is free to release the product to the client because BitcoinPayGate guarantees that Merchant will be paid $50 000
Risky payment paid incorrectly
- Client requests the payment of $50 000
- API returns amount of BTC that is requested to be sent to address X
- BTC is received correctly, but due to high value of the Payment we wait few Bitcoin blockchain confirmations in
UNCONFIRMED
state - BitcoinPayGate sends
REGULAR
notification in statusUNDERPAID
- Because it was a fraudulent transaction, BitcoinPayGate after some time will move it to
INVALID
state updatingremainingToPayBtc
to what the original amount reduced by what was correctly paid to that address - BitcoinPayGate sends
REGULAR
notification in statusINVALID
- Merchant shouldn't release the product to the client until there's a
CONFIRMED
notification
Underpaid And Unconfirmed
- Client requests the payment of $50 000
- API returns amount of BTC that is requested to be sent to address X
- User sends too little BTC
- The transaction moves into
UNDERPAID
because too little BTC was received - BitcoinPayGate sends
REGULAR
notification in statusUNDERPAID
- When User notices the problem, the remaining BTC is sent
- BitcoinPayGate observes that Payment was now paid correctly, but due to high amount payment is now
UNCONFIRMED
- BitcoinPayGate sends
REGULAR
notification in statusUNCONFIRMED
- After receiving enough Bitcoin blockchain notifications transaction goes into
CONFIRMED
state - BitcoinPayGate sends
REGULAR
notification in statusCONFIRMED
- Merchant is free to release the product to the client because BitcoinPayGate guarantees that Merchant will be paid $50 000