Adds event flows tables for each send/receive payment method

breez · Jan 15, 2025 · cc2b6b8 · cc2b6b8
1 parent 8ceac4a
commit cc2b6b8
Show file tree

Hide file tree

Showing 2 changed files with 56 additions and 5 deletions.
diff --git a/src/guide/receive_payment.md b/src/guide/receive_payment.md
@@ -251,11 +251,6 @@ receive method, optionally specifying a description.
 - For Bitcoin/Liquid BIP21 payments, it will be encoded in the URI as the `message` field.
 - For plain Liquid payments, the description has no effect.
 
-<div class="warning">
-<h4>Developer note</h4>
-When waiting for a payment to be received, it is enough to wait for a <code>PaymentWaitingConfirmation</code> event before displaying a successful payment feedback in the UI. At this point the transaction is broadcast and will be shortly confirmed.
-</div>
-
 <custom-tabs category="lang">
 <div slot="title">Rust</div>
 <section>
@@ -321,3 +316,30 @@ When waiting for a payment to be received, it is enough to wait for a <code>Paym
 ```
 </section>
 </custom-tabs>
+
+## Event Flows
+Once a receive payment is initiated, you can follow and react to the different payment events using the guide below for each payment method. See [Listening to events](/guide/events.html) for how to subscribe to events.
+
+### Lightning
+| Event | Description | UX Suggestion |
+| --- | --- | --- |
+| **PaymentPending** | The swap service has intercepted a HTLC for the Lightning invoice and broadcast a lockup transaction. The SDK has seen the lockup transaction and will broadcast the claim transaction, either when the lockup transaction is confirmed or if it is accepted as a zero-conf payment. | Show payment as pending. |
+| **PaymentWaitingConfirmation** | The claim transaction has been broadcast or a direct Liquid transaction (<a target="_blank" href="https://docs.boltz.exchange/v/api/magic-routing-hints">MRH</a>) has been seen. | Display successful payment feedback. |
+| **PaymentSucceeded** | The claim transaction or direct Liquid transaction (<a target="_blank" href="https://docs.boltz.exchange/v/api/magic-routing-hints">MRH</a>) is confirmed. | Show payment as complete. |
+| **PaymentFailed** | The swap has failed from one of several reasons. Either the swap/invoice has expired or the lockup transaction failed to broadcast. |  |
+
+### Bitcoin
+| Event | Description | UX Suggestion |
+| --- | --- | --- |
+| **PaymentWaitingFeeAcceptance** | The swap service has seen the Bitcoin lockup transaction. If there was no amount set for this swap or the Bitcoin lockup transaction contains a different amount, the fee has to be accepted, see [Amountless Bitcoin Payments](#amountless-bitcoin-payments). If the fee is within the configured leeway, the swap will be automatically accepted. | Allow the user to review fees for this payment. |
+| **PaymentPending** | The swap service has seen the Bitcoin lockup transaction and the amount is accepted. Once the SDK has seen the Liquid lockup transaction it will broadcast the Liquid claim transaction, either when the Liquid lockup transaction is confirmed or if it is accepted as a zero-conf payment. | Show payment as pending. |
+| **PaymentWaitingConfirmation** | The Liquid claim transaction has been broadcast and is waiting confirmation. | Display successful payment feedback. |
+| **PaymentSucceeded** | The Liquid claim transaction is confirmed. | Show payment as complete. |
+| **PaymentFailed** | The swap has failed from one of several reasons. Either the swap has expired, the fee was not accepted or the Liquid lockup transaction failed to broadcast. If a Bitcoin lockup transaction was broadcast then the funds will need to be refunded, see [Refunding payments](/guide/refund_payment.html). |  |
+| **PaymentRefundPending** | A Bitcoin refund transaction has been broadcast and is waiting confirmation. |  |
+
+### Liquid
+| Event | Description | UX Suggestion |
+| --- | --- | --- |
+| **PaymentWaitingConfirmation** | The transaction has been seen. | Display successful payment feedback. |
+| **PaymentSucceeded** | The transaction is confirmed. | Show payment as complete. |
diff --git a/src/guide/send_payment.md b/src/guide/send_payment.md
@@ -385,3 +385,32 @@ send method.
 ```
 </section>
 </custom-tabs>
+
+## Event Flows
+Once a send payment is initiated, you can follow and react to the different payment events using the guide below for each payment method. See [Listening to events](/guide/events.html) for how to subscribe to events.
+
+### Lightning
+| Event | Description | UX Suggestion |
+| --- | --- | --- |
+| **PaymentPending** | The SDK has broadcast the lockup transaction for the swap. | Show payment as pending. |
+| **PaymentWaitingConfirmation** | If the Lightning invoice contains an <a target="_blank" href="https://docs.boltz.exchange/v/api/magic-routing-hints">MRH</a>, the SDK will instead broadcast a direct Liquid transaction. | Display successful payment feedback. |
+| **PaymentSucceeded** | The swap service has seen the lockup transaction and broadcast the claim transaction, or the direct Liquid transaction (<a target="_blank" href="https://docs.boltz.exchange/v/api/magic-routing-hints">MRH</a>) is confirmed. | Show payment as complete. |
+| **PaymentFailed** | The swap has expired without a lockup transaction. |  |
+| **PaymentRefundPending** | The swap can be refunded for several reasons. Either the swap/invoice has expired or the swap service failed to pay the invoice. In this case the SDK will broadcast a refund transaction. |  |
+| **PaymentRefunded** | The refund transaction is confirmed. |  |
+
+### Bitcoin
+| Event | Description | UX Suggestion |
+| --- | --- | --- |
+| **PaymentPending** | The SDK has broadcast the Liquid lockup transaction. Once the SDK has seen the Bitcoin lockup transaction it will broadcast the Bitcoin claim transaction, either when the Bitcoin lockup transaction is confirmed or if it is accepted as a zero-conf payment. | Show payment as pending. |
+| **PaymentWaitingConfirmation** | The Bitcoin claim transaction has been broadcast and is waiting confirmation. | Display successful payment feedback. |
+| **PaymentSucceeded** | The Bitcoin claim transaction is confirmed. | Show payment as complete. |
+| **PaymentFailed** | The swap has expired without a Liquid lockup transaction. |  |
+| **PaymentRefundPending** | The swap can be refunded for several reasons. Either the swap has expired or the Bitcoin lockup transaction failed to broadcast. In this case the SDK will broadcast a Liquid refund transaction. |  |
+| **PaymentRefunded** | The Liquid refund transaction is confirmed. |  |
+
+### Liquid
+| Event | Description | UX Suggestion |
+| --- | --- | --- |
+| **PaymentWaitingConfirmation** | The transaction has been seen. | Display successful payment feedback. |
+| **PaymentSucceeded** | The transaction is confirmed. | Show payment as complete. |