BitPay migration

# Migrate BitPay to MakePay

Use this as the working brief for an AI coding agent. Replace BitPay invoice creation, IPN-triggered status reconciliation, invoice-state handling, request signing, and provider SDK/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

- BitPay `POST /invoices` invoice creation -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- BitPay invoice `url` -> MakePay `paymentLink.publicUrl`.
- BitPay invoice `id` or `invoiceId` -> MakePay `paymentLink.uid`; keep the old invoice ID in a migration alias table while orders are in flight.
- BitPay `price` and `currency` -> MakePay `payload.amount` and `payload.currency` or exact `payload.asset`.
- BitPay `orderId`, `itemDesc`, `posData`, and `guid` -> MakePay `merchantOrderId`, `label`, `description`, and internal metadata.
- BitPay `notificationURL` -> MakePay webhook callback URL configured in MakeCrypto.
- BitPay `redirectURL`, `closeURL`, and `autoRedirect` -> MakePay success/failure redirect settings or hosted-page return handling.
- BitPay `token`, `X-Accept-Version`, optional `X-Identity`, and optional `X-Signature` request signing -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers.
- BitPay unsigned-by-default IPNs plus follow-up `GET /invoices/:invoiceId` verification -> MakePay signed webhook verification from `x-makepay-signature` over the raw request body.
- BitPay states `new`, `paid`, `confirmed`, `complete`, `expired`, and `invalid` plus exception states `paidPartial` and `paidOver` -> MakePay `makepay.payment.status_changed` events and normalized order states.

## Agent prompt: inventory

You are migrating this repository from BitPay to MakePay. Search for BitPay API clients, `bitpay.com/invoices`, `/invoices`, `invoiceId`, invoice `url`, `token`, `X-Accept-Version`, `X-Identity`, `X-Signature`, `notificationURL`, `redirectURL`, `closeURL`, `transactionSpeed`, `posData`, `guid`, IPN handlers, and enum handling for `new`, `paid`, `confirmed`, `complete`, `expired`, `invalid`, `paidPartial`, and `paidOver`. Return a file-by-file migration plan with the exact functions that create invoices, store provider IDs, redirect buyers, receive IPNs, fetch invoice status, and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice creation

Implement MakePay payment-link creation in the existing BitPay invoice creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Map BitPay `price` to `payload.amount`, `currency` to `payload.currency` or `payload.asset`, `orderId` to `merchantOrderId`, `itemDesc` to `label` or `description`, and any serialized `posData`/`guid` to internal metadata. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy BitPay invoice ID fields for historical records.

## Agent prompt: replace IPN verification

Replace BitPay IPN-triggered reconciliation with MakePay webhook verification. For legacy BitPay orders, keep the rule that IPNs are not trusted by default and must trigger a follow-up invoice fetch before fulfillment. 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.

## Agent prompt: normalize statuses

Map legacy BitPay statuses explicitly during cutover. `new` and `paid` should not grant goods by default. `confirmed` can complete the order only if the existing business accepted BitPay confirmed status. `complete` is the safest paid state. `expired` and `invalid` should close the legacy payment without marking the order paid. `paidPartial` and `paidOver` exception states should go to manual review or the existing refund/underpayment path.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing BitPay invoices can still receive IPNs until they settle, fail, expire, or become invalid. Route callbacks by provider, keep provider-specific IDs separate, and add logs that include provider, order ID, payment UID, delivery ID, legacy invoice ID, and normalized status. Remove BitPay credentials and request-signing code only after there are no open legacy orders.

## 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 BitPay IPN routing during cutover, BitPay `paid` not granting goods, `confirmed`/`complete` handling, partial/overpaid exception handling, expired/invalid invoice handling, 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 a BitPay invoice `url`.
- Webhook verification fails closed when `x-makepay-signature` is missing, stale, or invalid.
- Webhooks are idempotent by delivery ID and cannot regress a completed order.
- Legacy BitPay IPNs remain trigger-only and fetch invoice status before fulfillment.
- Legacy `paid`, `confirmed`, `complete`, `expired`, `invalid`, `paidPartial`, and `paidOver` paths are explicitly tested.
- Existing BitPay orders remain reconcilable until the migration flag is fully removed.