Docs / Migration guide / CoinGate

This migration guide should help you replace CoinGate's exchange-routed order flow with a cleaner Payvra payment path.

Use this page to switch from CoinGate's order and callback model to Payvra's payment contract, while making the pricing, settlement, and webhook behavior explicit before any live traffic moves.

Create free sandbox Open API reference

Keep the migration narrow and reversible: map the order-create path to Payvra payments, replace the callback verifier, prove one sandbox run end to end, and only then shift production traffic.

What to prove before cutover

Pricing transparency

CoinGate's exchange-routed path obscures where spread and latency enter the flow. Payvra makes the payment and settlement path easier to inspect.

Webhook hardening

Move away from token-parameter callback checks and into signed webhook delivery with a clearer verification contract.

Operational continuity

You can keep existing CoinGate orders draining while routing only new traffic into the Payvra path.

Cutover facts

Primary naming change

CoinGate orders become Payvra payments.

Settlement target

Payvra settles into stablecoin balances rather than a CoinGate-managed exchange path.

Hosted checkout

Payvra payment links cover the hosted checkout path without reintroducing provider-specific order concepts.

Promotion rule

Use sandbox credentials until the callback replacement and final order updates are fully proven.

Overview

Treat this page as a migration brief for operators and developers. Confirm the commercial gap, map the API contract, prove the webhook path, and only then switch live volume.

CoinGate and Payvra both let you accept crypto payments, but the production contract differs. CoinGate wraps orders around its own exchange path, while Payvra keeps the payment surface cleaner and makes settlement behavior easier to reason about.

Run this migration as a replacement of assumptions as much as code. The team needs to know what happens to order creation, callback verification, and settlement visibility before moving live merchant traffic.

Why switch now

This should read like a production decision, not a feature wish list. Each row below explains the practical reason to move traffic away from the old provider.

Lower total cost

Removing hidden exchange spread changes the real economics of the checkout path, not just the headline fee number.

Clearer security model

Signed webhooks are easier to validate and audit than a callback token embedded in the payload.

Broader chain posture

Payvra keeps settlement closer to the underlying chains instead of abstracting everything through a provider exchange.

Faster sandbox loop

You can rehearse the full lifecycle immediately without a separate provider-specific test account flow.

API mapping

The main contract rewrite is around naming and settlement behavior. Map CoinGate orders to Payvra payments first, then move the hosted checkout and balance-management paths one step at a time.

CoinGate	Payvra	Notes
`POST` `/v2/orders`	`POST` `/v1/payments`	CoinGate orders become Payvra payments. Use `amount` + `currency` instead of `price_amount` + `price_currency`.
`GET` `/v2/orders/{id}`	`GET` `/v1/payments/{id}`	Direct equivalent with richer settlement detail.
`GET` `/v2/orders`	`GET` `/v1/payments`	Payvra uses cursor pagination instead of page-number traversal.
`POST` `/v2/orders/{id}/checkout`	`POST` `/v1/payment-links`	Use Payvra payment links for hosted checkout equivalents.
`GET` `/v2/ledger/account`	`GET` `/v1/ledger/balances`	Payvra exposes balance detail by settlement currency and chain.
`POST` `/v2/withdrawals`	`POST` `/v1/withdrawals`	Direct equivalent with on-chain execution detail.
`-` `-`	`POST` `/v1/refunds`	Refunds move from manual operations into a first-class API path.
`-` `-`	`POST` `/v1/batch-payouts`	Payvra adds multi-recipient payouts.

Code examples

Show the old and new contract side by side so the implementation team can replace the integration without hunting through multiple docs surfaces.

Create a payment

Replace the old order-creation call first. It proves auth, metadata mapping, hosted checkout handoff, and the first payment state transition without widening the migration scope.

CoinGate

1// CoinGate
2const response = await fetch("https://api.coingate.com/v2/orders", {
3  method: "POST",
4  headers: {
5    Authorization: "Token YOUR_COINGATE_TOKEN",
6    "Content-Type": "application/json",
7  },
8  body: JSON.stringify({
9    order_id: "order_123",
10    price_amount: 49.99,
11    price_currency: "USD",
12    receive_currency: "USDT",
13    callback_url: "https://yoursite.com/webhooks",
14    success_url: "https://yoursite.com/success",
15    cancel_url: "https://yoursite.com/cancel",
16  }),
17});
18
19const order = await response.json();
20// Redirect to: order.payment_url

Payvra

1// Payvra
2import Payvra from "payvra";
3
4const payvraSecretKey = process.env.PAYVRA_SECRET_KEY;
5if (!payvraSecretKey) {
6  throw new Error("Set PAYVRA_SECRET_KEY before running this example.");
7}
8
9const payvra = new Payvra(payvraSecretKey);
10
11const payment = await payvra.payments.create({
12  amount: "49.99",
13  currency: "USDC",
14  chain: "solana",
15  metadata: { orderId: "order_123" },
16});
17
18// Redirect to: payment.checkoutUrl

Handle webhooks

The callback rewrite is what turns this into a real provider migration. Replace token-parameter validation with explicit signature verification before you trust the paid-state update.

CoinGate callback

1// CoinGate callback handler
2app.post("/webhooks", (req, res) => {
3  const { status, order_id, token } = req.body;
4
5  if (token !== process.env.COINGATE_CALLBACK_TOKEN) {
6    return res.status(401).send("Invalid");
7  }
8
9  if (status === "paid") {
10    // Mark order paid
11  }
12
13  res.sendStatus(200);
14});

Payvra webhook

1// Payvra webhook handler
2app.post("/webhooks", (req, res) => {
3  const signature = req.headers["webhook-signature"];
4  const timestamp = req.headers["webhook-timestamp"];
5  const webhookId = req.headers["webhook-id"];
6
7  const signedContent = `${webhookId}.${timestamp}.${req.rawBody}`;
8  const expected = crypto
9    .createHmac("sha256", WEBHOOK_SECRET)
10    .update(signedContent)
11    .digest("base64");
12
13  if (signature !== `v1,${expected}`) {
14    return res.status(401).send("Invalid");
15  }
16
17  const { type, data } = req.body;
18  if (type === "payment.completed") {
19    // Mark order paid - data.metadata.orderId
20  }
21
22  res.sendStatus(200);
23});

Webhook mapping

CoinGate callback payloads report free-form status values. Payvra turns those transitions into typed webhook events so your handler can stay explicit about what each update means.

CoinGate status	Payvra	Notes
`Callback` `new`	`Webhook` `payment.created`	Payment created.
`Callback` `pending`	`Webhook` `payment.confirming`	Deposit detected.
`Callback` `confirming`	`Webhook` `payment.confirming`	Payment still waiting on chain confirmation.
`Callback` `paid`	`Webhook` `payment.confirmed`	Payment confirmed on-chain.
`Callback` `invalid`	`Webhook` `payment.failed`	Payment failed.
`Callback` `expired`	`Webhook` `payment.expired`	Payment expired.
`Callback` `canceled`	`Webhook` `payment.failed`	Canceled and invalid both collapse into failed-state handling.
`Callback` `refunded`	`Webhook` `refund.completed`	Refund completed.

Migration steps

Run this as a controlled cutover, not a blind rewrite. Keep the old provider draining existing payments while the new Payvra path proves itself in sandbox first.

Start with sandbox credentials and keep current orders draining

Generate sk_test_... credentials and leave open CoinGate orders untouched. The first objective is to prove the Payvra path, not to re-open already-issued orders.

Replace order creation with Payvra payment creation

Map price_amount and price_currency into the Payvra payment request, and move your existing order reference into metadata.orderId.

Terminal

1npm install payvra

Replace the callback verifier before trusting order completion

Your application should reject unsigned or stale Payvra webhook deliveries before it mutates any paid-state or settlement record.

Run one sandbox payment to the final completed state

Observe payment creation, hosted checkout, confirmation, webhook receipt, and order update as one end-to-end flow before moving to live.

Promote to live with the same route shape

Switch to live credentials and the live webhook secret once the sandbox path is predictable. The contract surface should stay the same when you go live.

Operator FAQ

Use these answers when the rollout owner wants to know what happens to existing traffic, settlement assumptions, and store-side behavior during the cutover.

What changes about hosted checkout?

CoinGate's order checkout step maps to a Payvra payment or payment-link path. The main difference is the cleaner payment naming and more explicit settlement posture.

What happens to CoinGate's fiat-conversion expectations?

Payvra settles into stablecoin balances rather than handling fiat off-ramp inside the same provider flow. That changes treasury handling, but it keeps settlement faster and more transparent.

Can I migrate in parallel?

Yes. Let existing CoinGate orders finish on CoinGate and send only new payment creation through Payvra until the replacement path is fully verified.

Ready to move off CoinGate?

Map the order flow to Payvra payments, prove the signed webhook path in sandbox, and promote to live only after the new settlement path is easy for operators to explain and reconcile.

Get sandbox keys Review webhook docs

This migration guide should help you replace CoinGate's exchange-routed order flow with a cleaner Payvra payment path.

Use this page to switch from CoinGate's order and callback model to Payvra's payment contract, while making the pricing, settlement, and webhook behavior explicit before any live traffic moves.

Keep the migration narrow and reversible: map the order-create path to Payvra payments, replace the callback verifier, prove one sandbox run end to end, and only then shift production traffic.

CoinGate

Payvra

Notes

POST /v2/orders

POST /v1/payments

CoinGate orders become Payvra payments. Use `amount` + `currency` instead of `price_amount` + `price_currency`.

GET /v2/orders/{id}

GET /v1/payments/{id}

Direct equivalent with richer settlement detail.

GET /v2/orders

GET /v1/payments

Payvra uses cursor pagination instead of page-number traversal.

POST /v2/orders/{id}/checkout

POST /v1/payment-links

Use Payvra payment links for hosted checkout equivalents.

GET /v2/ledger/account

GET /v1/ledger/balances

Payvra exposes balance detail by settlement currency and chain.

POST /v2/withdrawals

POST /v1/withdrawals

Direct equivalent with on-chain execution detail.

- -

POST /v1/refunds

Refunds move from manual operations into a first-class API path.

- -

POST /v1/batch-payouts

Payvra adds multi-recipient payouts.

1// CoinGate 2const response = await fetch("https://api.coingate.com/v2/orders", { 3 method: "POST", 4 headers: { 5 Authorization: "Token YOUR_COINGATE_TOKEN", 6 "Content-Type": "application/json", 7 }, 8 body: JSON.stringify({ 9 order_id: "order_123", 10 price_amount: 49.99, 11 price_currency: "USD", 12 receive_currency: "USDT", 13 callback_url: "https://yoursite.com/webhooks", 14 success_url: "https://yoursite.com/success", 15 cancel_url: "https://yoursite.com/cancel", 16 }), 17}); 18 19const order = await response.json(); 20// Redirect to: order.payment_url

1// Payvra 2import Payvra from "payvra"; 3 4const payvraSecretKey = process.env.PAYVRA_SECRET_KEY; 5if (!payvraSecretKey) { 6 throw new Error("Set PAYVRA_SECRET_KEY before running this example."); 7} 8 9const payvra = new Payvra(payvraSecretKey); 10 11const payment = await payvra.payments.create({ 12 amount: "49.99", 13 currency: "USDC", 14 chain: "solana", 15 metadata: { orderId: "order_123" }, 16}); 17 18// Redirect to: payment.checkoutUrl

1// CoinGate callback handler 2app.post("/webhooks", (req, res) => { 3 const { status, order_id, token } = req.body; 4 5 if (token !== process.env.COINGATE_CALLBACK_TOKEN) { 6 return res.status(401).send("Invalid"); 7 } 8 9 if (status === "paid") { 10 // Mark order paid 11 } 12 13 res.sendStatus(200); 14});

1// Payvra webhook handler 2app.post("/webhooks", (req, res) => { 3 const signature = req.headers["webhook-signature"]; 4 const timestamp = req.headers["webhook-timestamp"]; 5 const webhookId = req.headers["webhook-id"]; 6 7 const signedContent = `${webhookId}.${timestamp}.${req.rawBody}`; 8 const expected = crypto 9 .createHmac("sha256", WEBHOOK_SECRET) 10 .update(signedContent) 11 .digest("base64"); 12 13 if (signature !== `v1,${expected}`) { 14 return res.status(401).send("Invalid"); 15 } 16 17 const { type, data } = req.body; 18 if (type === "payment.completed") { 19 // Mark order paid - data.metadata.orderId 20 } 21 22 res.sendStatus(200); 23});

CoinGate status

Payvra

Notes

Callback new

Webhook payment.created

Payment created.

Callback pending

Webhook payment.confirming

Deposit detected.

Callback confirming

Webhook payment.confirming

Payment still waiting on chain confirmation.

Callback paid

Webhook payment.confirmed

Payment confirmed on-chain.

Callback invalid

Webhook payment.failed

Payment failed.

Callback expired

Webhook payment.expired

Payment expired.

Callback canceled

Webhook payment.failed

Canceled and invalid both collapse into failed-state handling.

Callback refunded

Webhook refund.completed

Refund completed.