AI migration

OxaPay migration

Use an AI agent to replace OxaPay invoices, payment URLs, white-label checkout, static addresses, callbacks, and status handling with MakePay APIs and SDKs.

Overview

This AI compatibility guide gives a senior developer or coding agent a direct path for replacing OxaPay invoice creation, hosted payment URLs, white-label payment details, static-address flows, callback HMAC verification, payment status polling, and status reconciliation with MakePay. It covers OxaPay v1 payment APIs, merchant_api_key, track_id, payment_url, callback_url, return_url, order_id, HMAC webhook signatures, invoice/white-label/static address payment types, payment history, and SDK installation.

Use it when the existing codebase calls OxaPay Merchant APIs, stores OxaPay track_id values on orders, redirects buyers to payment_url, renders OxaPay white-label addresses or QR codes, creates static addresses for customer top-ups, verifies the HMAC callback header, polls payment state, or still uses legacy /merchants/request invoice creation. OxaPay documents the current and legacy integration model in the Generate Invoice API, Generate White Label API, Generate Static Address API, Payment Information API, Payment History API, Payment Status Table, Webhook guide, and legacy Creating an Invoice API.

Payment links API

Webhook verification

SDK libraries

Migration map

OxaPay integrations usually create an invoice, store the returned track_id, redirect the buyer to payment_url, or render white-label/static-address checkout artifacts, then reconcile callbacks and payment-history polling. In MakePay, use payment links, signed webhooks, and SDK helpers for the same order flow.

OxaPay surface	MakePay replacement
`https://api.oxapay.com` base URL	MakeCrypto company/API credential configuration
`merchant_api_key` header or legacy `merchant` body field	`X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials
`POST /v1/payment/invoice`	`POST /api/partner/v1/makepay/payment-links` or SDK create-payment-link helper
Legacy `POST /merchants/request`	MakePay payment-link creation
Response `data.track_id` or legacy `trackId`	`paymentLink.uid`; keep a legacy alias during cutover
Response `data.payment_url` or legacy `payLink`	`paymentLink.publicUrl`
`amount` and `currency`	`payload.amount` and `payload.currency` or exact `payload.asset`
`to_currency`, `pay_currency`, `network`, and `mixed_payment`	MakePay exact `payload.asset` only when the business must force buyer assets
`callback_url`, legacy `callbackUrl`, `return_url`, and legacy `returnUrl`	MakePay webhook endpoint plus hosted-page redirect handling
`email`, `order_id`, legacy `orderId`, `description`, and `thanks_message`	`clientEmail`, `merchantOrderId`, `label`, `description`, and metadata
`lifetime`, legacy `lifeTime`, `expired_at`, and legacy `expiredAt`	MakePay payment-link expiry and late-payment business rules
`fee_paid_by_payer`, `under_paid_coverage`, `auto_withdrawal`, and `sandbox`	MakePay payment-link settings, environment flags, and internal metadata
`POST /v1/payment/white-label`	MakePay hosted checkout, embedded checkout route, or modal script
White-label response `pay_amount`, `pay_currency`, `network`, `address`, `qr_code`, and `rate`	Hosted MakePay checkout state; avoid storing provider artifacts as order URLs
`POST /v1/payment/static-address` and static-address callbacks	MakePay payment links for one-off checkout; keep legacy top-up addresses gated
`GET /v1/payment/{track_id}` payment information	MakePay payment-link lookup and webhook replay/reconciliation tooling
`GET /v1/payment` payment history filters by `track_id`, `type`, `status`, `pay_currency`, and address	MakePay reconciliation jobs and internal payment reporting
Callback `HMAC` header using HMAC-SHA512 over raw POST data with `MERCHANT_API_KEY`	MakePay `x-makepay-signature` HMAC verification over the raw request body
Callback response HTTP 200 with body `ok`	MakePay webhook response handling
Callback/payment types `invoice`, `white_label`, `static_address`, `payment_link`, and `donation`	MakePay payment-link events or legacy OxaPay handling during cutover
Statuses `new`, `waiting`, `paying`, `paid`, `manual_accept`, `underpaid`, `refunding`, `refunded`, `expired`	MakePay normalized paid, pending, failed, underpaid, refunded, and manual-review states
OxaPay payout callbacks and payout API key HMAC	Keep provider-specific payout/refund handling separate from MakePay checkout

For a clean migration, keep provider-specific IDs separate. Existing OxaPay invoices, white-label sessions, static addresses, and payout callbacks should continue to reconcile until they are paid, underpaid, expired, refunded, manually accepted, revoked, or manually closed by current business rules, while new order checkout uses 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 OxaPay usage

You are migrating this repository from OxaPay to MakePay. Search for OxaPay API
clients, api.oxapay.com, /v1/payment/invoice, /v1/payment/white-label,
/v1/payment/static-address, /v1/payment/{track_id}, /v1/payment,
/merchants/request, merchant_api_key, MERCHANT_API_KEY, merchant, track_id,
trackId, payment_url, payLink, pay_amount, pay_currency, network, address,
qr_code, callback_url, callbackUrl, return_url, returnUrl, order_id, orderId,
description, thanks_message, lifetime, lifeTime, expired_at, expiredAt,
fee_paid_by_payer, feePaidByPayer, under_paid_coverage, underPaidCover,
to_currency, auto_withdrawal, mixed_payment, sandbox, HMAC callback headers,
HMAC-SHA512 callback verification, invoice, white_label, static_address,
payment_link, donation, payout callbacks, and status handling for new, waiting,
paying, paid, manual_accept, underpaid, refunding, refunded, and expired.

Return a file-by-file migration plan with the exact functions that create
OxaPay invoices, white-label payments, or static addresses; store track IDs;
redirect buyers; render QR/address checkout data; verify callbacks; fetch
payment information/history; process payout callbacks; and reconcile order
status. Do not edit files yet.

Replace invoice creation

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

Remove OxaPay merchant_api_key and legacy merchant body authentication from the
new-order path. Map OxaPay amount to payload.amount, currency to
payload.currency or payload.asset, to_currency/pay_currency/network to an exact
asset only when the business must force buyer assets, order_id or orderId to
merchantOrderId, email to clientEmail, description or thanks_message to label
and description, callback_url or callbackUrl to the MakePay webhook endpoint,
return_url or returnUrl to MakePay redirect handling, and lifetime/lifeTime to
the equivalent payment-link expiry or business timeout setting.

Store paymentLink.uid and paymentLink.publicUrl, and keep nullable legacy OxaPay
track_id/trackId fields for historical records.

Replace hosted checkout and white-label artifacts

Replace OxaPay payment_url and legacy payLink redirects with MakePay
paymentLink.publicUrl. Do not carry forward OxaPay white-label pay_amount,
pay_currency, network, address, qr_code, rate, tx_hash, or direct deposit fields
as the primary order URL for new MakePay orders; those are provider-specific
checkout artifacts.

Find any frontend that renders OxaPay white-label QR codes, wallet addresses,
network selectors, or static-address top-up screens. For one-off order checkout,
replace it with MakePay hosted checkout, embedded checkout route, or modal
script depending on the existing UX. If the product still needs reusable top-up
addresses, keep the legacy OxaPay static-address flow behind a provider flag
until all old deposits and callbacks are reconciled, then design a MakePay-native
top-up flow separately.

Replace callback verification

Replace OxaPay callback handling with MakePay webhook verification. For legacy
OxaPay callbacks, preserve HMAC verification until open OxaPay payments are
closed: read the exact raw application/json request body, compute HMAC-SHA512
with MERCHANT_API_KEY for payment callbacks or PAYOUT_API_KEY for payout
callbacks, compare against the HMAC header with a timing-safe compare, and only
then parse/process the JSON. Keep the required OxaPay success response only for
legacy OxaPay endpoints: HTTP 200 with body ok.

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
OxaPay callbacks, use track_id/trackId plus type, status, tx_hash, and order_id
for idempotency.

Normalize statuses

Map legacy OxaPay statuses explicitly during cutover and normalize case because
some callbacks/examples may use capitalized values. new and waiting should not
grant goods. paying means a payment attempt is in progress and must remain
pending until paid or manual_accept. paid can complete the order only after
amount, currency, order_id, track_id, and provider checks pass. manual_accept
should complete only if the existing business treats manual acceptance as paid.
underpaid should route to underpayment/manual review unless under_paid_coverage
rules explicitly accept it. expired should close the payment without marking the
order paid. refunding should keep the order in a refund-pending state. refunded
should update refund state without double-crediting or regressing fulfillment.

Dual-run cutover

Add a migration flag so newly created orders use MakePay while existing OxaPay
invoices, white-label payments, static addresses, payment links, donation
payments, and payout callbacks can still receive callbacks and payment-history
polling until they are paid, underpaid, expired, refunding, refunded, manually
accepted, revoked, 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 OxaPay track_id,
order_id, type, status, tx_hash, address, amount, currency, pay_currency,
network, and normalized status.

Remove OxaPay merchant API keys, payout API keys, HMAC callback verification,
payment_url/payLink redirects, white-label QR/address rendering, static-address
creation, payment information/history polling, and payout callback code only
after there are no open legacy OxaPay payments, static addresses, or payouts.

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 OxaPay callback routing during
cutover, OxaPay HMAC rejection, payment_url/payLink replacement, white-label
QR/address artifact removal, static-address legacy routing, new/waiting/paying
not granting goods, paid completion, manual_accept policy, underpaid manual
review, expired closure, refunding pending refund state, refunded state, legacy
payment-information polling fallback, legacy payment-history reconciliation, 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.

Agent-ready OxaPay migration Markdown

# Migrate OxaPay to MakePay

Use this as the working brief for an AI coding agent. Replace OxaPay invoice creation, hosted payment URLs, white-label payment details, static-address flows, callback HMAC verification, payment status 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

- OxaPay `https://api.oxapay.com` base URL -> MakeCrypto company/API credential configuration.
- OxaPay `merchant_api_key` header or legacy `merchant` body field -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials.
- OxaPay `POST /v1/payment/invoice` -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- Legacy OxaPay `POST /merchants/request` -> MakePay payment-link creation.
- OxaPay response `data.track_id` or legacy `trackId` -> MakePay `paymentLink.uid`; keep the old track ID in a migration alias table while orders are in flight.
- OxaPay response `data.payment_url` or legacy `payLink` -> MakePay `paymentLink.publicUrl`.
- OxaPay `amount` and `currency` -> MakePay `payload.amount` and `payload.currency` or exact `payload.asset`.
- OxaPay `to_currency`, `pay_currency`, `network`, and `mixed_payment` -> MakePay exact `payload.asset` only when the business must force buyer assets.
- OxaPay `callback_url`, legacy `callbackUrl`, `return_url`, and legacy `returnUrl` -> MakePay webhook endpoint plus hosted-page redirect handling.
- OxaPay `email`, `order_id`, legacy `orderId`, `description`, and `thanks_message` -> MakePay `clientEmail`, `merchantOrderId`, `label`, `description`, and metadata.
- OxaPay `lifetime`, legacy `lifeTime`, `expired_at`, and legacy `expiredAt` -> MakePay payment-link expiry and late-payment business rules.
- OxaPay `fee_paid_by_payer`, `under_paid_coverage`, `auto_withdrawal`, and `sandbox` -> MakePay payment-link settings, environment flags, and internal metadata.
- OxaPay `POST /v1/payment/white-label` -> MakePay hosted checkout, embedded checkout route, or modal script.
- OxaPay white-label `pay_amount`, `pay_currency`, `network`, `address`, `qr_code`, and `rate` -> hosted MakePay checkout state; avoid storing provider artifacts as order URLs.
- OxaPay `POST /v1/payment/static-address` and static-address callbacks -> MakePay payment links for one-off checkout; keep legacy top-up addresses gated.
- OxaPay `GET /v1/payment/{track_id}` payment information -> MakePay payment-link lookup and webhook replay/reconciliation tooling.
- OxaPay `GET /v1/payment` payment history filters -> MakePay reconciliation jobs and internal payment reporting.
- OxaPay callback `HMAC` header using HMAC-SHA512 over raw POST data with `MERCHANT_API_KEY` -> MakePay `x-makepay-signature` HMAC verification over the raw request body.
- OxaPay callback response HTTP 200 with body `ok` -> MakePay webhook response handling.
- OxaPay callback/payment types `invoice`, `white_label`, `static_address`, `payment_link`, and `donation` -> MakePay payment-link events or legacy OxaPay handling during cutover.
- OxaPay statuses `new`, `waiting`, `paying`, `paid`, `manual_accept`, `underpaid`, `refunding`, `refunded`, and `expired` -> MakePay normalized paid, pending, failed, underpaid, refunded, and manual-review states.
- OxaPay payout callbacks and payout API key HMAC -> keep provider-specific payout/refund handling separate from MakePay checkout.

## Agent prompt: inventory

You are migrating this repository from OxaPay to MakePay. Search for OxaPay API clients, `api.oxapay.com`, `/v1/payment/invoice`, `/v1/payment/white-label`, `/v1/payment/static-address`, `/v1/payment/{track_id}`, `/v1/payment`, `/merchants/request`, `merchant_api_key`, `MERCHANT_API_KEY`, `merchant`, `track_id`, `trackId`, `payment_url`, `payLink`, `pay_amount`, `pay_currency`, `network`, `address`, `qr_code`, `callback_url`, `callbackUrl`, `return_url`, `returnUrl`, `order_id`, `orderId`, `description`, `thanks_message`, `lifetime`, `lifeTime`, `expired_at`, `expiredAt`, `fee_paid_by_payer`, `feePaidByPayer`, `under_paid_coverage`, `underPaidCover`, `to_currency`, `auto_withdrawal`, `mixed_payment`, `sandbox`, `HMAC` callback headers, HMAC-SHA512 callback verification, `invoice`, `white_label`, `static_address`, `payment_link`, `donation`, payout callbacks, and status handling for `new`, `waiting`, `paying`, `paid`, `manual_accept`, `underpaid`, `refunding`, `refunded`, and `expired`. Return a file-by-file migration plan with the exact functions that create OxaPay invoices, white-label payments, or static addresses; store track IDs; redirect buyers; render QR/address checkout data; verify callbacks; fetch payment information/history; process payout callbacks; and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice creation

Implement MakePay payment-link creation in the existing OxaPay invoice creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Remove OxaPay `merchant_api_key` and legacy `merchant` body authentication from the new-order path. Map OxaPay `amount` to `payload.amount`, `currency` to `payload.currency` or `payload.asset`, `to_currency`/`pay_currency`/`network` to an exact asset only when the business must force buyer assets, `order_id` or `orderId` to `merchantOrderId`, `email` to `clientEmail`, `description` or `thanks_message` to `label` and `description`, `callback_url` or `callbackUrl` to the MakePay webhook endpoint, `return_url` or `returnUrl` to MakePay redirect handling, and `lifetime`/`lifeTime` to the equivalent payment-link expiry or business timeout setting. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy OxaPay `track_id`/`trackId` fields for historical records.

## Agent prompt: replace hosted checkout and white-label artifacts

Replace OxaPay `payment_url` and legacy `payLink` redirects with MakePay `paymentLink.publicUrl`. Do not carry forward OxaPay white-label `pay_amount`, `pay_currency`, `network`, `address`, `qr_code`, `rate`, `tx_hash`, or direct deposit fields as the primary order URL for new MakePay orders; those are provider-specific checkout artifacts. Find any frontend that renders OxaPay white-label QR codes, wallet addresses, network selectors, or static-address top-up screens. For one-off order checkout, replace it with MakePay hosted checkout, embedded checkout route, or modal script depending on the existing UX. If the product still needs reusable top-up addresses, keep the legacy OxaPay static-address flow behind a provider flag until all old deposits and callbacks are reconciled, then design a MakePay-native top-up flow separately.

## Agent prompt: replace callback verification

Replace OxaPay callback handling with MakePay webhook verification. For legacy OxaPay callbacks, preserve HMAC verification until open OxaPay payments are closed: read the exact raw `application/json` request body, compute HMAC-SHA512 with `MERCHANT_API_KEY` for payment callbacks or `PAYOUT_API_KEY` for payout callbacks, compare against the `HMAC` header with a timing-safe compare, and only then parse/process the JSON. Keep the required OxaPay success response only for legacy OxaPay endpoints: HTTP 200 with body `ok`. 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 OxaPay callbacks, use `track_id`/`trackId` plus type, status, `tx_hash`, and `order_id` for idempotency.

## Agent prompt: normalize statuses

Map legacy OxaPay statuses explicitly during cutover and normalize case because some callbacks/examples may use capitalized values. `new` and `waiting` should not grant goods. `paying` means a payment attempt is in progress and must remain pending until `paid` or `manual_accept`. `paid` can complete the order only after amount, currency, `order_id`, `track_id`, and provider checks pass. `manual_accept` should complete only if the existing business treats manual acceptance as paid. `underpaid` should route to underpayment/manual review unless `under_paid_coverage` rules explicitly accept it. `expired` should close the payment without marking the order paid. `refunding` should keep the order in a refund-pending state. `refunded` should update refund state without double-crediting or regressing fulfillment.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing OxaPay invoices, white-label payments, static addresses, payment links, donation payments, and payout callbacks can still receive callbacks and payment-history polling until they are paid, underpaid, expired, refunding, refunded, manually accepted, revoked, 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 OxaPay `track_id`, `order_id`, type, status, `tx_hash`, address, amount, currency, `pay_currency`, network, and normalized status. Remove OxaPay merchant API keys, payout API keys, HMAC callback verification, `payment_url`/`payLink` redirects, white-label QR/address rendering, static-address creation, payment information/history polling, and payout callback code only after there are no open legacy OxaPay payments, static addresses, or payouts.

## 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 OxaPay callback routing during cutover, OxaPay HMAC rejection, `payment_url`/`payLink` replacement, white-label QR/address artifact removal, static-address legacy routing, new/waiting/paying not granting goods, paid completion, `manual_accept` policy, underpaid manual review, expired closure, refunding pending refund state, refunded state, legacy payment-information polling fallback, legacy payment-history reconciliation, 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 OxaPay `payment_url` or legacy `payLink`.
- New-order code no longer sends OxaPay `merchant_api_key` or legacy `merchant` invoice requests.
- New MakePay orders do not store OxaPay QR codes, wallet addresses, network fields, or transaction hashes as order URLs.
- 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.
- Legacy OxaPay callbacks keep `HMAC` verification until cutover is complete.
- Legacy new, waiting, paying, paid, manual_accept, underpaid, refunding, refunded, and expired paths are explicitly tested.
- Existing OxaPay invoices, white-label payments, static addresses, and payouts still reconcile until the migration flag is removed.

Verification checklist

A new order creates exactly one MakePay payment link and stores paymentLink.uid.
The buyer redirect uses paymentLink.publicUrl instead of OxaPay payment_url or legacy payLink.
New-order code no longer sends OxaPay merchant_api_key or legacy merchant invoice requests.
New MakePay orders do not store OxaPay QR codes, wallet addresses, network fields, or transaction hashes as order URLs.
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.
Legacy OxaPay callbacks keep HMAC verification until cutover is complete.
Legacy new, waiting, paying, paid, manual_accept, underpaid, refunding, refunded, and expired paths are explicitly tested.
Existing OxaPay invoices, white-label payments, static addresses, and payouts still reconcile until the migration flag is removed.
Production logs include provider, order ID, payment UID, delivery ID, legacy track ID, order ID, type, status, transaction hash, address, amount, currency, network, and normalized status.