Release MakePay 1.7.5 payment received UX

Author: orangebtc

BTCPayServer.Plugins.MakePay.Tests/MakePayCheckoutPolicyTests.cs

@@ -370,4 +370,20 @@ public void CashAppCheckoutStaysInsideBtcpayAndUsesOriginScopedApi()
         Assert.DoesNotContain("window.location.assign", source);
         Assert.DoesNotContain("paymentMethod=cash_app_onramp", source);
     }
+
+    [Fact]
+    public void DepositReceivedUsesPayerFacingConfirmationInsteadOfSendInstructions()
+    {
+        var source = File.ReadAllText(
+            Path.Combine(AppContext.BaseDirectory, "Fixtures", "CheckoutPaymentMethodExtension.cshtml"));
+
+        Assert.Contains("v-else-if=\"paymentStarted && isPaymentReceived\"", source);
+        Assert.Contains("Payment received", source);
+        Assert.Contains("We received your payment and are finalizing the invoice", source);
+        Assert.Contains("['deposit_received', 'swapping', 'sending', 'complete']", source);
+        Assert.Contains("paymentReceived: false", source);
+        Assert.Contains("this.paymentReceived = true", source);
+        Assert.Contains("Do not send another payment to this address", source);
+        Assert.DoesNotContain("Status: {{ status }}", source);
+    }
 }

BTCPayServer.Plugins.MakePay.Tests/MakePayPaymentRecorderTests.cs

@@ -0,0 +1,38 @@
+#nullable enable
+using BTCPayServer.Data;
+using BTCPayServer.Plugins.MakePay.Services;
+using Xunit;
+
+namespace BTCPayServer.Plugins.MakePay.Tests;
+
+public class MakePayPaymentRecorderTests
+{
+    [Theory]
+    [InlineData("deposit_received")]
+    [InlineData("swapping")]
+    [InlineData("sending")]
+    [InlineData("complete")]
+    [InlineData(" DEPOSIT_RECEIVED ")]
+    public void DepositReceiptAndLaterStatesCreateAProcessingPayment(string status)
+    {
+        Assert.Equal(
+            PaymentStatus.Processing,
+            MakePayPaymentRecorder.MapSessionStatusToPaymentStatus(status));
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("quoted")]
+    [InlineData("awaiting_deposit")]
+    [InlineData("pending")]
+    [InlineData("underpaid")]
+    [InlineData("expired")]
+    [InlineData("failed")]
+    [InlineData("cancelled")]
+    [InlineData("refunded")]
+    public void PreDepositAndTerminalFailureStatesDoNotCreateAPayment(string? status)
+    {
+        Assert.Null(MakePayPaymentRecorder.MapSessionStatusToPaymentStatus(status));
+    }
+}

BTCPayServer.Plugins.MakePay/BTCPayServer.Plugins.MakePay.csproj

@@ -9,7 +9,7 @@
   <PropertyGroup>
     <Product>Accept more than 90+ coins and chains - MakePay</Product>
     <Description>Accept 90+ altcoins with Makepay’s fully decentralized BTCPay plugin. Customers pay in their preferred coin; merchants receive their chosen asset via instant conversion.</Description>
-    <Version>1.7.4</Version>
+    <Version>1.7.5</Version>
     <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
   </PropertyGroup>
 

BTCPayServer.Plugins.MakePay/Controllers/MakePayWebhookController.cs

@@ -150,7 +150,7 @@ public async Task<IActionResult> HandleWebhook(string storeId)
             return Ok();
         }
 
-        await _paymentRecorder.RecordIfComplete(
+        await _paymentRecorder.RecordIfReceived(
             invoice,
             promptDetails,
             session,

BTCPayServer.Plugins.MakePay/MakePayPlugin.cs

@@ -10,7 +10,7 @@ namespace BTCPayServer.Plugins.MakePay;
 
 public class MakePayPlugin : BaseBTCPayServerPlugin
 {
-    public const string PluginVersion = "1.7.4";
+    public const string PluginVersion = "1.7.5";
     public static readonly PaymentMethodId MakePayPaymentMethodId = new("MAKEPAY");
 
     public override IBTCPayServerPlugin.PluginDependency[] Dependencies { get; } =

BTCPayServer.Plugins.MakePay/Services/MakePayInvoiceListener.cs

@@ -191,6 +191,6 @@ private async Task ReconcileInvoice(
             ["settlementAmount"] = current["settlementAmount"]
         };
 
-        await _paymentRecorder.RecordIfComplete(invoice, promptDetails, session);
+        await _paymentRecorder.RecordIfReceived(invoice, promptDetails, session);
     }
 }

BTCPayServer.Plugins.MakePay/Services/MakePayPaymentRecorder.cs

@@ -32,22 +32,26 @@ public MakePayPaymentRecorder(
         _logger = logger;
     }
 
-    public async Task<bool> RecordIfComplete(
+    public async Task<bool> RecordIfReceived(
         InvoiceEntity invoice,
         MakePayPromptDetails promptDetails,
         JObject session,
         string? deliveryId = null)
     {
         var status = Text(session["status"]);
-        if (!string.Equals(status, "complete", StringComparison.OrdinalIgnoreCase))
+        var paymentStatus = MapSessionStatusToPaymentStatus(status);
+        if (paymentStatus is null)
         {
             return false;
         }
 
         var sessionId = Text(session["id"]) ?? Text(session["sessionId"]);
         if (string.IsNullOrWhiteSpace(sessionId))
         {
-            _logger.LogWarning("MakePay complete session for invoice {InvoiceId} did not include a session id.", invoice.Id);
+            _logger.LogWarning(
+                "MakePay {Status} session for invoice {InvoiceId} did not include a session id.",
+                status,
+                invoice.Id);
             return false;
         }
 
@@ -70,7 +74,7 @@ public async Task<bool> RecordIfComplete(
         {
             PaymentLinkUid = promptDetails.PaymentLinkUid,
             SessionId = sessionId,
-            Status = status ?? "complete",
+            Status = status!,
             PaymentMethod = Text(session["paymentMethod"]) ??
                             Text(session.SelectToken("quotePayload.paymentMethod")) ??
                             "crypto",
@@ -107,7 +111,9 @@ public async Task<bool> RecordIfComplete(
             InvoiceDataId = invoice.Id,
             Currency = "BTC",
             Amount = promptDetails.BtcAmount,
-            Status = PaymentStatus.Processing,
+            // A source-chain deposit is real received-payment evidence, but it is
+            // not proof that the merchant-controlled settlement has confirmed.
+            Status = paymentStatus.Value,
             Created = DateTimeOffset.UtcNow
         };
         payment.Set(invoice, handler, paymentData);
@@ -157,6 +163,19 @@ public async Task<bool> RecordIfComplete(
         return true;
     }
 
+    internal static PaymentStatus? MapSessionStatusToPaymentStatus(string? status)
+    {
+        // A webhook can be missed while the session advances, so every state at
+        // or beyond deposit receipt must be able to create the same idempotent
+        // native payment record. It intentionally remains Processing; BTCPay may
+        // settle the invoice only from independent settlement confirmation.
+        return status?.Trim().ToLowerInvariant() switch
+        {
+            "deposit_received" or "swapping" or "sending" or "complete" => PaymentStatus.Processing,
+            _ => null
+        };
+    }
+
     private static string? Text(JToken? token)
     {
         var value = token?.Value<string>()?.Trim();

BTCPayServer.Plugins.MakePay/Views/Shared/MakePay/CheckoutPaymentMethodExtension.cshtml

@@ -142,6 +142,30 @@
         font-size: .75rem;
     }
 
+    .makepay-checkout .makepay-payment-received {
+        width: 100%;
+        max-width: 28rem;
+        margin: 0 auto;
+        padding: 2rem 1rem;
+    }
+
+    .makepay-checkout .makepay-payment-received-icon {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 4rem;
+        height: 4rem;
+        margin-bottom: 1rem;
+        border-radius: 50%;
+        background: var(--btcpay-success-dim-bg, rgba(60, 153, 110, .18));
+        color: var(--btcpay-success, #3c996e);
+    }
+
+    .makepay-checkout .makepay-payment-received-icon svg {
+        width: 2rem;
+        height: 2rem;
+    }
+
     @@media (max-width: 420px) {
         .makepay-checkout .makepay-option > span {
             grid-template-columns: 2.5rem minmax(0, 1fr);
@@ -382,6 +406,23 @@
             </div>
         </div>
 
+        <div v-else-if="paymentStarted && isPaymentReceived"
+             class="makepay-payment-received text-center"
+             role="status"
+             aria-live="polite">
+            <span class="makepay-payment-received-icon" aria-hidden="true">
+                <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                    <path d="M5 12.5l4.25 4.25L19 7"
+                          stroke="currentColor"
+                          stroke-width="2.5"
+                          stroke-linecap="round"
+                          stroke-linejoin="round"></path>
+                </svg>
+            </span>
+            <div class="h4 mb-2">{{ paymentReceivedTitle }}</div>
+            <p class="text-muted mb-0">{{ paymentReceivedMessage }}</p>
+        </div>
+
         <div v-else-if="paymentStarted && isCashAppPayment"
              class="makepay-cash-app-transfer text-center">
             <div class="makepay-cash-app-summary justify-content-center mb-3">
@@ -452,8 +493,11 @@
             </button>
         </div>
 
-        <div v-if="status && !isCashAppPayment" class="mt-3 small text-muted text-center">
-            Status: {{ status }}
+        <div v-if="status && !isCashAppPayment && !isPaymentReceived"
+             class="mt-3 small text-muted text-center"
+             role="status"
+             aria-live="polite">
+            {{ checkoutStatusLabel }}
         </div>
 
         <div v-if="isBusy" class="text-center py-3">
@@ -499,6 +543,7 @@
                 cashAppPaymentRequest: '',
                 paymentExpiresAtMs: 0,
                 status: '',
+                paymentReceived: false,
                 error: '',
                 success: '',
                 isBusy: false,
@@ -615,6 +660,44 @@
                 };
                 return labels[this.status] || 'Waiting for payment';
             },
+            isPaymentReceived: function () {
+                return this.paymentReceived ||
+                    ['deposit_received', 'swapping', 'sending', 'complete']
+                        .indexOf(this.status) >= 0;
+            },
+            paymentReceivedTitle: function () {
+                if (['expired', 'failed', 'cancelled', 'refunded'].indexOf(this.status) >= 0) {
+                    return 'Payment needs attention';
+                }
+
+                return this.status === 'complete'
+                    ? 'Payment complete'
+                    : 'Payment received';
+            },
+            paymentReceivedMessage: function () {
+                if (['expired', 'failed', 'cancelled', 'refunded'].indexOf(this.status) >= 0) {
+                    return 'We received your transfer, but could not finish processing it. Do not send another payment to this address. Please contact the merchant for help.';
+                }
+
+                return this.status === 'complete'
+                    ? 'Thank you. This invoice is paid and you can safely close this window.'
+                    : 'Thank you. We received your payment and are finalizing the invoice. This page will update automatically.';
+            },
+            checkoutStatusLabel: function () {
+                var labels = {
+                    quoted: 'Quote ready',
+                    awaiting_deposit: 'Waiting for payment',
+                    pending: 'Waiting for payment',
+                    deposit_received: 'Payment received',
+                    swapping: 'Processing payment',
+                    sending: 'Processing payment',
+                    complete: 'Payment complete',
+                    expired: 'Payment expired',
+                    failed: 'Payment failed',
+                    cancelled: 'Payment cancelled'
+                };
+                return labels[this.status] || 'Checking payment status';
+            },
             refundAddressMode: function () {
                 return this.model.makePayRefundAddressMode === 'payer_entered'
                     ? 'payer_entered'
@@ -1116,6 +1199,7 @@
                 this.cashAppPaymentRequest = '';
                 this.paymentExpiresAtMs = 0;
                 this.status = '';
+                this.paymentReceived = false;
                 this.error = '';
                 this.success = '';
                 this.awaitingConfirmation = false;
@@ -1363,7 +1447,13 @@
                     this.selectedAsset = String(payload.selectedSellAsset);
                     this.syncSelectedCurrencyFromAsset();
                 }
-                this.status = payload.status || this.status;
+                var nextStatus = payload.status || this.status;
+                if (['deposit_received', 'swapping', 'sending', 'complete'].indexOf(nextStatus) >= 0) {
+                    // Once the payer transfer is observed, never expose payment
+                    // instructions again because of a weaker tracking response.
+                    this.paymentReceived = true;
+                }
+                this.status = nextStatus;
                 this.applyQuotedAmounts(payload);
                 this.paymentExpiresAtMs = this.parseDateMs(payload.expiresAt) || this.paymentExpiresAtMs;
                 if (payload.deposit) {

README.md

@@ -182,16 +182,19 @@ polling, and quote refresh.
 ## Settlement and Accounting
 
 MakePay session webhooks and reconciliation responses are treated as evidence
-that the MakePay payment session completed. The plugin records that evidence as
-a **Processing** MakePay payment on the invoice, so BTCPay does not mark the
-invoice as settled solely because MakePay reported a completed session.
+that the payer's source-chain deposit was received. As soon as the session
+reaches `deposit_received` (or a later payment state), the plugin records a
+**Processing** MakePay payment and publishes BTCPay's native **Invoice - Received
+Payment** event. The payment deliberately remains Processing, so BTCPay does not
+mark the invoice as settled without independent settlement confirmation.
 
 BTCPay final settlement should be based on independent BTC wallet/on-chain
 confirmation for the merchant-controlled settlement address.
 
 | MakePay state                       | BTCPay behavior                                                                |
 | ----------------------------------- | ------------------------------------------------------------------------------ |
-| `complete`                          | Records a Processing MakePay payment with session and deposit metadata.        |
+| `deposit_received`                  | Records a Processing payment and publishes the native Received Payment event.  |
+| `swapping`, `sending`, or `complete` | Records the same payment if an earlier status callback was missed.             |
 | `failed`, `expired`, or `cancelled` | Shows the state without recording a settled payment.                           |
 | `underpaid`                         | Keeps the prompt unsettled so the invoice can be handled by policy or support. |