Changelly Pay migration

Overview

This AI compatibility guide gives a senior developer or coding agent a direct path for replacing Changelly Pay with MakePay. It focuses on the integration surfaces that usually matter in production: invoice creation, buyer redirect URLs, provider IDs, webhook verification, status reconciliation, and SDK installation.

Use it when the existing codebase calls the Changelly Pay Merchant API directly or wraps it behind a payment provider abstraction. The official Changelly Pay API documentation is available at api.pay.changelly.com, with the OpenAPI spec at api.pay.changelly.com/spec.yaml.

Migration map

Changelly Pay invoices and deposits are modeled around POST /payments, payment_id, payment_url, merchant RSA request signing, and payment callbacks with provider statuses such as CREATED, WAITING, COMPLETED, FAILED, and CANCELED. In MakePay, use payment links, HMAC-signed webhooks, and SDK helpers for the same business flow.

For a clean migration, keep provider-specific IDs separate. Existing Changelly Pay orders should continue to reconcile until they settle 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 Changelly Pay usage

You are migrating this repository from Changelly Pay to MakePay. Search for
Changelly Pay API clients, /payments calls, payment_url, payment_id,
X-Api-Key, X-Signature, RSA signing helpers, callback handlers, and enum
handling for CREATED, WAITING, COMPLETED, FAILED, and CANCELED.

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

Replace invoice creation

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

Map order amount to payload.amount, display or settlement currency to
payload.currency or payload.asset, customer email to clientEmail, order
reference to merchantOrderId, and description or label to order-facing text.
Store paymentLink.uid and paymentLink.publicUrl, and keep a nullable legacy
Changelly Pay payment ID field for historical records.

Replace callback verification

Replace the Changelly Pay callback verifier with MakePay webhook verification.
Read the exact raw request body before JSON parsing, parse x-makepay-signature,
verify the 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.

Dual-run cutover

Add a migration flag so newly created orders use MakePay while existing
Changelly Pay orders can still receive callbacks until they settle or expire.
Route callbacks by provider, keep provider-specific IDs separate, and add logs
that include provider, order ID, payment UID, delivery ID, and normalized
status.

Remove Changelly Pay 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 Changelly Pay callback routing
during cutover, 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 Changelly Pay to MakePay

Use this as the working brief for an AI coding agent. Replace Changelly Pay invoice creation, callbacks, status reconciliation, and SDK 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

- Changelly Pay `POST /payments` invoice creation -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- Changelly Pay `payment_url` -> MakePay `paymentLink.publicUrl`.
- Changelly Pay `payment_id` -> MakePay `paymentLink.uid`; keep the old ID in a migration alias table while orders are in flight.
- Changelly Pay `order_id` or merchant metadata -> MakePay `merchantOrderId`, `label`, and `description`.
- Changelly Pay `nominal_amount` and invoice asset -> MakePay `payload.amount` plus `payload.currency` or exact `payload.asset`.
- Changelly Pay `X-Api-Key` and RSA `X-Signature` signing -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers.
- Changelly Pay callbacks with `CREATED`, `WAITING`, `COMPLETED`, `FAILED`, `CANCELED` -> MakePay `makepay.payment.status_changed` webhooks and session/link status handling.
- Changelly Pay callback signature verification -> MakePay HMAC verification from `x-makepay-signature` over the raw request body.

## Agent prompt: inventory

You are migrating this repository from Changelly Pay to MakePay. Search for Changelly Pay API clients, `/payments` calls, `payment_url`, `payment_id`, `X-Api-Key`, `X-Signature`, RSA signing helpers, callback handlers, and enum handling for `CREATED`, `WAITING`, `COMPLETED`, `FAILED`, and `CANCELED`. Return a file-by-file migration plan with the exact functions that create invoices, store payment IDs, redirect buyers, verify callbacks, and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice creation

Implement MakePay payment-link creation in the existing invoice creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Map order amount to `payload.amount`, display or settlement currency to `payload.currency` or `payload.asset`, customer email to `clientEmail`, order reference to `merchantOrderId`, and description/label to order-facing text. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep a nullable legacy Changelly Pay payment ID field for historical records.

## Agent prompt: replace callback verification

Replace the Changelly Pay callback verifier with MakePay webhook verification. Read the exact raw request body before JSON parsing, parse `x-makepay-signature`, verify the 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.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing Changelly Pay orders can still receive callbacks until they settle or expire. Route callbacks by provider, keep provider-specific IDs separate, and add logs that include provider, order ID, payment UID, delivery ID, and normalized status. Remove Changelly Pay 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 Changelly Pay callback routing during cutover, 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`.
- 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 Changelly Pay 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.
• 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.
• Existing Changelly Pay orders still reconcile until the migration flag is removed.
• Production logs include provider, order ID, payment UID, delivery ID, and normalized status.