NOWPayments migration

Overview

This AI compatibility guide gives a senior developer or coding agent a direct path for replacing NOWPayments with MakePay. It covers hosted invoices, direct payments, buyer redirect URLs, provider IDs, IPN verification, status reconciliation, and SDK installation.

Use it when the existing codebase calls the NOWPayments API directly or wraps it behind a payment provider abstraction. The official NOWPayments API and endpoint guide is available in the NOWPayments HelpCenter, with IPN setup documented at IPN and how to setup.

Migration map

NOWPayments integrations usually use either POST /invoice for a hosted invoice or POST /payment for a direct crypto payment. Both flows authenticate with x-api-key, accept ipn_callback_url, and send IPN callbacks signed with x-nowpayments-sig. In MakePay, use payment links, HMAC-signed webhooks, and SDK helpers for the same order flow.

For a clean migration, keep provider-specific IDs separate. Existing NOWPayments invoices and payments should continue to reconcile until they finish, fail, or expire, while new orders use MakePay.

SDK install commands

Pick the SDK that matches the service being migrated. These are the same quick commands shown on the MakePay SDK cards.

npm install @makecrypto/makepay
composer require makepay/makepay-php
go get github.com/makecryptoio/makepay-go
pip install makepay
cargo add makepay

implementation("io.makecrypto:makepay:0.3.0")

.package(url: "https://github.com/makecryptoio/makepay-swift-sdk.git", from: "0.3.0")

Use the SDK for payment-link creation and webhook verification whenever the language supports it. If a service has a custom HTTP client layer, call the payment-links API directly and keep the provider adapter small.

Agent prompts

Inventory NOWPayments usage

You are migrating this repository from NOWPayments to MakePay. Search for
NOWPayments API clients, api.nowpayments.io, /invoice, /payment, invoice_url,
payment_id, x-api-key, x-nowpayments-sig, ipn_callback_url, IPN handlers, and
enum handling for waiting, confirming, confirmed, sending, finished,
partially_paid, failed, expired, and cancelled.

Return a file-by-file migration plan with the exact functions that create
invoices or direct payments, store provider IDs, redirect buyers, verify IPNs,
and reconcile order status. Do not edit files yet.

Replace invoice or payment creation

Implement MakePay payment-link creation in the existing NOWPayments invoice or
direct-payment creation path. Use the official MakePay SDK for this stack when
available; otherwise call POST /api/partner/v1/makepay/payment-links.

Map price_amount to payload.amount, price_currency or settlement requirements
to payload.currency or payload.asset, order_id to merchantOrderId, and
order_description to label or description. Store paymentLink.uid and
paymentLink.publicUrl, and keep nullable legacy NOWPayments invoice/payment ID
fields for historical records.

Replace IPN verification

Replace NOWPayments IPN verification with MakePay webhook verification. Remove
sorted-JSON HMAC-SHA512 verification 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 status updates idempotent by delivery ID and payment-link UID.

Normalize statuses

Map legacy NOWPayments statuses explicitly during cutover. waiting, confirming,
confirmed, and sending should not grant goods by default. finished can complete
the order. partially_paid and wrong-asset states should go to manual review or
the existing underpayment path. failed, expired, and cancelled should close the
legacy payment without marking the order paid.

Dual-run cutover

Add a migration flag so newly created orders use MakePay while existing
NOWPayments invoices or direct payments can still receive IPNs until they
settle, fail, or expire. Route callbacks by provider, keep provider-specific
IDs separate, and add logs that include provider, order ID, payment UID,
delivery ID, legacy invoice/payment ID, and normalized status.

Remove NOWPayments credentials only after there are no open legacy orders.

Write 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 NOWPayments IPN routing during
cutover, partially paid/manual-review handling, expired payment handling, and
buyer redirect URL generation.

Use mocked MakePay SDK/API responses. Do not hit production APIs in tests.

Copy migration Markdown

The block below is a compact agent-ready brief for repository migrations. Copy it into Codex, Claude Code, Cursor, or another codebase-aware assistant when you want the model to perform the migration against a real project.

# Migrate NOWPayments to MakePay

Use this as the working brief for an AI coding agent. Replace NOWPayments invoice or direct-payment creation, IPN verification, status reconciliation, and provider SDK/API usage with MakePay payment links, 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

- NOWPayments `POST /invoice` -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- NOWPayments `POST /payment` direct payment -> MakePay payment link creation plus hosted checkout URL; avoid storing deposit addresses as the primary order URL.
- NOWPayments `invoice_url` -> MakePay `paymentLink.publicUrl`.
- NOWPayments `id` or `payment_id` -> MakePay `paymentLink.uid`; keep the old provider ID in a migration alias table while orders are in flight.
- NOWPayments `price_amount` and `price_currency` -> MakePay `payload.amount` and `payload.currency` or exact `payload.asset`.
- NOWPayments `pay_currency` -> MakePay destination asset selection when the merchant must force a settlement asset or chain.
- NOWPayments `order_id` and `order_description` -> MakePay `merchantOrderId`, `label`, and `description`.
- NOWPayments `success_url` and `cancel_url` -> MakePay success/failure redirect settings or hosted-page return handling.
- NOWPayments `x-api-key` -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers.
- NOWPayments IPN `x-nowpayments-sig` HMAC-SHA512 over sorted JSON -> MakePay `x-makepay-signature` HMAC verification over the raw request body.
- NOWPayments statuses `waiting`, `confirming`, `confirmed`, `sending`, `finished`, `partially_paid`, `failed`, `expired`, and `cancelled` -> MakePay `makepay.payment.status_changed` events and normalized order states.

## Agent prompt: inventory

You are migrating this repository from NOWPayments to MakePay. Search for NOWPayments API clients, `api.nowpayments.io`, `/invoice`, `/payment`, `invoice_url`, `payment_id`, `x-api-key`, `x-nowpayments-sig`, `ipn_callback_url`, IPN handlers, and enum handling for `waiting`, `confirming`, `confirmed`, `sending`, `finished`, `partially_paid`, `failed`, `expired`, and `cancelled`. Return a file-by-file migration plan with the exact functions that create invoices or direct payments, store provider IDs, redirect buyers, verify IPNs, and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice/payment creation

Implement MakePay payment-link creation in the existing NOWPayments invoice or direct-payment creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Map `price_amount` to `payload.amount`, `price_currency` or settlement requirements to `payload.currency` or `payload.asset`, `order_id` to `merchantOrderId`, and `order_description` to `label` or `description`. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy NOWPayments invoice/payment ID fields for historical records.

## Agent prompt: replace IPN verification

Replace NOWPayments IPN verification with MakePay webhook verification. Remove sorted-JSON HMAC-SHA512 verification 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: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing NOWPayments invoices or direct payments can still receive IPNs until they settle, fail, or expire. Route callbacks by provider, keep provider-specific IDs separate, and add logs that include provider, order ID, payment UID, delivery ID, legacy invoice/payment ID, and normalized status. Remove NOWPayments credentials 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 NOWPayments IPN routing during cutover, partially paid/manual-review handling, expired payment 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 `invoice_url` or provider deposit-address UI.
- 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.
- `partially_paid`, wrong-asset, failed, and expired legacy NOWPayments states are mapped to explicit business states during cutover.
- Legacy NOWPayments orders remain reconcilable until the migration flag is fully removed.

Verification checklist

• A new order creates exactly one MakePay payment link and stores paymentLink.uid.
• The buyer redirect uses paymentLink.publicUrl instead of invoice_url or provider deposit-address UI.
• Webhook verification fails closed when x-makepay-signature is missing, stale, or invalid.
• makepay.payment.status_changed handling is idempotent by delivery ID.
• Completed orders cannot be regressed by delayed provider events.
• partially_paid, wrong-asset, failed, expired, and cancelled legacy states are mapped to explicit business states during cutover.
• Existing NOWPayments orders still reconcile until the migration flag is removed.
• Production logs include provider, order ID, payment UID, delivery ID, legacy invoice/payment ID, and normalized status.