Confirmo migration

# Migrate Confirmo to MakePay

Use this as the working brief for an AI coding agent. Replace Confirmo invoice creation, hosted invoice URLs, invoice overlay events, webhook notification verification, invoice detail polling, exception handling, take-request/manual acceptance flows, refund links, status reconciliation, and provider API usage with MakePay payment links, signed webhooks, and the SDK that matches the codebase.

## Target MakePay SDK

Choose one install command for the stack being migrated:

```bash
npm install @makecrypto/makepay
composer require makepay/makepay-php
go get github.com/makecryptoio/makepay-go
pip install makepay
cargo add makepay
```

For JVM services use:

```kotlin
implementation("io.makecrypto:makepay:0.1.0")
```

For Swift Package Manager use:

```swift
.package(url: "https://github.com/makecryptoio/makepay-swift-sdk.git", from: "0.3.0")
```

## Migration map

- Confirmo `https://confirmo.net/api/v3` base URL -> MakeCrypto company/API credential configuration.
- Confirmo `Authorization: Bearer {CONFIRMO_API_KEY}` -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials.
- Confirmo `POST /api/v3/invoices` -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- Confirmo invoice `id` -> MakePay `paymentLink.uid`; keep the old invoice ID in a migration alias table while orders are in flight.
- Confirmo invoice `url` -> MakePay `paymentLink.publicUrl`.
- Confirmo `invoice.amount` and `invoice.currencyFrom` -> MakePay `payload.amount` and `payload.currency`.
- Confirmo `invoice.currencyTo` and `invoice.layer2ProtocolName` -> MakePay exact `payload.asset` only when the business must force buyer assets.
- Confirmo `settlement.currency` -> settlement/business configuration or internal metadata.
- Confirmo `product.name` and `product.description` -> MakePay `label` and `description`.
- Confirmo `reference`, customer email/name/order JSON, and order numbers -> MakePay `merchantOrderId`, `clientEmail`, and internal metadata.
- Confirmo `returnUrl`, `notifyUrl`, and `notifyEmail` -> MakePay hosted-page redirect handling plus MakePay webhook endpoint.
- Confirmo checkout QR code, `address`, `cryptoUri`, `crypto.currency`, `crypto.amount`, and txids -> hosted MakePay checkout state; avoid storing provider artifacts as order URLs.
- Confirmo `@confirmo/overlay`, custom iframe, `CLOSE_CONFIRMO_OVERLAY`, and `CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE` -> MakePay hosted checkout, embedded checkout route, or modal script.
- Confirmo `bp-signature` SHA256(payload + callback password) webhook header -> MakePay `x-makepay-signature` HMAC verification over the raw request body.
- Confirmo webhook body containing the full invoice model -> MakePay payment events or legacy Confirmo handling during cutover.
- Confirmo direct `GET /api/v3/invoices/{id}` verification after final webhooks -> MakePay payment-link lookup and webhook replay/reconciliation tooling.
- Confirmo `GET /api/v3/invoices` list/filter reconciliation -> MakePay reconciliation jobs and internal payment reporting.
- Confirmo statuses `prepared`, `pending_verification`, `active`, `confirming`, `paid`, `expired`, `error`, and `blocked` -> MakePay normalized pending, paid, expired, failed, blocked, and manual-review states.
- Confirmo `unhandledExceptions`, overpayment, underpayment, delayed payment, `overUnderPaidAmount`, and `exception` -> MakePay manual-review, underpayment, overpayment, and late-payment handling.
- Confirmo `POST /api/v3/invoices/{id}/take` and confirm take request -> MakePay manual acceptance or support workflow.
- Confirmo `refundLink`, invoice refunds, and payout/refund state -> MakePay refund or manual support workflow.

## Agent prompt: inventory

You are migrating this repository from Confirmo to MakePay. Search for Confirmo API clients, `confirmo.net/api/v3`, `/api/v3/invoices`, `/api/v3/invoices/{id}`, `/api/v3/invoices/{id}/take`, `Authorization: Bearer`, `CONFIRMO_API_KEY`, callback password, `bp-signature`, `notifyUrl`, `notifyurl`, `notifyEmail`, `returnUrl`, `reference`, `product.name`, `product.description`, `invoice.amount`, `invoice.currencyFrom`, `invoice.currencyTo`, `invoice.layer2ProtocolName`, `settlement.currency`, `id`, `url`, `address`, `cryptoUri`, `customerAmount`, `merchantAmount`, `settlementAmount`, `rate`, `paid`, `paidSince`, `paidAtTime`, `completedAtTime`, `cryptoTransactions`, `txids`, `confirmations`, `requiredConfirmations`, `refundLink`, `refunds`, `unhandledExceptions`, `overUnderPaidAmount`, `exception`, `@confirmo/overlay`, `CLOSE_CONFIRMO_OVERLAY`, `CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE`, `prepared`, `pending_verification`, `active`, `confirming`, `paid`, `expired`, `error`, `blocked`, and invoice detail polling. Return a file-by-file migration plan with the exact functions that create Confirmo invoices, store invoice IDs, redirect or open overlay checkout, render QR/address checkout data, verify bp-signature notifications, fetch invoice details, list invoices for reconciliation, process take requests or manual acceptance, process refund links, and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice creation

Implement MakePay payment-link creation in the existing Confirmo invoice creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Remove Confirmo `Authorization: Bearer` usage from the new-order path. Map `invoice.amount` to `payload.amount`, `invoice.currencyFrom` to `payload.currency`, `invoice.currencyTo` and `invoice.layer2ProtocolName` to `payload.asset` only when the business must force a buyer asset or Lightning/native-chain method, `settlement.currency` to settlement/business metadata, `product.name` to `label`, `product.description` to `description`, `reference`/order JSON to `merchantOrderId` and internal metadata, customer email to `clientEmail`, `notifyUrl` to the MakePay webhook endpoint, and `returnUrl` to MakePay redirect handling. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy Confirmo invoice ID fields for historical records.

## Agent prompt: replace hosted checkout and overlay artifacts

Replace Confirmo invoice `url` redirects with MakePay `paymentLink.publicUrl`. For Confirmo embedded checkout, remove `@confirmo/overlay`, Confirmo custom iframe code, `CLOSE_CONFIRMO_OVERLAY` handlers, and `CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE` handlers for new MakePay orders. Use MakePay hosted checkout, embedded checkout route, or modal script depending on the existing UX. Do not carry forward Confirmo QR codes, `address`, `cryptoUri`, `crypto.amount`, `crypto.currency`, `customerAmount`, payment asset, `txids`, or `cryptoTransactions` as the primary order URL for new MakePay orders; those are provider-specific checkout artifacts.

## Agent prompt: replace webhook verification

Replace Confirmo notification handling with MakePay webhook verification. For legacy Confirmo notifications, preserve `bp-signature` verification until open Confirmo invoices are closed: read the exact raw `application/json` request body, append the Confirmo callback password as a suffix, compute SHA256, compare the hex digest against the `bp-signature` header with a timing-safe compare, and only then parse/process the JSON. After any final or fulfillment-relevant legacy notification such as `paid`, call the Confirmo GET invoice detail endpoint before granting goods because Confirmo recommends direct verification after final webhooks. For new MakePay events, read the exact raw request body before JSON parsing, parse `x-makepay-signature`, verify timestamp tolerance and HMAC digest with the MakePay webhook secret, then process only trusted events. Treat `makepay.payment.status_changed` as the primary order reconciliation event and make updates idempotent by delivery ID and payment-link UID. For legacy Confirmo notifications, use invoice `id` plus status, `paidSince`/`paidAtTime`, `txids`/`cryptoTransactions`, and `completedAtTime` for idempotency.

## Agent prompt: normalize statuses

Map legacy Confirmo statuses explicitly during cutover. `prepared`, `pending_verification`, and `active` should not grant goods. `confirming` means a payment has been detected and should remain pending until `paid`. `paid` can complete the order only after amount, currency, invoice ID, reference/order, and provider checks pass, preferably after direct invoice-detail verification. `expired` should close the payment unless `unhandledExceptions` or delayed/partial payment business rules require manual review. `error` and `blocked` should close the payment or route to manual review without marking it paid. Overpayment, underpayment, delayed payment, `unhandledExceptions`, `overUnderPaidAmount`, and `exception` entries should route to explicit manual-review, overpaid, underpaid, late-payment, refund, or take-request handling.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing Confirmo invoices can still receive notifications and invoice-detail/list polling until they are paid, expired, errored, blocked, refunded, manually accepted, exception-resolved, or manually closed through the current business rules. Route callbacks by provider, keep provider-specific IDs separate, and add logs that include provider, order ID, payment UID, delivery ID, legacy Confirmo invoice ID, status, reference, `merchantAmount`, `customerAmount`, `settlementAmount`, `cryptoTransactions`/`txids`, confirmations, `requiredConfirmations`, `unhandledExceptions`, `overUnderPaidAmount`, `refundLink`, and normalized status. Remove Confirmo API keys, callback passwords, `bp-signature` verification, `@confirmo/overlay` code, custom iframe handlers, invoice `url` redirects, QR/address/`cryptoUri` rendering, invoice detail/list polling, take-request code, and refund-link code only after there are no open legacy Confirmo invoices.

## Agent prompt: tests

Add or update tests for MakePay payment-link creation, failed authentication, webhook signature rejection, successful `makepay.payment.status_changed` handling, duplicate webhook delivery idempotency, legacy Confirmo notification routing during cutover, `bp-signature` rejection, required GET invoice-detail verification before fulfillment, invoice `url` replacement, `@confirmo/overlay` removal, QR/address/`cryptoUri` artifact removal, prepared/pending_verification/active not granting goods, confirming pending behavior, paid completion, expired closure, error/blocked closure, `unhandledExceptions` manual review, overpayment, underpayment, delayed payment, take-request/manual acceptance policy, refund link handling, legacy invoice list reconciliation, and buyer redirect URL generation. Use mocked MakePay SDK/API responses; do not hit production APIs in tests.

## Verification checklist

- A new order creates exactly one MakePay payment link and stores `paymentLink.uid`.
- The buyer redirect uses `paymentLink.publicUrl` instead of Confirmo invoice `url`.
- New-order code no longer sends Confirmo `Authorization: Bearer` invoice requests.
- New MakePay orders do not store Confirmo QR codes, addresses, crypto URIs, or transaction IDs as order URLs.
- New MakePay orders no longer load `@confirmo/overlay` or depend on Confirmo overlay postMessage events.
- Webhook verification fails closed when `x-makepay-signature` is missing, stale, or invalid.
- `makepay.payment.status_changed` handling is idempotent by delivery ID.
- Completed orders cannot be regressed by delayed provider events.
- Legacy Confirmo notifications keep `bp-signature` verification until cutover is complete.
- Legacy final-status webhooks verify the invoice through Confirmo GET invoice detail before fulfillment.
- Legacy prepared, pending_verification, active, confirming, paid, expired, error, blocked, exception, refund, and take-request paths are explicitly tested.
- Existing Confirmo invoices still reconcile until the migration flag is removed.