# Payment gateway

A **payment** is one order, one price in US dollars, and one deadline. Your backend (or your
store plugin) creates it; the customer pays it on the hosted checkout; you are told when it
is paid. The money lands in your own balance, minus your ordinary deposit fee — nothing is
added to the price your customer sees.

**What a customer can pay with** — every coin the platform receives, on its own network:

| Network | Coins |
| --- | --- |
| TRON | USDT (TRC20), TRX |
| BNB Smart Chain | USDT, USDC (BEP20), BNB |
| Solana | USDT, USDC (SPL), SOL |
| Bitcoin | BTC |
| TON | USDT, TON |

`GET /v1/payments/assets` is what can be paid **right now**; the checkout offers exactly that
list. Confirmations per network are on [Networks](networks).

**What it costs.** The ordinary fees, nothing gateway-specific: a payment is credited like a
deposit — no platform fee; free on TRON and BNB Smart Chain, and on the other networks less
the live network cost of moving it into our wallet — and money you send out later is a
payout (a flat platform fee plus the live network cost). Every figure is on the live
[price sheet](fees) and `GET /v1/pricing`; never copy one into your checkout.

A payment is not a [deposit address](deposit-addresses). A deposit address is permanent and
belongs to one user; a payment belongs to one order and closes on a clock.

**Create payments from your backend, never from a browser.** Your API key is your account.

**Using a store?** Download its plugin below (also in the dashboard, Payments → Plugins).
Each needs a project API key and the callback secret, and nothing below. Each has a
**Payment page** setting: *Redirect* (the customer goes to the payment page and comes back)
or *Embedded on your site* (the payment page sits inside your own order page — section 1a).

| Platform | Download | Install |
| --- | --- | --- |
| WooCommerce | [woocommerce.zip](https://cryptoinfra.net/downloads/woocommerce.zip) | WordPress → Plugins → Add New → Upload. Classic and block checkout. |
| Easy Digital Downloads | [edd.zip](https://cryptoinfra.net/downloads/edd.zip) | WordPress plugin, EDD 3. |
| Paid Memberships Pro | [pmpro.zip](https://cryptoinfra.net/downloads/pmpro.zip) | WordPress plugin, one-time levels. |
| Gravity Forms | [gravityforms.zip](https://cryptoinfra.net/downloads/gravityforms.zip) | WordPress plugin, product payments. |
| Restrict Content Pro | [rcp.zip](https://cryptoinfra.net/downloads/rcp.zip) | WordPress plugin, one-time payments. |
| WHMCS | [whmcs.zip](https://cryptoinfra.net/downloads/whmcs.zip) | Unzip into the WHMCS root; activate under Apps & Integrations. |
| Blesta | [blesta.zip](https://cryptoinfra.net/downloads/blesta.zip) | Unzip into the Blesta root; install under Payment Gateways. |
| WISECP | [wisecp.zip](https://cryptoinfra.net/downloads/wisecp.zip) | Unzip into the WISECP root. |
| Clientexec | [clientexec.zip](https://cryptoinfra.net/downloads/clientexec.zip) | Unzip into the Clientexec root. |
| PrestaShop 8 | [prestashop.zip](https://cryptoinfra.net/downloads/prestashop.zip) | Modules → Upload a module. |
| OpenCart 4 | [opencart.zip](https://cryptoinfra.net/downloads/opencart.zip) | Extensions → Installer. |
| Magento 2 / Adobe Commerce | [magento2.zip](https://cryptoinfra.net/downloads/magento2.zip) | `app/code/Cryptoinfra/Payment`, then `setup:upgrade`. |
| VirtueMart 4 | [virtuemart.zip](https://cryptoinfra.net/downloads/virtuemart.zip) | Joomla → Extensions → Install. |
| Laravel | [laravel.zip](https://cryptoinfra.net/downloads/laravel.zip) | A package for your own Laravel app: client, webhook route, events. |

**Writing code?** SDKs for Node/TypeScript, Python and PHP wrap the calls on this page and
the webhook signature check. **No code?** n8n, Zapier and Make apps create payments
and react to `payment.*` events, and a self-hosted Telegram bot lets your staff create a
payment from a chat (`/pay 25`) and posts there when it is paid. All of them are on the same
Payments → Plugins page.

**On Shopify?** There is no native Shopify payment method (Shopify approves those
providers itself). Use a payment link (section 5 below) instead: create
one per product or an open-amount one, and put it on the order confirmation or a manual
payment method's instructions.

## 1. Create it

```bash
curl https://api.cryptoinfra.build/v1/payments \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "wc-1001",
    "amount": "49.99",
    "description": "Order #1001",
    "callback_url": "https://shop.example/crypto/callback",
    "return_url": "https://shop.example/order/1001/thanks"
  }'
```

| Field | What it is |
| --- | --- |
| `order_id` | your reference — letters, digits and `. : @ / # - _`, up to 128. **One payment per order id per project**: the same order again with the same `amount`, `asset_id` and `callback_url` returns the same payment (`200`); anything different is a `409 order_id_conflict` — use a new order id (e.g. `1001-2`) |
| `amount` | the price in USD, as a decimal string |
| `asset_id` | optional — lock the coin now. Leave it out and the customer picks on the checkout |
| `callback_url` | optional — this payment's events go here too, signed with your project's callback secret |
| `return_url` | optional — the checkout's "Back to the shop" button once paid |
| `ttl_seconds` | optional — how long the customer has (300 to 86400; default from your settings, 1 hour) |
| `metadata` | optional — any small key/value object; echoed on every read and event |

The response carries `checkout_url` — a page on `https://pay.cryptoinfra.net`. Send the customer there and you are done until the
webhook arrives. On that page the customer picks the coin, then the network it travels on,
and proceeds; only then are the address and the amount set (and, for a coin that is not a
stablecoin, the rate locked). They send, the page confirms the payment by itself and ends on
a receipt. If you set a support email or link (section 4), the page offers it as
"Need help?".

## 1a. Keep the customer on your site

The payment page also works inside a frame on your own page — and knows it is framed by
itself, so any `checkout_url` can be embedded as it is. The simplest way is one script tag
where the payment should appear:

```html
<script src="https://pay.cryptoinfra.net/embed/checkout.js"
        data-checkout="CHECKOUT_URL" data-theme="light" async></script>
```

It draws a frame that is always exactly as tall as the page and fits any width (two columns
on a wide page, one on a phone). Once the payment is paid it waits three seconds on the
receipt, then sends the whole window to the payment's `return_url`. Options:
`data-theme="light"` or `"dark"` to match your site (without it the page follows the
customer's device), `data-redirect="off"` to stay on the receipt, `data-target="#pay"` to
draw the frame inside an element of yours. `data-link="LINK_CODE"` embeds a payment link
(section 5) instead.

Your page hears what happens — `window.addEventListener('cryptoinfra:status', e => …)`,
with `e.detail` = `{ status, order_id, return_url }`. Use it to show your own message, but
fulfil the order on the webhook (section 3), never on this event.

Your own `<iframe>` works too: `<iframe src="CHECKOUT_URL" allow="clipboard-write"
style="width:100%;border:0">`, add `theme=light` or `theme=dark` to the URL's query if you
like. The page posts `{ source: 'cryptoinfra', type: 'resize', height }` and
`{ source: 'cryptoinfra', type: 'status', status, order_id, return_url }` to its parent;
check `event.origin` is `https://pay.cryptoinfra.net` before you use them.

## 2. Or render your own checkout

Give `asset_id` (see `GET /v1/payments/assets` for what can be paid right now) and the
response also carries `address`, `payer_amount` and `expires_at` — the complete payment
instruction. Show exactly `payer_amount` of that coin, to that address, on that network.

A USD stablecoin is priced at exactly 1 (49.99 USD asks 49.99 USDT). Any other coin is
converted at the live rate when the coin is chosen, and that rate is locked: it never moves
afterwards.

## 3. Fulfil on the webhook

| Event | Status | What to do |
| --- | --- | --- |
| `payment.paid` | `paid` or `overpaid` | fulfil the order |
| `payment.underpaid` | `underpaid` | less than the price arrived before the deadline — your call |
| `payment.expired` | `expired` | nothing arrived — cancel the order |
| `payment.late_paid` | `expired_paid` | money arrived after the deadline — decide by hand |

Events go to your project's registered [webhook](webhooks) endpoints, and to the payment's
`callback_url` when it has one. Both are signed: `x-cryptoinfra-signature` is the hex
HMAC-SHA256 of the raw body — with the endpoint's secret for a registered endpoint, and with
your project's **callback secret** (`GET /v1/payments/settings`, or Payments → Gateway
settings in the dashboard) for a `callback_url`. Verify before you trust; or read
`GET /v1/payments/{id}` with your key, which is the truth either way.

A transfer that was sent before the deadline but is still confirming keeps the payment open
as `confirming` — the customer is never expired for how long the network took.

## 4. Settings

`POST /v1/payments/settings` sets, per project: the default time to pay, an **underpaid
tolerance** (a number, 0 to 5 %: a payment short by at most that much still counts as
`paid`; read back as a decimal string), a new callback secret
(`rotate_callback_secret: true`), and the **support your customers see** on the payment
page — `support_email` and `support_url` (`https://` only); an empty string or `null`
clears one, and with neither set the page shows no help link. The same settings are in the
dashboard under Payments → Gateway settings.

## 5. Payment links and donation buttons

No code at all: `POST /v1/payment-links` (or Payments → Links & buttons in the dashboard)
makes a reusable link — `fixed` with a price, or `open` where the payer types the amount
(donations, tips), optionally between `min_amount` and `max_amount`. Share its `url`, or put
a button on any web page:

```html
<script src="https://pay.cryptoinfra.net/embed/button.js"
        data-link="YOUR_LINK_CODE" data-label="Donate with crypto" async></script>
```

The button opens the link's page in a new tab. To put the page itself on yours instead,
use the embedded checkout with `data-link` (section 1a).

Each payer makes a new payment (order id `link-…`, `metadata.link` = the link id), so the
same webhooks and the same Payments list apply.

## 5a. Point of sale

For a counter or a market stall: **Payments → Point of sale** in the dashboard is a keypad.
Type the amount in USD, the customer scans the code on the screen with their wallet and picks
the coin, and the screen turns green when the payment is paid. It is an ordinary payment —
same webhooks, same Payments list, same fees — made without a line of code.

## 6. Moving the money: auto-convert and auto-settle

Gateway money lands in your own balance. In the dashboard (Payments → Auto-settle) the
account owner can add daily rules: **convert** one coin to another at 02:00 IST (for
example TRX → USDT), and **send** a coin to your own wallet at 03:00 IST, always keeping an
amount you choose. A new address, or a new coin to buy, starts working 24 hours after it is
saved, and a send above your approval threshold still waits for approval. Only the account
owner can set them, each change is confirmed with the authenticator code, and rules are set
from the dashboard only — never with an API key.

## 7. Testing in the sandbox

Against `https://merchant.cryptoinfra.build/sandbox` everything above works with fake money.
`POST /v1/simulate/payment` with `{"payment_id": "pay_…"}` pays a payment (in full, or
`amount` for a partial one, or `asset_id` for the wrong coin) and the payment.* events are
delivered to your endpoints and `callback_url` as in production.

## What a payment never does

- It never re-prices: the amount the customer was shown is the amount.
- It never loses money: a transfer of the wrong coin, or after the deadline, is still
  credited to your balance and shows on the payment — it just does not mark it paid.
- It is never paid twice: a settled status is final.
