BVNK migration

# Migrate BVNK to MakePay

Use this as the working brief for an AI coding agent. Replace BVNK Hawk authentication, hosted crypto payment creation, redirectUrl checkout, reusable channel-address flows, x-signature webhook verification, payment-summary polling, 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

- BVNK Hawk Auth ID and Hawk Auth Key -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials.
- BVNK `Authorization: Hawk ...` HMAC-SHA256 request signing -> MakePay SDK client configuration or credential headers.
- BVNK `POST /api/v1/pay/summary` with `type: "IN"` -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- BVNK response `redirectUrl` -> MakePay `paymentLink.publicUrl`.
- BVNK response/payment `uuid` -> MakePay `paymentLink.uid`; keep the old UUID in a migration alias table while orders are in flight.
- BVNK `reference` -> MakePay `merchantOrderId` plus internal metadata.
- BVNK `walletId`, `merchantId`, and merchant display settings -> MakeCrypto company/API credential configuration.
- BVNK `amount`, `currency`, `displayCurrency`, and `walletCurrency` -> MakePay `payload.amount` and `payload.currency` or exact `payload.asset`.
- BVNK `returnUrl` -> MakePay success/failure redirect settings or hosted-page return handling.
- BVNK `acceptanceExpiryDate`, `quoteExpiryDate`, and `expiryDate` -> MakePay payment-link expiry and underpayment/late-payment business rules.
- BVNK `address.uri`, `address.address`, `protocol`, and `alternatives` -> hosted MakePay checkout state; avoid storing deposit addresses as order URLs.
- BVNK `GET /api/v1/pay/{uuid}/summary` reconciliation -> MakePay payment-link lookup and webhook replay/reconciliation tooling.
- BVNK channel pay-in address flow -> MakePay payment links for per-order checkout; keep channels only for legacy top-ups.
- BVNK webhook `x-signature` HMAC-SHA256 over the raw JSON payload -> MakePay `x-makepay-signature` HMAC verification over the raw request body.
- BVNK webhook `eventId`, `event`, `data.uuid`, and transaction hashes -> MakePay delivery ID plus `paymentLink.uid` idempotency.
- BVNK `bvnk:payment:crypto:status-change` events -> MakePay `makepay.payment.status_changed` events and normalized order states.
- BVNK channel detected, confirmed, and on-hold webhooks -> MakePay payment events or legacy channel handling during cutover.
- BVNK statuses `PENDING`, `PROCESSING`, `COMPLETE`, `UNDERPAID`, `EXPIRED`, `DETECTED`, `CANCELLED`, and on-hold states -> MakePay normalized paid, pending, failed, underpaid, and manual-review states.

## Agent prompt: inventory

You are migrating this repository from BVNK to MakePay. Search for BVNK API clients, `api.bvnk.com`, `api.sandbox.bvnk.com`, Hawk Auth ID, Hawk Auth Key, `Authorization: Hawk`, HmacSHA256/HMAC-SHA256 request signing helpers, `/api/v1/pay/summary`, `/api/v1/pay/{uuid}/summary`, `redirectUrl`, `uuid`, `walletId`, `merchantId`, `reference`, `returnUrl`, `amount`, `currency`, `displayCurrency`, `walletCurrency`, `paidCurrency`, `acceptanceExpiryDate`, `quoteExpiryDate`, `expiryDate`, `address.uri`, `address.address`, `protocol`, `channelId`, channel-address flows, `bvnk:payment:crypto:status-change`, `bvnk:payment:channel:transaction-detected`, `bvnk:payment:channel:transaction-confirmed`, `bvnk:payment:channel:transaction-on-hold`, `x-signature`, `eventId`, `data.uuid`, `transactions[].hash`, and status handling for `PENDING`, `PROCESSING`, `COMPLETE`, `UNDERPAID`, `EXPIRED`, `DETECTED`, `CANCELLED`, and on-hold states. Return a file-by-file migration plan with the exact functions that sign requests, create BVNK payments, store provider UUIDs/references, redirect buyers, verify webhooks, fetch payment summaries, process channel deposits, and reconcile order status. Do not edit files yet.

## Agent prompt: replace payment creation

Implement MakePay payment-link creation in the existing BVNK hosted-payment creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Remove Hawk Authorization generation from the new-order path. Map BVNK `reference` to `merchantOrderId`, `amount` to `payload.amount`, `currency`/`displayCurrency` or forced settlement requirements to `payload.currency` or `payload.asset`, and `returnUrl` to MakePay redirect handling. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy BVNK uuid/reference fields for historical records.

## Agent prompt: replace hosted checkout and channel flows

Replace BVNK `redirectUrl` redirects with MakePay `paymentLink.publicUrl`. Do not carry forward BVNK `address.uri`, `address.address`, crypto URI, or `protocol` fields as the primary order URL for new MakePay orders; those are provider-specific deposit artifacts. Find any BVNK channel pay-in flow that assigns reusable channel addresses for top-ups. For one-off order checkout, replace it with MakePay payment links so each order has a `paymentLink.uid` and `paymentLink.publicUrl`. If the product still needs reusable top-up addresses, keep the legacy channel flow behind a provider flag until all old channel deposits and webhooks are reconciled, then design a MakePay-native top-up flow separately.

## Agent prompt: replace webhook verification

Replace BVNK webhook verification with MakePay webhook verification. For legacy BVNK payments and channel deposits, keep `x-signature` verification by computing base64(HMAC-SHA256(raw JSON payload, webhook public/secret key string as UTF-8)) with the exact raw request body and comparing it with a timing-safe compare. Always acknowledge only after the signature and idempotency checks pass, and keep BVNK payment-summary lookups for legacy callbacks when the current code relies on them. 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 BVNK webhooks, use `eventId` plus `data.uuid` or transaction hash for idempotency.

## Agent prompt: normalize statuses

Map legacy BVNK statuses explicitly during cutover. `PENDING` should not grant goods. `PROCESSING` should remain pending until a final status arrives. `COMPLETE` can complete the order once amount and currency match the order policy. `UNDERPAID` should route to underpayment/manual-review or partial-credit handling. `EXPIRED` and `CANCELLED` should close the payment without marking it paid. Channel `DETECTED` should remain pending; channel `COMPLETE` can credit the customer only after amount, currency, and risk checks pass. On-hold events should route to risk/manual review and must not grant goods automatically.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing BVNK payments and channel deposits can still receive webhooks and payment-summary polling until they are complete, underpaid, expired, cancelled, on hold, refunded, 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 BVNK uuid, reference, eventId, channelId, transaction hash, status, and normalized status. Remove BVNK Hawk credentials, Hawk signing helpers, redirectUrl handling, x-signature callback verification, payment-summary polling, and channel creation code only after there are no open legacy BVNK payments or channel deposits.

## 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 BVNK webhook routing during cutover, BVNK x-signature rejection, redirectUrl replacement, channel-to-payment-link replacement, PENDING/PROCESSING not granting goods, COMPLETE completion, UNDERPAID manual review, EXPIRED/CANCELLED closure, on-hold risk handling, legacy payment-summary polling fallback, 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 BVNK `redirectUrl`.
- New-order code no longer generates Hawk Authorization headers for hosted checkout.
- New MakePay orders do not store BVNK deposit addresses or crypto URIs as order URLs.
- 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 BVNK webhooks keep `x-signature` HMAC verification until cutover is complete.
- Legacy pending/processing/complete/underpaid/expired/detected/cancelled/on-hold paths are explicitly tested.
- Existing BVNK payments and channel deposits remain reconcilable until the migration flag is fully removed.