Cryptomus migration

# Migrate Cryptomus to MakePay

Use this as the working brief for an AI coding agent. Replace Cryptomus invoice creation, MD5/base64 request signing, webhook signature verification, payment-status reconciliation, 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

- Cryptomus `POST https://api.cryptomus.com/v1/payment` invoice creation -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- Cryptomus response `url` -> MakePay `paymentLink.publicUrl`.
- Cryptomus `uuid` -> MakePay `paymentLink.uid`; keep the old Cryptomus UUID in a migration alias table while orders are in flight.
- Cryptomus `order_id` -> MakePay `merchantOrderId`.
- Cryptomus `amount` and `currency` -> MakePay `payload.amount` and `payload.currency` or exact `payload.asset`.
- Cryptomus `to_currency`, `network`, and `payer_currency` -> MakePay destination asset selection when the merchant must force settlement asset or chain.
- Cryptomus `url_callback` -> MakePay webhook callback URL configured in MakeCrypto.
- Cryptomus `url_return` and `url_success` -> MakePay success/failure redirect settings or hosted-page return handling.
- Cryptomus `additional_data` -> internal metadata stored next to the MakePay payment link.
- Cryptomus `merchant` header and request `sign` MD5(base64(JSON) + API key) -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers.
- Cryptomus webhook body `sign` plus optional IP allowlist -> MakePay `x-makepay-signature` HMAC verification over the raw request body.
- Cryptomus statuses `check`, `process`, `confirm_check`, `paid`, `paid_over`, `wrong_amount`, `wrong_amount_waiting`, `fail`, `cancel`, `system_fail`, `refund_process`, `refund_fail`, `refund_paid`, and `locked` -> MakePay `makepay.payment.status_changed` events and normalized order states.

## Agent prompt: inventory

You are migrating this repository from Cryptomus to MakePay. Search for Cryptomus API clients, `api.cryptomus.com`, `/v1/payment`, `merchant` headers, `sign` generation, MD5/base64 signing helpers, `url_callback`, `url_return`, `url_success`, invoice `url`, `uuid`, `order_id`, `amount`, `currency`, `to_currency`, `network`, `additional_data`, webhook handlers, webhook body `sign`, IP allowlists, and status handling for `check`, `process`, `confirm_check`, `paid`, `paid_over`, `wrong_amount`, `wrong_amount_waiting`, `fail`, `cancel`, `system_fail`, `refund_process`, `refund_fail`, `refund_paid`, and `locked`. Return a file-by-file migration plan with the exact functions that create invoices, store provider IDs, redirect buyers, verify webhooks, and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice creation

Implement MakePay payment-link creation in the existing Cryptomus invoice creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Map Cryptomus `amount` to `payload.amount`, `currency` or forced settlement requirements from `to_currency`/`network` to `payload.currency` or `payload.asset`, `order_id` to `merchantOrderId`, and `additional_data` to internal metadata. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy Cryptomus UUID fields for historical records.

## Agent prompt: replace webhook verification

Replace Cryptomus webhook verification with MakePay webhook verification. For legacy Cryptomus orders, keep existing body `sign` verification by removing `sign` from the payload, recreating MD5(base64(JSON) + payment API key), using timing-safe comparison, and preserving any IP allowlist until legacy orders are closed. 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 Cryptomus statuses explicitly during cutover. `check`, `process`, `confirm_check`, and `wrong_amount_waiting` should not grant goods by default. `paid` can complete the order. `paid_over` can complete the order but should preserve an overpayment note. `wrong_amount`, `fail`, `cancel`, and `system_fail` should not mark the order paid. `refund_process`, `refund_fail`, `refund_paid`, and `locked` should route through refund/risk/manual-review flows.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing Cryptomus invoices can still receive webhooks until they are paid, cancelled, failed, refunded, locked, or expire 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 Cryptomus UUID, and normalized status. Remove Cryptomus credentials, MD5/base64 signing helpers, and IP allowlist code only after there are no open legacy 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 Cryptomus webhook routing during cutover, Cryptomus signature rejection, check/process/confirm_check not granting goods, paid and paid_over handling, wrong_amount handling, fail/cancel/system_fail handling, refund/locked 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 Cryptomus response `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 Cryptomus webhooks keep body `sign` verification until cutover is complete.
- Legacy check/process/confirm_check/paid/paid_over/wrong_amount/fail/cancel/system_fail/refund/locked paths are explicitly tested.
- Existing Cryptomus invoices remain reconcilable until the migration flag is fully removed.