CoinPayments migration

# Migrate CoinPayments to MakePay

Use this as the working brief for an AI coding agent. Replace CoinPayments REST invoices, legacy `/api.php` create_transaction calls, hosted checkout URLs, IPN/webhook verification, status polling, 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

- CoinPayments new API regional base URL such as `https://a-api.coinpayments.net/api` -> MakeCrypto company/API credential configuration.
- CoinPayments `X-CoinPayments-Client`, `X-CoinPayments-Timestamp`, and `X-CoinPayments-Signature` auth -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials.
- Legacy CoinPayments `/api.php` with `key`, `cmd`, and `HMAC` SHA-512 over raw POST data -> MakePay SDK client configuration or credential headers.
- CoinPayments new `POST /merchant/invoices` -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- Legacy CoinPayments `cmd=create_transaction` -> MakePay payment-link creation.
- CoinPayments invoice `link`, `checkoutLink`, and legacy `checkout_url` -> MakePay `paymentLink.publicUrl`.
- CoinPayments new invoice `id` or legacy `txn_id` -> MakePay `paymentLink.uid`; keep the old provider ID in a migration alias table while orders are in flight.
- CoinPayments invoice `currency`, invoice items, and `payment.refundEmail` -> MakePay `payload.amount`, `payload.currency` or `payload.asset`, `label`, and client data.
- Legacy CoinPayments `amount`, `currency1`, `currency2`, `buyer_email`, `item_name`, `item_number`, `invoice`, and `custom` -> MakePay amount/currency/client/order metadata fields.
- Legacy CoinPayments `address`, `dest_tag`, `qrcode_url`, `confirms_needed`, `timeout`, and `status_url` -> hosted MakePay checkout state; avoid storing deposit artifacts as order URLs.
- CoinPayments legacy `ipn_url` and new webhooks -> MakePay webhook endpoint and `x-makepay-signature` verification.
- Legacy CoinPayments IPN `HMAC` header, IPN Secret, `merchant`, `ipn_id`, `ipn_type`, `txn_id`, and `send_tx` -> MakePay delivery ID plus `paymentLink.uid` idempotency.
- Legacy CoinPayments `get_tx_info` and `get_tx_info_multi` reconciliation -> MakePay payment-link lookup and webhook replay/reconciliation tooling.
- Legacy CoinPayments statuses `-2`, `-1`, `0`, `1`, `2`, `3`, `100`, and future `>=100` rules -> MakePay normalized paid, pending, failed, underpaid, and manual-review states.
- CoinPayments wallet/address collection flows -> MakePay payment links for per-order checkout; keep addresses only for legacy top-ups.

## Agent prompt: inventory

You are migrating this repository from CoinPayments to MakePay. Search for CoinPayments API clients, `coinpayments.net/api.php`, `legacy.coinpayments.net`, `a-api.coinpayments.net`, `b-api.coinpayments.net`, `c-api.coinpayments.net`, `create_transaction`, `cmd`, `key`, `HMAC`, SHA-512 request signing, IPN Secret, `ipn_url`, `ipn_mode`, `ipn_id`, `merchant`, `txn_id`, `checkout_url`, `status_url`, `qrcode_url`, `address`, `dest_tag`, `confirms_needed`, `timeout`, `amount`, `currency1`, `currency2`, `buyer_email`, `item_name`, `item_number`, `invoice`, `custom`, `get_tx_info`, `get_tx_info_multi`, `X-CoinPayments-Client`, `X-CoinPayments-Timestamp`, `X-CoinPayments-Signature`, `POST /merchant/invoices`, `link`, `checkoutLink`, `payment.refundEmail`, `payoutOverrides`, wallet/address collection flows, and status handling for `-2`, `-1`, `0`, `1`, `2`, `3`, `100`, and `>=100`. Return a file-by-file migration plan with the exact functions that sign requests, create CoinPayments invoices or transactions, store provider IDs, redirect buyers, verify IPNs/webhooks, fetch transaction or invoice status, and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice and transaction creation

Implement MakePay payment-link creation in the existing CoinPayments invoice or transaction creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. For new CoinPayments REST invoices, map invoice amount/items to `payload.amount`, currency or settlement requirements to `payload.currency` or `payload.asset`, `payment.refundEmail` to `clientEmail`, and invoice/customer text to `label` and `description`. For legacy `create_transaction` calls, map `amount` to `payload.amount`, `currency1` or the existing order currency to `payload.currency`, `currency2` to an exact asset only when the business must force the buyer asset, `buyer_email` to `clientEmail`, `item_name` to `label`, and `item_number`/`invoice`/`custom` to `merchantOrderId` or internal metadata. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy CoinPayments invoice ID or txn_id fields for historical records.

## Agent prompt: replace hosted checkout and deposit artifacts

Replace CoinPayments invoice `link`, `checkoutLink`, and legacy `checkout_url` redirects with MakePay `paymentLink.publicUrl`. Do not carry forward CoinPayments `address`, `dest_tag`, `status_url`, `qrcode_url`, `confirms_needed`, or `timeout` fields as the primary order URL for new MakePay orders; those are provider-specific deposit artifacts. Find any CoinPayments wallet/address collection flow that assigns reusable or temporary deposit addresses for customer 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 address flow behind a provider flag until all old deposits and webhooks are reconciled, then design a MakePay-native top-up flow separately.

## Agent prompt: replace IPN and webhook verification

Replace CoinPayments IPN/webhook handling with MakePay webhook verification. For legacy CoinPayments IPNs, keep HMAC verification by reading the exact raw `application/x-www-form-urlencoded` body, computing HMAC-SHA512 with the IPN Secret, comparing against the `HMAC` header with a timing-safe compare, and checking the merchant ID before processing. For new CoinPayments webhooks, keep `X-CoinPayments-Client`, `X-CoinPayments-Timestamp`, and `X-CoinPayments-Signature` verification plus sender/IP validation until legacy events 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. For legacy CoinPayments IPNs, use `ipn_id` plus `txn_id` or `send_tx` for idempotency.

## Agent prompt: normalize statuses

Map legacy CoinPayments statuses explicitly during cutover. Negative statuses such as `-2` and `-1` should close the payment without marking the order paid. `0`, `1`, and `3` should remain pending or manual review and must not grant goods. Status `2` is queued for nightly payout; keep the existing business decision, but prefer waiting for `>=100` unless the current integration already fulfilled on status `2`. Status `100` and any future `>=100` status can complete the order only after amount, currency, merchant, and provider ID checks pass. For new CoinPayments invoices/webhooks, map provider invoice or transaction states into the same internal paid, pending, failed, underpaid, and manual-review states before switching that code path to MakePay.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing CoinPayments invoices, legacy transactions, and address deposits can still receive IPNs/webhooks and status polling until they are complete, failed, cancelled, timed out, 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 invoice ID, txn_id, ipn_id, send_tx, merchant, status, status_text, and normalized status. Remove CoinPayments API keys, client secrets, HMAC signing helpers, IPN Secret verification, checkout_url/link/checkoutLink handling, status polling, and wallet/address collection code only after there are no open legacy CoinPayments payments or 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 CoinPayments IPN routing during cutover, legacy HMAC rejection, new `X-CoinPayments-Signature` rejection, checkout_url/link/checkoutLink replacement, address/dest_tag/QR artifact removal, negative status closure, pending statuses not granting goods, status `2` policy handling, status `>=100` completion, amount/currency mismatch handling, legacy `get_tx_info` 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 CoinPayments `link`, `checkoutLink`, or legacy `checkout_url`.
- New-order code no longer signs CoinPayments REST or legacy `/api.php` requests.
- New MakePay orders do not store CoinPayments deposit addresses, destination tags, QR URLs, or status URLs 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 CoinPayments IPNs keep `HMAC` and merchant-ID verification until cutover is complete.
- Legacy new-platform CoinPayments webhooks keep `X-CoinPayments-Signature` verification until cutover is complete.
- Legacy negative, pending, queued, and complete statuses are explicitly tested.
- Existing CoinPayments invoices, transactions, and address deposits remain reconcilable until the migration flag is fully removed.