Migração com IA

Plisio migration

Use an AI agent to replace Plisio invoice creation, invoice URLs, verify_hash callbacks, deposits, 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 Plisio invoice checkout, callback verification, status polling, white-label invoice fields, and deposit-address flows with MakePay. It covers Plisio api_key authentication, GET /api/v1/invoices/new, hosted invoice_url checkout, txn_id IDs, verify_hash callback signatures, transaction status reconciliation, pay-in deposit callbacks, and SDK installation.

Use it when the existing codebase calls Plisio directly, depends on a Plisio plugin, stores Plisio transaction IDs on orders, renders Plisio invoice or QR data, or verifies Plisio callbacks before fulfilling orders. Plisio documents the API in Introduction, Create an invoice, Manage invoice updates and cash-in, Transactions, Transaction details, and Create a deposit.

Payment links API

Webhook verification

SDK libraries

Migration map

Plisio integrations usually create an invoice with GET /api/v1/invoices/new, pass a secret api_key as a query parameter, send the buyer to data.invoice_url, and reconcile with callbacks containing verify_hash plus optional GET /api/v1/operations/<id> lookups. In MakePay, use payment links, signed webhooks, and SDK helpers for the same order flow.

Plisio surface	MakePay replacement
`https://api.plisio.net/api/v1` base URL	MakeCrypto company/API credential configuration
`api_key=SECRET_KEY` query authentication	`X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials
`GET /api/v1/invoices/new`	`POST /api/partner/v1/makepay/payment-links` or SDK create-payment-link helper
`source_currency` and `source_amount`	`payload.currency` and `payload.amount`
`amount` with `currency` or `allowed_psys_cids`	Exact `payload.asset` only when buyer asset must be forced
`order_number`	`merchantOrderId`; keep unique per order
`order_name` and `description`	`label` and `description`
`email`	`clientEmail`
`callback_url`, `success_callback_url`, and `fail_callback_url`	MakePay webhook endpoint plus success/failure redirect handling
`success_invoice_url` and `fail_invoice_url`	MakePay hosted-page return URLs or host-page redirect settings
`expire_min`	Payment-link expiry and late-payment business rules
Response `data.txn_id`	`paymentLink.uid`; keep a legacy alias during cutover
Response `data.invoice_url`	`paymentLink.publicUrl`
White-label `wallet_hash`, `psys_cid`, `qr_code`, and `pending_amount`	Hosted MakePay checkout state; avoid storing deposit artifacts as order URLs
Callback `verify_hash` HMAC-SHA1 over sorted form data or JSON callback body	`x-makepay-signature` HMAC verification over the raw request body
Callback `txn_id`, `switch_id`, `tx_urls`, and `ipn_type`	Webhook delivery ID plus `paymentLink.uid` idempotency
`GET /api/v1/operations` and `GET /api/v1/operations/<id>` reconciliation	MakePay payment-link lookup and webhook replay/reconciliation tooling
Deposit `GET /api/v1/shops/deposit/new` with `uid`, `psys_cid`, and `hash`	MakePay payment links for per-order checkout; keep deposits only for legacy top-ups
Invoice statuses `new`, `pending`, `pending internal`, `completed`, `expired`	MakePay normalized paid, pending, failed, underpaid, and manual-review states
Extra statuses `mismatch`, `error`, `cancelled`, and `cancelled duplicate`	Explicit failed, overpaid, duplicate, and manual-review handling

For a clean migration, keep provider-specific IDs separate. Existing Plisio invoices and pay-in deposits should continue to reconcile until they are completed, expired, cancelled, duplicated, mismatched, errored, refunded, or manually closed by current business rules, 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 Plisio usage

You are migrating this repository from Plisio to MakePay. Search for Plisio API
clients, plisio.net, api.plisio.net, /api/v1/invoices/new,
/api/v1/operations, /api/v1/operations/<id>, /api/v1/shops/deposit/new,
api_key, SECRET_KEY, source_currency, source_amount, amount, currency,
allowed_psys_cids, order_number, order_name, description, callback_url,
success_callback_url, fail_callback_url, success_invoice_url, fail_invoice_url,
redirect_to_invoice, expire_min, return_existing, txn_id, invoice_url,
invoice_total_sum, wallet_hash, psys_cid, pending_amount, qr_code, tx_urls,
switch_id, verify_hash, HMAC-SHA1 verification, callback handlers, Status URL,
Request IP allowlisting, pay_in callbacks, deposit_uid, and status handling for
new, pending, pending internal, expired, completed, mismatch, error, cancelled,
and cancelled duplicate.

Return a file-by-file migration plan with the exact functions that create
Plisio invoices, store provider transaction IDs, redirect buyers, render QR or
deposit data, verify callbacks, fetch operation status, process deposit
callbacks, and reconcile order status. Do not edit files yet.

Replace invoice creation

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

Remove Plisio api_key query usage from the new-order path. Map source_amount to
payload.amount, source_currency to payload.currency, amount/currency or
allowed_psys_cids to payload.asset only when the business must force a buyer
asset, order_number to merchantOrderId, order_name to label, description to
description, email to clientEmail, and expire_min to the equivalent payment-link
expiry or business timeout setting.

Store paymentLink.uid and paymentLink.publicUrl, and keep nullable legacy Plisio
txn_id fields for historical records.

Replace hosted checkout and white-label artifacts

Replace Plisio invoice_url redirects with MakePay paymentLink.publicUrl. Do not
carry forward Plisio wallet_hash, psys_cid, qr_code, pending_amount,
invoice_total_sum, tx_urls, or crypto deposit fields as the primary order URL
for new MakePay orders; those are provider-specific checkout artifacts.

Find any Plisio white-label or deposit flow that displays direct wallet hashes,
QR codes, or permanent pay-in addresses. For one-off order checkout, replace it
with MakePay payment links so each order has a paymentLink.uid and
paymentLink.publicUrl. If the product still needs reusable top-up addresses,
keep the legacy Plisio deposit flow behind a provider flag until all old pay-ins
and callbacks are reconciled, then design a MakePay-native top-up flow
separately.

Replace callback verification

Replace Plisio callback handling with MakePay webhook verification. For legacy
Plisio callbacks, preserve verify_hash validation until open Plisio invoices are
closed. For PHP/form callbacks, remove verify_hash from the payload, sort fields
the same way as the current implementation, preserve Plisio-specific conversions
such as expire_utc string conversion and tx_urls entity decoding when present,
serialize the payload, compute HMAC-SHA1 with the Plisio SECRET_KEY, and compare
with verify_hash using a timing-safe compare. For non-PHP JSON callbacks, keep
the json=true callback behavior and verify the exact JSON signing behavior used
by the current integration.

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
Plisio callbacks, use txn_id plus switch_id or tx_urls for idempotency.

Normalize statuses

Map legacy Plisio statuses explicitly during cutover. new should not grant
goods. pending and pending internal should remain pending until a final status
arrives. completed can complete the order only after amount, currency,
merchant/shop, and provider ID checks pass. expired should inspect the amount
received and route partial payment to underpayment/manual review. mismatch
should route to overpayment/manual review. error and cancelled should close the
payment without marking it paid. cancelled duplicate should not double-credit;
link it to the winning switched invoice when switch_id or related transaction
metadata is available.

Dual-run cutover

Add a migration flag so newly created orders use MakePay while existing Plisio
invoices and pay-in deposits can still receive callbacks and operation polling
until they are completed, expired, cancelled, duplicated, mismatched, errored,
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 Plisio txn_id, switch_id,
ipn_type, merchant_id, order_number, status, confirmations, tx_urls, and
normalized status.

Remove Plisio SECRET_KEY usage, api_key query construction, invoice_url
handling, verify_hash validation, operation polling, QR rendering, wallet_hash
storage, and deposit-address creation only after there are no open legacy Plisio
invoices or pay-ins.

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 Plisio callback routing during
cutover, verify_hash rejection, invoice_url replacement, white-label QR and
wallet artifact removal, new/pending/pending-internal not granting goods,
completed fulfillment, expired underpayment handling, mismatch overpayment
handling, cancelled/error closure, cancelled duplicate de-duplication, legacy
operation polling fallback, Plisio deposit callback routing, 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 Plisio migration Markdown

# Migrate Plisio to MakePay

Use this as the working brief for an AI coding agent. Replace Plisio API-key invoice creation, hosted invoice URLs, callback verify_hash validation, operation polling, white-label invoice artifacts, deposit-address flows, status reconciliation, and provider SDK/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

- Plisio `https://api.plisio.net/api/v1` base URL -> MakeCrypto company/API credential configuration.
- Plisio `api_key=SECRET_KEY` query authentication -> MakePay `X-MakeCrypto-Key-Id` and `X-MakeCrypto-Key-Secret` headers or SDK credentials.
- Plisio `GET /api/v1/invoices/new` -> MakePay `POST /api/partner/v1/makepay/payment-links` or the SDK create-payment-link helper.
- Plisio `source_currency` and `source_amount` -> MakePay `payload.currency` and `payload.amount`.
- Plisio `amount` with `currency` or `allowed_psys_cids` -> MakePay exact `payload.asset` only when the business must force a buyer asset.
- Plisio `order_number` -> MakePay `merchantOrderId`; keep it unique per order.
- Plisio `order_name` and `description` -> MakePay `label` and `description`.
- Plisio `email` -> MakePay `clientEmail`.
- Plisio `callback_url`, `success_callback_url`, and `fail_callback_url` -> MakePay webhook endpoint plus success/failure redirect handling.
- Plisio `success_invoice_url` and `fail_invoice_url` -> MakePay hosted-page return URLs or host-page redirect settings.
- Plisio `expire_min` -> MakePay payment-link expiry and late-payment business rules.
- Plisio response `data.txn_id` -> MakePay `paymentLink.uid`; keep the old transaction ID in a migration alias table while orders are in flight.
- Plisio response `data.invoice_url` -> MakePay `paymentLink.publicUrl`.
- Plisio white-label `wallet_hash`, `psys_cid`, `qr_code`, `pending_amount`, and `tx_urls` -> hosted MakePay checkout state; avoid storing deposit artifacts as order URLs.
- Plisio callback `verify_hash` HMAC-SHA1 over sorted form data or JSON callback body -> MakePay `x-makepay-signature` HMAC verification over the raw request body.
- Plisio callback `txn_id`, `switch_id`, `tx_urls`, and `ipn_type` -> MakePay delivery ID plus `paymentLink.uid` idempotency.
- Plisio `GET /api/v1/operations` and `GET /api/v1/operations/<id>` reconciliation -> MakePay payment-link lookup and webhook replay/reconciliation tooling.
- Plisio deposit `GET /api/v1/shops/deposit/new` with `uid`, `psys_cid`, and `hash` -> MakePay payment links for per-order checkout; keep deposits only for legacy top-ups.
- Plisio statuses `new`, `pending`, `pending internal`, `completed`, `expired`, `mismatch`, `error`, `cancelled`, and `cancelled duplicate` -> MakePay normalized paid, pending, failed, underpaid, overpaid, duplicate, and manual-review states.

## Agent prompt: inventory

You are migrating this repository from Plisio to MakePay. Search for Plisio API clients, `plisio.net`, `api.plisio.net`, `/api/v1/invoices/new`, `/api/v1/operations`, `/api/v1/operations/<id>`, `/api/v1/shops/deposit/new`, `api_key`, `SECRET_KEY`, `source_currency`, `source_amount`, `amount`, `currency`, `allowed_psys_cids`, `order_number`, `order_name`, `description`, `callback_url`, `success_callback_url`, `fail_callback_url`, `success_invoice_url`, `fail_invoice_url`, `redirect_to_invoice`, `expire_min`, `return_existing`, `txn_id`, `invoice_url`, `invoice_total_sum`, `wallet_hash`, `psys_cid`, `pending_amount`, `qr_code`, `tx_urls`, `switch_id`, `verify_hash`, HMAC-SHA1 verification, callback handlers, Status URL, Request IP allowlisting, `pay_in` callbacks, `deposit_uid`, and status handling for `new`, `pending`, `pending internal`, `expired`, `completed`, `mismatch`, `error`, `cancelled`, and `cancelled duplicate`. Return a file-by-file migration plan with the exact functions that create Plisio invoices, store provider transaction IDs, redirect buyers, render QR or deposit data, verify callbacks, fetch operation status, process deposit callbacks, and reconcile order status. Do not edit files yet.

## Agent prompt: replace invoice creation

Implement MakePay payment-link creation in the existing Plisio invoice creation path. Use the official MakePay SDK for this stack when available; otherwise call `POST /api/partner/v1/makepay/payment-links`. Remove Plisio `api_key` query usage from the new-order path. Map `source_amount` to `payload.amount`, `source_currency` to `payload.currency`, `amount`/`currency` or `allowed_psys_cids` to `payload.asset` only when the business must force a buyer asset, `order_number` to `merchantOrderId`, `order_name` to `label`, `description` to `description`, `email` to `clientEmail`, and `expire_min` to the equivalent payment-link expiry or business timeout setting. Store `paymentLink.uid` and `paymentLink.publicUrl`, and keep nullable legacy Plisio `txn_id` fields for historical records.

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

Replace Plisio `invoice_url` redirects with MakePay `paymentLink.publicUrl`. Do not carry forward Plisio `wallet_hash`, `psys_cid`, `qr_code`, `pending_amount`, `invoice_total_sum`, `tx_urls`, or crypto deposit fields as the primary order URL for new MakePay orders; those are provider-specific checkout artifacts. Find any Plisio white-label or deposit flow that displays direct wallet hashes, QR codes, or permanent pay-in addresses. For one-off order checkout, replace it with MakePay payment links so each order has a `paymentLink.uid` and `paymentLink.publicUrl`. If the product still needs reusable top-up addresses, keep the legacy Plisio deposit flow behind a provider flag until all old pay-ins and callbacks are reconciled, then design a MakePay-native top-up flow separately.

## Agent prompt: replace callback verification

Replace Plisio callback handling with MakePay webhook verification. For legacy Plisio callbacks, preserve `verify_hash` validation until open Plisio invoices are closed. For PHP/form callbacks, remove `verify_hash` from the payload, sort fields the same way as the current implementation, preserve Plisio-specific conversions such as `expire_utc` string conversion and `tx_urls` entity decoding when present, serialize the payload, compute HMAC-SHA1 with the Plisio SECRET_KEY, and compare with `verify_hash` using a timing-safe compare. For non-PHP JSON callbacks, keep the `json=true` callback behavior and verify the exact JSON signing behavior used by the current integration. 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 Plisio callbacks, use `txn_id` plus `switch_id` or `tx_urls` for idempotency.

## Agent prompt: normalize statuses

Map legacy Plisio statuses explicitly during cutover. `new` should not grant goods. `pending` and `pending internal` should remain pending until a final status arrives. `completed` can complete the order only after amount, currency, merchant/shop, and provider ID checks pass. `expired` should inspect the amount received and route partial payment to underpayment/manual review. `mismatch` should route to overpayment/manual review. `error` and `cancelled` should close the payment without marking it paid. `cancelled duplicate` should not double-credit; link it to the winning switched invoice when `switch_id` or related transaction metadata is available.

## Agent prompt: dual-run cutover

Add a migration flag so newly created orders use MakePay while existing Plisio invoices and pay-in deposits can still receive callbacks and operation polling until they are completed, expired, cancelled, duplicated, mismatched, errored, 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 Plisio txn_id, switch_id, ipn_type, merchant_id, order_number, status, confirmations, tx_urls, and normalized status. Remove Plisio SECRET_KEY usage, api_key query construction, invoice_url handling, verify_hash validation, operation polling, QR rendering, wallet_hash storage, and deposit-address creation only after there are no open legacy Plisio invoices or pay-ins.

## 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 Plisio callback routing during cutover, `verify_hash` rejection, invoice_url replacement, white-label QR and wallet artifact removal, new/pending/pending-internal not granting goods, completed fulfillment, expired underpayment handling, mismatch overpayment handling, cancelled/error closure, cancelled duplicate de-duplication, legacy operation polling fallback, Plisio deposit callback routing, 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 Plisio `invoice_url`.
- New-order code no longer passes Plisio `api_key` or `SECRET_KEY` in invoice-creation requests.
- New MakePay orders do not store Plisio wallet hashes, QR codes, transaction URLs, or deposit addresses as order URLs.
- 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 Plisio callbacks keep `verify_hash` validation until cutover is complete.
- Legacy new/pending/pending-internal/completed/expired/mismatch/error/cancelled/cancelled-duplicate paths are explicitly tested.
- Existing Plisio invoices and pay-ins 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 Plisio invoice_url.
New-order code no longer passes Plisio api_key or SECRET_KEY in invoice-creation requests.
New MakePay orders do not store Plisio wallet hashes, QR codes, transaction URLs, or deposit addresses 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 Plisio callbacks keep verify_hash validation until cutover is complete.
New, pending, pending internal, completed, expired, mismatch, error, cancelled, and cancelled duplicate paths are explicitly tested.
Existing Plisio invoices and pay-ins still reconcile until the migration flag is removed.
Production logs include provider, order ID, payment UID, delivery ID, legacy Plisio transaction ID, switch ID, IPN type, merchant ID, order number, status, confirmations, transaction URLs, and normalized status.