Triple-A migration

# Migrate Triple-A to MakePay

Use this as the working brief for an AI coding agent. Replace Triple-A OAuth token handling, payment creation, hosted_url redirects, embedded widget flows, notify_url callbacks, notify_secret/shared-secret checks, payment-detail 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

- Triple-A `POST /api/v2/oauth/token` client-credentials token flow -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials.
- Triple-A `Authorization: Bearer <token>` -> MakePay credential headers or SDK client configuration.
- Triple-A `POST /api/v2/payment` payment creation -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- Triple-A `type: "triplea"` external payment form -> MakePay hosted `paymentLink.publicUrl`.
- Triple-A `type: "widget"` embedded payment form -> MakePay embedded checkout route or modal script.
- Triple-A response `hosted_url` -> MakePay `paymentLink.publicUrl`.
- Triple-A `payment_reference` -> MakePay `paymentLink.uid`; keep the old payment reference in a migration alias table while orders are in flight.
- Triple-A `merchant_key` -> MakeCrypto company/API credential configuration.
- Triple-A `order_id` and `webhook_data.order_id` -> MakePay `merchantOrderId` plus internal metadata.
- Triple-A `order_amount` and `order_currency` -> MakePay `payload.amount` and `payload.currency` or exact `payload.asset`.
- Triple-A `success_url` and `cancel_url` -> MakePay success/failure redirect settings or hosted-page return handling.
- Triple-A `notify_url`, `notify_email`, `notify_txs`, and `notify_secret` -> MakePay webhook endpoint and `x-makepay-signature` verification.
- Triple-A payer fields and `required_payer_data` -> customer metadata, pre-checkout validation, or order profile data.
- Triple-A `GET /api/v2/payment/:payment_reference?verbose=0` status lookup -> MakePay payment-link lookup and webhook replay/reconciliation tooling.
- Triple-A `status`, `payment_tier`, `txs[].status`, and `txs[].payment_tier` -> MakePay `makepay.payment.status_changed` events and normalized order states.
- Triple-A `crypto_address`, `crypto_amount`, `crypto_uri`, and `expires_in` -> hosted MakePay checkout state; avoid storing deposit addresses as order URLs.

## Agent prompt: inventory

You are migrating this repository from Triple-A to MakePay. Search for Triple-A API clients, `api.triple-a.io`, `/api/v2/oauth/token`, `/api/v2/payment`, payment details lookup by `payment_reference`, bearer token caching, `merchant_key`, `payment_reference`, `hosted_url`, `access_token`, `type: "triplea"`, `type: "widget"`, `order_currency`, `order_amount`, `order_id`, `webhook_data`, `notify_url`, `notify_email`, `notify_secret`, `notify_txs`, `success_url`, `cancel_url`, payer fields, `required_payer_data`, `crypto_address`, `crypto_amount`, `crypto_uri`, `expires_in`, `payment_tier`, `txs`, webhook handlers, and status handling for `none`, `short`, `hold`, `good`, and `invalid`. Return a file-by-file migration plan with the exact functions that obtain tokens, create payments, store provider references, redirect buyers, verify callbacks, fetch payment details, and reconcile order status. Do not edit files yet.

## Agent prompt: replace payment creation

Implement MakePay payment-link creation in the existing Triple-A payment creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Remove Triple-A bearer token fetching and `merchant_key` usage from the new-order path. Map `order_amount` to `payload.amount`, `order_currency` to `payload.currency` or `payload.asset`, `order_id` or `webhook_data.order_id` to `merchantOrderId`, payer fields to customer metadata, and cart or product text to `label` and `description`. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy Triple-A `payment_reference` fields for historical records.

## Agent prompt: replace hosted and widget checkout

Replace Triple-A `hosted_url` redirects with MakePay `paymentLink.publicUrl`. For legacy `type=triplea` external payment pages, redirect buyers to the MakePay hosted payment URL. For legacy `type=widget` embedded forms, use the MakePay embedded checkout route or modal script and keep the host page responsible for redirect handling. Do not carry forward Triple-A `crypto_address`, `crypto_amount`, or `crypto_uri` as the primary order URL for new MakePay orders; those are provider-specific deposit artifacts.

## Agent prompt: replace webhook verification

Replace Triple-A webhook handling with MakePay webhook verification. For legacy Triple-A payments, preserve the existing `notify_secret`/shared-secret check and `payment_reference` routing until open payments 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 Triple-A callbacks, use `payment_reference` plus any callback transaction identifier or tx hash for idempotency.

## Agent prompt: normalize statuses

Map legacy Triple-A statuses explicitly during cutover. `none` should not grant goods. `short` should route to underpayment/manual-review handling. `hold` should remain pending or manual review depending on the current risk policy. `good` can complete the order. `invalid` should close the payment without marking it paid. Apply the same mapping to `payment_tier` and `txs[].payment_tier` when the code uses verbose payment details. Confirm amount and currency before fulfillment, because delayed callbacks or detail lookups must not regress a completed order.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing Triple-A payments can still receive webhooks and payment-detail polling until they are good, invalid, expired, 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 payment_reference, order_id, transaction ID, tx hash, payment_tier, and normalized status. Remove Triple-A OAuth credentials, merchant_key, hosted_url handling, widget code, notify_secret validation, and payment-detail polling only after there are no open legacy Triple-A payments.

## 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 Triple-A webhook routing during cutover, Triple-A notify_secret rejection, hosted_url replacement, widget-to-embedded checkout replacement, none/short/hold/good/invalid status mapping, amount/currency mismatch handling, payment-detail 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 Triple-A `hosted_url`.
- New-order code no longer fetches Triple-A bearer tokens or sends `merchant_key`.
- Embedded checkout uses MakePay embed/modal behavior instead of Triple-A `type: "widget"`.
- 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 Triple-A callbacks keep `notify_secret` or existing shared-secret validation until cutover is complete.
- Legacy none/short/hold/good/invalid paths are explicitly tested.
- Existing Triple-A payments remain reconcilable until the migration flag is fully removed.