Documentation

Everything, in one place.

Take card and crypto payments on your own site. Create a free account, add your payout wallet and an API key — then cards and crypto each take one call, every payment shows in your dashboard, and the money settles straight to your own wallet.

For AI assistantsIntegrating with Claude, ChatGPT or Cursor? Give it this file.norpo-for-ai.md · the whole API, rules and copy-paste code in one page.Download file

Getting started

Base URL https://api.norpo.io. JSON over HTTPS, no SDK, no sandbox: the requests on this page are the live ones. Money settles straight to your own wallet — Norpo does not hold it, except for the options you ask for: Telegram and crypto to balance, which credit your Norpo balance.

Pick one route. Each group below is complete on its own.

No code at all? Use a plugin, or send a payment link from your dashboard.

Cards

Card payments

The key says who you are, so every payment lands in your dashboard — orders, volume, reports — and your server can get signed webhooks with retries. Money still settles straight to your own wallet.

  1. Sign up at the sign-up form. The account is live at once.
  2. Add your payout wallet in Settings: an EVM address (0x…) from a wallet you control. Payouts may be sent in ETH, USDC or USDT (Polygon or BEP-20), or POL, Polygon’s native token.
  3. Create a key in Settings → API keys. The secret is shown once; copy it to your server.
  4. Optional: add a webhook endpoint in Webhooks to be told when payments settle.

Authenticate

One header on every request. Keys start with nrp_live_sk_, never expire and stop working the moment you revoke them. Keep the key on your server — never in browser, app or plugin code.

Authorization header
Authorization: Bearer nrp_live_sk_…

Test mode

Build and test the whole integration without money. Create a test key in Settings → API keys → New test key; it starts with nrp_test_sk_. Payments made with it never reach a provider: order.url opens a Norpo test page (api.norpo.io/test-checkout/…) with two buttons, every answer carries"test": true, and so does the data of your webhooks. Test and live payments never mix — each key sees only its own.

Resolve a test payment from code
curl -X POST https://api.norpo.io/v1/payments/cmud5…/simulate \
  -H "Authorization: Bearer nrp_test_sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "paid" }'

# outcome: "paid" → payment.settled, "failed" → payment.failed
# switch to a live key when you go live — nothing else changes

Create a payment

Send the amount; the wallet comes from your account. Send the customer to order.url, then read the status back or wait for the webhook. There is no minimum amount of our own.

One call for card and crypto. The payout wallet comes from your account, so it is never in the request; the key in the header is what identifies you.

POST /v1/payments
curl -X POST https://api.norpo.io/v1/payments \
  -H "Authorization: Bearer nrp_live_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
      "amount":      49.00,
      "currency":    "USD",
      "reference":   "order-1042",
      "callbackUrl": "https://shop.tld/hook",
      "callbackFormat": "json",
      "redirectUrl": "https://shop.tld/thanks"
     }'

# → 201
{
  "paymentId": "cmud5…",
  "reference": "order-1042",
  "status":    "pending",
  "order": {
    "kind":        "onramp",
    "url":         "https://api.norpo.io/return/p/cmud5…",
    "checkoutUrl": "https://pay.norpo.io/c/7PtToMTHohgeZH43skGLwk",
    "settleAsset": "USDC"
  },
  "callbackFormat": "json",
  "callbackSecret": "cbsec_8Kq2…"
}

# Send the customer to order.url — a Norpo waiting page that
# opens the checkout, confirms the payment and, with
# redirectUrl, returns the customer to your site.

# Every payment made this way appears in your
# dashboard: orders, volume, reports and webhooks.
FieldWhat it does
amountRequired. The price, e.g. 49.00 — not cents.
currencyThree-letter code, default USD. Bill in the customer’s own currency: local methods only appear for local money.
referenceYour order id. Echoed in responses, the callback and webhooks — match payments by it.
redirectUrlWhere the customer goes after paying. The waiting page sends them there once the payment is confirmed; without it the page just says the payment arrived.
callbackUrlOptional. Norpo tells this URL when the payment settles — see Confirm it.
callbackFormatSend "json": the callback becomes a signed JSON POST, and the response carries a callbackSecret for this payment. Store it with the order to verify Norpo-Signature.
customerEmailOptional. Pre-fills the checkout and goes into your records.

The waiting page. order.url is always a Norpo page, not the checkout itself. It opens the checkout in a new tab, keeps the customer’s place, shows the payment once it lands and, when you set a redirectUrl, sends the customer back to you. Card checkouts never return anyone on their own, so this is what brings them back. The raw checkout link is in order.checkoutUrl if you need it.

Confirm it

Two ways to hear about a payment: webhooks for the whole account (below), or a callbackUrl on the payment itself — handy for plugins and bots. Create the payment with "callbackFormat": "json" and Norpo POSTs a signed JSON event to that URL. Check Norpo-Signature with the callbackSecret from the create response: an HMAC-SHA256 of {t}.{body}, the same scheme as webhooks. Make the handler idempotent — the same event can arrive twice.

POST your callbackUrl
Norpo-Event:     payment.paid
Norpo-Signature: t=1790497260000,v1=5f2c…

{
  "id":      "evt_1ae3…",
  "event":   "payment.paid",
  "created": 1790497260,
  "data": {
    "id":        "cmud5…",
    "status":    "paid",
    "reference": "order-1042",
    "amount":    49,
    "currency":  "USD"
  }
}

# verify the signature, match by id or reference, then fulfil

Responses

Every answer POST /v1/payments can give, and what to do about it.

WhenWhat to do
201Payment createdSend the customer to order.url. Keep paymentId; poll it or wait for the webhook.
400The body is malformed — no amount, not a number, broken JSONRead issues: each entry names the field and what is wrong with it.
401Missing API key — no Authorization headerSend Authorization: Bearer nrp_live_sk_… on every request.
401Invalid API key — wrong or revoked keyCreate a new key in Settings → API keys. A revoked key never comes back.
403account_not_active — the account is suspendedContact support.
422No payout wallet on the accountAdd an EVM payout wallet (0x…) in Settings, then retry the same request.
422The payment network rejected your payout walletUse an EVM address (0x…) from a wallet you control — not an exchange deposit address, a contract or a burn address.
422Amount is below the minimum for the method you forced with kind or methodRaise the amount, or leave kind and method out and let Norpo pick.
429Too many requestsBack off and retry.
502The payment network did not answerNot your request. Retry in a minute; if it keeps failing, contact support.
503No payment method available for this requestUsually a kind or method that is not on for your account. Leave them out, or ask support.

Webhooks

Add an endpoint in the dashboard under Webhooks. Norpo POSTs JSON to it when a payment settles and retries for about ten hours until you answer 2xx. Check the Norpo-Signature header before trusting the body: it is an HMAC-SHA256 of {t}.{body} with your endpoint secret.

POST your webhook endpoint
Norpo-Event:     payment.settled
Norpo-Signature: t=1790497260000,v1=5f2c…

{
  "id":      "evt_9a41…",
  "event":   "payment.settled",
  "created": 1790497260,
  "data": {
    "paymentId": "cmud5…",
    "reference": "order-1042",
    "amount":    49,
    "currency":  "USD"
  }
}

# match by paymentId or reference; answer 2xx fast;
# the same event can arrive more than once — use "id"

Refunds

Card and crypto payments settle to your own wallet, which Norpo cannot spend from, so a refund is paid from your Norpo balance in USDT (TRC-20): minimum $5, network fee $1. Name the payment and refunds against it can never exceed what was paid. Your webhooks receive refund.created; the status turns paid with a TRON transaction hash once it is sent.

POST /v1/payouts/refunds
curl -X POST https://api.norpo.io/v1/payouts/refunds \
  -H "Authorization: Bearer nrp_live_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
      "paymentId": "cmud5…",
      "address":   "T…customer",
      "amount":    15,
      "reason":    "Damaged item"
     }'
Cards

AI agents (MCP)

Let an AI agent bill your customers. Norpo runs a Model Context Protocol server: point any MCP client at it with your API key and the agent can create payments, check their status and read your balance. It cannot withdraw or send money.

MCP server
URL:     https://api.norpo.io/mcp
Header:  Authorization: Bearer nrp_live_sk_…

# tools
  create_payment   amount, currency, reference → paymentId, order.url
  get_payment      paymentId → status
  list_payments    recent payments
  get_balance      balance in USD, read-only

For example, in Claude Code: claude mcp add --transport http norpo https://api.norpo.io/mcp --header "Authorization: Bearer nrp_live_sk_…". Use a separate key for the agent so you can revoke it on its own.

Checkout

Ways to pay

Every card payment opens the same checkout. Nothing to integrate: the buyer picks how to pay there, and your webhook or callback fires the same way whichever they choose.

Card, Apple Pay, Google Pay
Through the licensed providers available for the buyer’s country and amount, the best-converting one chosen already. 4.8%.
From an exchange
Binance, Bybit, OKX, KuCoin: a withdrawal of USDT or USDC to the order’s own address, with steps and the network named the way each exchange names it. 1.5%, or 0.4% with crypto to balance.
From a wallet
MetaMask, Trust, Rabby or any EVM wallet: a QR code or one tap opens the transfer already filled in. 1.5%, or 0.4% with crypto to balance.
From Solana
Phantom or Solflare pay in SOL with a Solana Pay code; it is converted on the way and paid out to your wallet. 1.5%.
No card option
Where no provider serves the buyer’s country or amount, the checkout says so and offers the ways above instead of a dead end.

Short payments

Exchanges often take their withdrawal fee out of the amount sent. When what arrives is short by no more than 3% of the order — and never more than $1 — the order still closes as paid. A bigger gap keeps the order open: the checkout tells the buyer how much is missing and they send the rest to the same address. Your callback fires once, when the order is complete.

On request

These options are off until they are switched on for your account. Crypto to balance and Telegram · CryptoBot you switch on yourself; for Changelly, ask in Telegram:

  • Crypto to balance. Any coin at checkout for 0.4%, credited to your Norpo balance. Switch it on in the dashboard under Crypto to balance. How it works.
  • Telegram · CryptoBot. The buyer pays an invoice from their @CryptoBot balance. The money is credited to your Norpo balance, minus 2%, and withdrawn as USDT on TRON. Switch it on in the dashboard: Settings → Ways your buyers can pay → Telegram.
  • Card, PayPal or Skrill via Changelly. The buyer buys USDC there and it goes straight to your order, 2% in total. Costs the buyer more than a direct card payment, so it is agreed with you first.

Crypto only

If you only need crypto, you can take crypto only. Cards, PayPal and local methods are switched off for your store, and the checkout opens straight on the crypto page: the buyer picks a coin and network and pays from an exchange or a wallet. The fee is 1.5% with the money straight to your wallet, or 0.4% with crypto to balance. Switch it on yourself in Settings → What buyers can pay with, or ask us in Telegram. Your integration stays the same, and you can switch back to all methods at any time.

Crypto to balance

Crypto to balance

A cheaper way to take crypto. Buyers pay in any coin at checkout, you pay 0.4% instead of 1.5%, and the money collects on your Norpo balance in USD until you withdraw it as USDT (TRC-20). Cards are not affected, and you do not change any code.

How it differs from standard crypto

Standard cryptoCrypto to balance
Your fee1.5%0.4%
Where the money goesStraight to your USDC (Polygon) walletYour Norpo balance, in USD
How you get itAutomatic, with every paymentYou withdraw as USDT (TRC-20)
Who holds itYouNorpo, until you withdraw
CoinsThe usual checkout coinsDozens of coins and networks
Minimum orderPer coinFrom $1 on Polygon to $50 on Ethereum, by coin and network
AvailabilityOn by defaultOne click in the dashboard

The difference that matters: with standard crypto the money reaches your wallet by itself. With crypto to balance Norpo holds it until you withdraw.

Turn it on

  1. Keep your USDC (Polygon) payout wallet in Settings. Cards and small orders still use it.
  2. Add a USDT (TRC-20) address under Balance. Withdrawals go there.
  3. Turn on two-factor authentication in Settings. Withdrawals need it.
  4. Press Request access under Crypto to balance in your dashboard. We switch it on for your account.

What happens to the money

An order for $250, paid in any coin:

AmountWhat happens
Order$250.00The buyer pays this, plus the conversion cost if the coin is not USDT on TRON
Your fee−$1.000.4%
On your balance$249.00Stays there until you withdraw
Network fee−$3.00Per withdrawal, not per payment
Reaches your wallet$246.00As USDT (TRC-20), within 60 minutes to 24 hours

The buyer pays the order price plus a conversion cost, unless they pay in USDT on TRON. It is included in the amount they see, and you do not pay it. You are credited the order amount minus 0.4%, whichever coin was used, so a coin’s price moving later does not change your balance.

Withdrawals
From $30, to the USDT (TRC-20) address on your account, with two-factor authentication. Each takes 60 minutes to 24 hours and costs $3 in network fees.
Small orders
An order below the minimum for every coin takes the standard route: straight to your wallet at 1.5%.
Amount window
The buyer sees a timer on the amount. If it runs out, the checkout gives a new amount for the same coin.

Your integration

If you use the checkout, a payment link or a plugin, there is nothing to do. The buyer sees more coins, and your webhook payment.settled fires as before.

If you show crypto on your own page with POST /v1/payments/:id/crypto, the coins go to your balance too. Show amountText, because it keeps every digit of the amount. The amount holds for validMinutes; after that, request the same coin again.

POST /v1/orders does not change: those orders still go straight to your wallet at the usual rate.

Questions

Does it replace standard crypto?
For checkout payments, yes, as long as the order meets the minimum. Smaller orders and POST /v1/orders stay on the standard route, so you can see payments of both kinds.
Do card payments change?
No. Cards keep their rate and keep going to your USDC (Polygon) wallet.
Can I use only a TRON address?
No. The USDC (Polygon) wallet stays required, because cards and small orders are paid to it.
Where do I see these payments?
Under Crypto to balance and Balance in your dashboard, next to your available amount and withdrawals.
Crypto

Crypto payments

Accept a named coin on a named chain, with the same API key. Each order gets its own deposit address and settlement forwards to your account’s payout wallet — or, for coins on other networks, to the wallet you pass for that network.

  1. Create the order with your API key, the coin (ticker) and the amount.
  2. Show the customer payTo and the amount, ideally as a QR code.
  3. Confirm when the callback arrives, after the deposit confirms on-chain.

Accept a named coin on a named chain. Each order opens its own deposit address — never reuse one. Coins on Polygon, BNB Chain and Ethereum settle to your account’s payout wallet; for other networks pass "wallet" on that network.

POST /v1/orders
curl -X POST https://api.norpo.io/v1/orders \
  -H "Authorization: Bearer nrp_live_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
      "ticker":      "polygon/usdc",
      "amount":      25,
      "callbackUrl": "https://shop.tld/hook",
      "callbackFormat": "json",
      "reference":   "order-1042"
     }'

# → 201
{
  "id":     "cmsey…",
  "status": "pending",
  "ticker": "polygon/usdc",
  "amount": 25,
  "payTo":  "0x2FE2…9580",
  "callbackSecret": "cbsec_8Kq2…"
}

# tickers: btc · eth · xmr · sol/sol · trx · ltc
#          polygon/usdc · erc20/usdt · trc20/usdt …

Confirm it

With "callbackFormat": "json" the callback is a signed POST, verified exactly like card payments with the order’s callbackSecret. It arrives after the deposit confirms on-chain.

POST your callbackUrl
Norpo-Event:     order.paid
Norpo-Signature: t=1790497260000,v1=9d07…

{
  "id":      "evt_77c0…",
  "event":   "order.paid",
  "created": 1790497260,
  "data": {
    "id":             "cmsey…",
    "status":         "paid",
    "reference":      "order-1042",
    "amount":         25,
    "coin":           "polygon/usdc",
    "amountReceived": "25.000000",
    "txHash":         "0x4b…9af"
  }
}

Integrated before October 2026? Nothing to change: payments and orders created without callbackFormat keep receiving the original GET callback, and every field you read today is still returned. Switch an integration over whenever it suits you by adding "callbackFormat": "json" to new orders.

Errors

Failures come back as JSON. For a bad or missing field (400) message is just "Invalid request" — the reason is in issues, one entry per field. Other errors put the reason in message.

MeaningWhat to do
201Done — the order existsUse the returned id; it is the only handle you get.
400A field is missing, malformed, or the provider refusedFor a field, read issues — it names the field and what is wrong. Where the provider refuses, its own sentence comes back in message unchanged.
404No such orderCheck the id. Ids are returned once, at creation.
422Valid request, cannot be fulfilledUsually no payout wallet on the account, or the network rejected that wallet. The message names the cause.
429Rate limitedBack off and retry. The limiter is per IP.
502Upstream unreachableNot your request. Retry shortly; if it persists, tell us.

Rules

One address, one order
Every order opens its own deposit address. Never reuse one: a second payment to a settled address is not credited automatically.
Match the network exactly
A polygon/usdc order takes USDC on Polygon. The same coin on another chain is a different asset and the funds are lost. The API checks the shape of your receiving address, not which chain you meant.
Show the exact amount
The customer sends the coin amount on the order. Less than that is not credited as paid; tell them to send it in one transfer.
No code

Plugins & modules

For a store, billing panel, forum or bot you already run. Free; connect each with your Norpo API key and it settles to the payout wallet in your account.

WordPress plugin

WooCommerce

Cards and crypto on any WordPress store.

ZIP · 39 KB
Download
Billing module

WHMCS

Every unpaid invoice gets a card-and-crypto pay button.

ZIP · 60 KB
Download
Forum add-on

XenForo

Paid user upgrades and Resource Manager sales.

ZIP · 23 KB
Download
Billing adapter

FOSSBilling

Open-source billing for hosting companies and VPN providers.

ZIP · 4 KB
Download
Gateway extension

Paymenter

Gateway extension for Paymenter v1, the open-source billing panel for game and VPS hosts.

ZIP · 4 KB
Download
WordPress plugin

Easy Digital Downloads

Sell software, ebooks and license keys on WordPress with cards and crypto.

ZIP · 4 KB
Download
WordPress plugin

Paid Memberships Pro

Membership sites on WordPress: one-off and fixed-term levels paid by card or crypto.

ZIP · 4 KB
Download
OpenCart 4 extension

OpenCart

Payment extension for OpenCart 4 stores.

OCMOD · 10 KB
Download
PrestaShop module

PrestaShop

Payment module for PrestaShop 1.7.6, 8 and 9.

ZIP · 7 KB
Download
Magento 2 module

Magento

Payment method for Magento 2.4 and Adobe Commerce.

ZIP · 15 KB
Download
Python & Node library

Telegram bots

Take payments inside a bot you already run. Python and Node.

ZIP · 33 KB
Download

Before you ship

The things that actually trip people up, in the order they hit them.

The key stays on your server
Never put nrp_live_sk_… in a browser, an app or a plugin someone else can read. If it leaks, revoke it in Settings → API keys — it stops working at once.
Confirm before you fulfil
Treat the callback as a nudge, not a receipt. Re-check with GET before releasing goods, and keep the handler idempotent — it can fire more than once.
Amounts are decimal strings
Send 250.00, not cents. Currency is the three-letter code; the customer pays in it and you are paid out in crypto — ETH, USDC or USDT (Polygon or BEP-20), or POL.
Bill in the customer’s own currency
Local payment methods only appear when the invoice is in the local money. A Swedish customer billed in SEK is offered Klarna; billed in EUR they are not. India’s UPI accepts nothing but INR. Charging everyone in USD quietly removes the way most of them would rather pay.

Something not covered here? Ask on @norpoio — a real person answers.