AI 迁移

Confirmo migration

Use an AI agent to replace Confirmo invoices, hosted invoice URLs, overlay checkout, webhooks, exceptions, refunds, 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 Confirmo invoice creation, hosted invoice URLs, invoice overlay events, webhook notification verification, invoice detail polling, exception handling, take-request/manual acceptance flows, refund links, and status reconciliation with MakePay. It covers Confirmo API v3 invoices, Authorization: Bearer, invoice.amount, invoice.currencyFrom, invoice.currencyTo, settlement.currency, invoice id, invoice url, notifyUrl, returnUrl, bp-signature, @confirmo/overlay, invoice statuses, exceptions, and SDK installation.

Use it when the existing codebase calls Confirmo API v3, stores Confirmo invoice IDs on orders, redirects buyers to Confirmo invoice url, embeds @confirmo/overlay or custom iframes, listens for CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE, verifies bp-signature notifications, or calls invoice detail/list/take-request endpoints before fulfillment. Confirmo documents the current integration model in the Accepting Your First Payment guide, Create new Invoice API, Get merchant invoices API, Notifications guide, Processing Webhooks guide, Invoice Lifecycle guide, Invoice creation reference, Invoice overlay guide, and Create Take Request API.

Payment links API

Webhook verification

SDK libraries

Migration map

Confirmo integrations usually create a v3 invoice, store the returned invoice id, redirect buyers to invoice url or open the Confirmo overlay, then reconcile webhooks and direct invoice-detail lookups. In MakePay, use payment links, signed webhooks, and SDK helpers for the same order flow.

Confirmo surface	MakePay replacement
`https://confirmo.net/api/v3` base URL	MakeCrypto company/API credential configuration
`Authorization: Bearer {CONFIRMO_API_KEY}`	`X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials
`POST /api/v3/invoices`	`POST /api/partner/v1/makepay/payment-links` or SDK create-payment-link helper
Invoice `id`	`paymentLink.uid`; keep a legacy alias during cutover
Invoice `url`	`paymentLink.publicUrl`
`invoice.amount` and `invoice.currencyFrom`	`payload.amount` and `payload.currency`
`invoice.currencyTo` and `invoice.layer2ProtocolName`	MakePay exact `payload.asset` only when the business must force buyer assets
`settlement.currency`	Settlement/business configuration or internal metadata
`product.name` and `product.description`	`label` and `description`
`reference`, customer email/name/order JSON, and order numbers	`merchantOrderId`, `clientEmail`, and internal metadata
`returnUrl`, `notifyUrl`, and `notifyEmail`	MakePay hosted-page redirect handling plus MakePay webhook endpoint
Confirmo checkout QR code, `address`, `cryptoUri`, `crypto.currency`, `crypto.amount`, and txids	Hosted MakePay checkout state; avoid storing provider artifacts as order URLs
`@confirmo/overlay`, custom iframe, `CLOSE_CONFIRMO_OVERLAY`, and `CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE`	MakePay hosted checkout, embedded checkout route, or modal script
`bp-signature` SHA256(payload + callback password) webhook header	MakePay `x-makepay-signature` HMAC verification over the raw request body
Webhook body containing the full invoice model	MakePay payment events or legacy Confirmo handling during cutover
Direct `GET /api/v3/invoices/{id}` verification after final webhooks	MakePay payment-link lookup and webhook replay/reconciliation tooling
`GET /api/v3/invoices` list/filter reconciliation	MakePay reconciliation jobs and internal payment reporting
Statuses `prepared`, `pending_verification`, `active`, `confirming`, `paid`, `expired`, `error`, `blocked`	MakePay normalized pending, paid, expired, failed, blocked, and manual-review states
`unhandledExceptions`, overpayment, underpayment, delayed payment, `overUnderPaidAmount`, and `exception`	MakePay manual-review, underpayment, overpayment, and late-payment handling
`POST /api/v3/invoices/{id}/take` and confirm take request	MakePay manual acceptance or support workflow
`refundLink`, invoice refunds, and payout/refund state	MakePay refund or manual support workflow

For a clean migration, keep provider-specific IDs separate. Existing Confirmo invoices should continue to reconcile until they are paid, expired, errored, blocked, refunded, manually accepted, exception-resolved, 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 Confirmo usage

You are migrating this repository from Confirmo to MakePay. Search for Confirmo
API clients, confirmo.net/api/v3, /api/v3/invoices,
/api/v3/invoices/{id}, /api/v3/invoices/{id}/take, Authorization: Bearer,
CONFIRMO_API_KEY, callback password, bp-signature, notifyUrl, notifyurl,
notifyEmail, returnUrl, reference, product.name, product.description,
invoice.amount, invoice.currencyFrom, invoice.currencyTo,
invoice.layer2ProtocolName, settlement.currency, id, url, address, cryptoUri,
customerAmount, merchantAmount, settlementAmount, rate, paid, paidSince,
paidAtTime, completedAtTime, cryptoTransactions, txids, confirmations,
requiredConfirmations, refundLink, refunds, unhandledExceptions,
overUnderPaidAmount, exception, @confirmo/overlay, CLOSE_CONFIRMO_OVERLAY,
CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE, prepared, pending_verification, active,
confirming, paid, expired, error, blocked, and invoice detail polling.

Return a file-by-file migration plan with the exact functions that create
Confirmo invoices, store invoice IDs, redirect or open overlay checkout, render
QR/address checkout data, verify bp-signature notifications, fetch invoice
details, list invoices for reconciliation, process take requests or manual
acceptance, process refund links, and reconcile order status. Do not edit files
yet.

Replace invoice creation

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

Remove Confirmo Authorization: Bearer usage from the new-order path. Map
invoice.amount to payload.amount, invoice.currencyFrom to payload.currency,
invoice.currencyTo and invoice.layer2ProtocolName to payload.asset only when the
business must force a buyer asset or Lightning/native-chain method,
settlement.currency to settlement/business metadata, product.name to label,
product.description to description, reference/order JSON to merchantOrderId and
internal metadata, customer email to clientEmail, notifyUrl to the MakePay
webhook endpoint, and returnUrl to MakePay redirect handling.

Store paymentLink.uid and paymentLink.publicUrl, and keep nullable legacy
Confirmo invoice ID fields for historical records.

Replace hosted checkout and overlay artifacts

Replace Confirmo invoice url redirects with MakePay paymentLink.publicUrl. For
Confirmo embedded checkout, remove @confirmo/overlay, Confirmo custom iframe
code, CLOSE_CONFIRMO_OVERLAY handlers, and
CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE handlers for new MakePay orders. Use
MakePay hosted checkout, embedded checkout route, or modal script depending on
the existing UX.

Do not carry forward Confirmo QR codes, address, cryptoUri, crypto.amount,
crypto.currency, customerAmount, payment asset, txids, or cryptoTransactions as
the primary order URL for new MakePay orders; those are provider-specific
checkout artifacts.

Replace webhook verification

Replace Confirmo notification handling with MakePay webhook verification. For
legacy Confirmo notifications, preserve bp-signature verification until open
Confirmo invoices are closed: read the exact raw application/json request body,
append the Confirmo callback password as a suffix, compute SHA256, compare the
hex digest against the bp-signature header with a timing-safe compare, and only
then parse/process the JSON. After any final or fulfillment-relevant legacy
notification such as paid, call the Confirmo GET invoice detail endpoint before
granting goods because Confirmo recommends direct verification after final
webhooks.

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
Confirmo notifications, use invoice id plus status, paidSince/paidAtTime,
txids/cryptoTransactions, and completedAtTime for idempotency.

Normalize statuses

Map legacy Confirmo statuses explicitly during cutover. prepared,
pending_verification, and active should not grant goods. confirming means a
payment has been detected and should remain pending until paid. paid can
complete the order only after amount, currency, invoice ID, reference/order, and
provider checks pass, preferably after direct invoice-detail verification.
expired should close the payment unless unhandledExceptions or delayed/partial
payment business rules require manual review. error and blocked should close the
payment or route to manual review without marking it paid. Overpayment,
underpayment, delayed payment, unhandledExceptions, overUnderPaidAmount, and
exception entries should route to explicit manual-review, overpaid, underpaid,
late-payment, refund, or take-request handling.

Dual-run cutover

Add a migration flag so newly created orders use MakePay while existing Confirmo
invoices can still receive notifications and invoice-detail/list polling until
they are paid, expired, errored, blocked, refunded, manually accepted,
exception-resolved, 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 Confirmo invoice
ID, status, reference, merchantAmount, customerAmount, settlementAmount,
cryptoTransactions/txids, confirmations, requiredConfirmations,
unhandledExceptions, overUnderPaidAmount, refundLink, and normalized status.

Remove Confirmo API keys, callback passwords, bp-signature verification,
@confirmo/overlay code, custom iframe handlers, invoice url redirects,
QR/address/cryptoUri rendering, invoice detail/list polling, take-request code,
and refund-link code only after there are no open legacy Confirmo invoices.

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 Confirmo notification routing
during cutover, bp-signature rejection, required GET invoice-detail verification
before fulfillment, invoice url replacement, @confirmo/overlay removal,
QR/address/cryptoUri artifact removal, prepared/pending_verification/active not
granting goods, confirming pending behavior, paid completion, expired closure,
error/blocked closure, unhandledExceptions manual review, overpayment,
underpayment, delayed payment, take-request/manual acceptance policy, refund
link handling, legacy invoice list 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 Confirmo migration Markdown

# Migrate Confirmo to MakePay

Use this as the working brief for an AI coding agent. Replace Confirmo invoice creation, hosted invoice URLs, invoice overlay events, webhook notification verification, invoice detail polling, exception handling, take-request/manual acceptance flows, refund links, 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

- Confirmo `https://confirmo.net/api/v3` base URL -> MakeCrypto company/API credential configuration.
- Confirmo `Authorization: Bearer {CONFIRMO_API_KEY}` -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials.
- Confirmo `POST /api/v3/invoices` -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- Confirmo invoice `id` -> MakePay `paymentLink.uid`; keep the old invoice ID in a migration alias table while orders are in flight.
- Confirmo invoice `url` -> MakePay `paymentLink.publicUrl`.
- Confirmo `invoice.amount` and `invoice.currencyFrom` -> MakePay `payload.amount` and `payload.currency`.
- Confirmo `invoice.currencyTo` and `invoice.layer2ProtocolName` -> MakePay exact `payload.asset` only when the business must force buyer assets.
- Confirmo `settlement.currency` -> settlement/business configuration or internal metadata.
- Confirmo `product.name` and `product.description` -> MakePay `label` and `description`.
- Confirmo `reference`, customer email/name/order JSON, and order numbers -> MakePay `merchantOrderId`, `clientEmail`, and internal metadata.
- Confirmo `returnUrl`, `notifyUrl`, and `notifyEmail` -> MakePay hosted-page redirect handling plus MakePay webhook endpoint.
- Confirmo checkout QR code, `address`, `cryptoUri`, `crypto.currency`, `crypto.amount`, and txids -> hosted MakePay checkout state; avoid storing provider artifacts as order URLs.
- Confirmo `@confirmo/overlay`, custom iframe, `CLOSE_CONFIRMO_OVERLAY`, and `CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE` -> MakePay hosted checkout, embedded checkout route, or modal script.
- Confirmo `bp-signature` SHA256(payload + callback password) webhook header -> MakePay `x-makepay-signature` HMAC verification over the raw request body.
- Confirmo webhook body containing the full invoice model -> MakePay payment events or legacy Confirmo handling during cutover.
- Confirmo direct `GET /api/v3/invoices/{id}` verification after final webhooks -> MakePay payment-link lookup and webhook replay/reconciliation tooling.
- Confirmo `GET /api/v3/invoices` list/filter reconciliation -> MakePay reconciliation jobs and internal payment reporting.
- Confirmo statuses `prepared`, `pending_verification`, `active`, `confirming`, `paid`, `expired`, `error`, and `blocked` -> MakePay normalized pending, paid, expired, failed, blocked, and manual-review states.
- Confirmo `unhandledExceptions`, overpayment, underpayment, delayed payment, `overUnderPaidAmount`, and `exception` -> MakePay manual-review, underpayment, overpayment, and late-payment handling.
- Confirmo `POST /api/v3/invoices/{id}/take` and confirm take request -> MakePay manual acceptance or support workflow.
- Confirmo `refundLink`, invoice refunds, and payout/refund state -> MakePay refund or manual support workflow.

## Agent prompt: inventory

You are migrating this repository from Confirmo to MakePay. Search for Confirmo API clients, `confirmo.net/api/v3`, `/api/v3/invoices`, `/api/v3/invoices/{id}`, `/api/v3/invoices/{id}/take`, `Authorization: Bearer`, `CONFIRMO_API_KEY`, callback password, `bp-signature`, `notifyUrl`, `notifyurl`, `notifyEmail`, `returnUrl`, `reference`, `product.name`, `product.description`, `invoice.amount`, `invoice.currencyFrom`, `invoice.currencyTo`, `invoice.layer2ProtocolName`, `settlement.currency`, `id`, `url`, `address`, `cryptoUri`, `customerAmount`, `merchantAmount`, `settlementAmount`, `rate`, `paid`, `paidSince`, `paidAtTime`, `completedAtTime`, `cryptoTransactions`, `txids`, `confirmations`, `requiredConfirmations`, `refundLink`, `refunds`, `unhandledExceptions`, `overUnderPaidAmount`, `exception`, `@confirmo/overlay`, `CLOSE_CONFIRMO_OVERLAY`, `CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE`, `prepared`, `pending_verification`, `active`, `confirming`, `paid`, `expired`, `error`, `blocked`, and invoice detail polling. Return a file-by-file migration plan with the exact functions that create Confirmo invoices, store invoice IDs, redirect or open overlay checkout, render QR/address checkout data, verify bp-signature notifications, fetch invoice details, list invoices for reconciliation, process take requests or manual acceptance, process refund links, and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice creation

Implement MakePay payment-link creation in the existing Confirmo invoice creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Remove Confirmo `Authorization: Bearer` usage from the new-order path. Map `invoice.amount` to `payload.amount`, `invoice.currencyFrom` to `payload.currency`, `invoice.currencyTo` and `invoice.layer2ProtocolName` to `payload.asset` only when the business must force a buyer asset or Lightning/native-chain method, `settlement.currency` to settlement/business metadata, `product.name` to `label`, `product.description` to `description`, `reference`/order JSON to `merchantOrderId` and internal metadata, customer email to `clientEmail`, `notifyUrl` to the MakePay webhook endpoint, and `returnUrl` to MakePay redirect handling. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy Confirmo invoice ID fields for historical records.

## Agent prompt: replace hosted checkout and overlay artifacts

Replace Confirmo invoice `url` redirects with MakePay `paymentLink.publicUrl`. For Confirmo embedded checkout, remove `@confirmo/overlay`, Confirmo custom iframe code, `CLOSE_CONFIRMO_OVERLAY` handlers, and `CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE` handlers for new MakePay orders. Use MakePay hosted checkout, embedded checkout route, or modal script depending on the existing UX. Do not carry forward Confirmo QR codes, `address`, `cryptoUri`, `crypto.amount`, `crypto.currency`, `customerAmount`, payment asset, `txids`, or `cryptoTransactions` as the primary order URL for new MakePay orders; those are provider-specific checkout artifacts.

## Agent prompt: replace webhook verification

Replace Confirmo notification handling with MakePay webhook verification. For legacy Confirmo notifications, preserve `bp-signature` verification until open Confirmo invoices are closed: read the exact raw `application/json` request body, append the Confirmo callback password as a suffix, compute SHA256, compare the hex digest against the `bp-signature` header with a timing-safe compare, and only then parse/process the JSON. After any final or fulfillment-relevant legacy notification such as `paid`, call the Confirmo GET invoice detail endpoint before granting goods because Confirmo recommends direct verification after final webhooks. 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 Confirmo notifications, use invoice `id` plus status, `paidSince`/`paidAtTime`, `txids`/`cryptoTransactions`, and `completedAtTime` for idempotency.

## Agent prompt: normalize statuses

Map legacy Confirmo statuses explicitly during cutover. `prepared`, `pending_verification`, and `active` should not grant goods. `confirming` means a payment has been detected and should remain pending until `paid`. `paid` can complete the order only after amount, currency, invoice ID, reference/order, and provider checks pass, preferably after direct invoice-detail verification. `expired` should close the payment unless `unhandledExceptions` or delayed/partial payment business rules require manual review. `error` and `blocked` should close the payment or route to manual review without marking it paid. Overpayment, underpayment, delayed payment, `unhandledExceptions`, `overUnderPaidAmount`, and `exception` entries should route to explicit manual-review, overpaid, underpaid, late-payment, refund, or take-request handling.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing Confirmo invoices can still receive notifications and invoice-detail/list polling until they are paid, expired, errored, blocked, refunded, manually accepted, exception-resolved, 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 Confirmo invoice ID, status, reference, `merchantAmount`, `customerAmount`, `settlementAmount`, `cryptoTransactions`/`txids`, confirmations, `requiredConfirmations`, `unhandledExceptions`, `overUnderPaidAmount`, `refundLink`, and normalized status. Remove Confirmo API keys, callback passwords, `bp-signature` verification, `@confirmo/overlay` code, custom iframe handlers, invoice `url` redirects, QR/address/`cryptoUri` rendering, invoice detail/list polling, take-request code, and refund-link code only after there are no open legacy Confirmo invoices.

## 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 Confirmo notification routing during cutover, `bp-signature` rejection, required GET invoice-detail verification before fulfillment, invoice `url` replacement, `@confirmo/overlay` removal, QR/address/`cryptoUri` artifact removal, prepared/pending_verification/active not granting goods, confirming pending behavior, paid completion, expired closure, error/blocked closure, `unhandledExceptions` manual review, overpayment, underpayment, delayed payment, take-request/manual acceptance policy, refund link handling, legacy invoice list 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 Confirmo invoice `url`.
- New-order code no longer sends Confirmo `Authorization: Bearer` invoice requests.
- New MakePay orders do not store Confirmo QR codes, addresses, crypto URIs, or transaction IDs as order URLs.
- New MakePay orders no longer load `@confirmo/overlay` or depend on Confirmo overlay postMessage events.
- 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 Confirmo notifications keep `bp-signature` verification until cutover is complete.
- Legacy final-status webhooks verify the invoice through Confirmo GET invoice detail before fulfillment.
- Legacy prepared, pending_verification, active, confirming, paid, expired, error, blocked, exception, refund, and take-request paths are explicitly tested.
- Existing Confirmo invoices 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 Confirmo invoice url.
New-order code no longer sends Confirmo Authorization: Bearer invoice requests.
New MakePay orders do not store Confirmo QR codes, addresses, crypto URIs, or transaction IDs as order URLs.
New MakePay orders no longer load @confirmo/overlay or depend on Confirmo overlay postMessage events.
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 Confirmo notifications keep bp-signature verification until cutover is complete.
Legacy final-status webhooks verify the invoice through Confirmo GET invoice detail before fulfillment.
Legacy prepared, pending_verification, active, confirming, paid, expired, error, blocked, exception, refund, and take-request paths are explicitly tested.
Existing Confirmo invoices still reconcile until the migration flag is removed.
Production logs include provider, order ID, payment UID, delivery ID, legacy invoice ID, status, reference, amount, currency, crypto transaction IDs, confirmations, exception flags, refund link, and normalized status.