PayLio
Documentation

Accept cards. Settle in USDC.

One POST creates a hosted checkout page. One redirect sends the customer. One callback confirms the payment. Your Polygon wallet receives USDC within seconds — no SDK, no setup fee, no KYC.

Get API KeyStart integrating

2

endpoints

~5 min

integration

~3 s

settlement

01·60-second integration

Quickstart

One POST, one redirect, one webhook handler. That's the entire integration — you can be live before lunch.

  1. 01

    Create wallet + link

    POST /api/v1/wallet returns checkout_url and ipn_token.

  2. 02

    Redirect customer

    Send the buyer to checkout_url — PayLio hosts the checkout.

  3. 03

    Receive callback

    PayLio GETs your URL with status=paid and the on-chain txid.

Quickstart · cURL
# 1 · Create the checkout link
curl -X POST https://paylio.org/api/v1/wallet \
  -H "Authorization: Bearer plio_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "address":  "0xYourPolygonWallet",
    "callback": "https://example.com/order/123/callback",
    "amount":   "49.99",
    "currency": "USD"
  }'

# 2 · Redirect the customer
#   → checkout_url

# 3 · Receive the callback when they pay
#   GET https://example.com/order/123/callback?status=paid&txid_out=…
02·Reference

Authentication

Every request to POST /api/v1/wallet and GET /api/v1/payment-status requires an API key.

Where to manage keys

Dashboard › API Keys

Full create / list / revoke page.

Dashboard › Settings

Same controls, embedded under the Developer section.

Send the key

Either header works — use one, not both:

HTTP headers
Authorization: Bearer plio_live_YOUR_KEY
# or
X-API-Key: plio_live_YOUR_KEY
Treat keys like passwords. They inherit the fee schedule of the account that created them. PayLio only stores a SHA-256 hash — if you lose a key, generate a new one and revoke the old.
03·Endpoint

Create Wallet & Checkout Link

Generates a hosted-checkout page and returns a ready-to-redirect checkout_url plus an ipn_token for tracking. Accepts JSON POST or query-string GET.

POST/api/v1/wallet
Card onramp only. At this stage the API creates card-funded payments that settle as USDC on Polygon. For direct-crypto flows, create the payment from your dashboard or use the WooCommerce / WHMCS module.

Request parameters

addressstringrequired
Your Polygon USDC payout wallet (0x…). Funds are forwarded here after every successful payment.
callbackurlrequired
Endpoint PayLio GETs when payment completes. See Callback.
amountstring | numberrequired
Order total. Decimal string preferred (e.g. "105.78") to avoid float rounding.
currencystring
ISO code: USD, EUR, GBP, CAD. Default USD.
emailstring
Customer email. Pre-fills the checkout page and is included in the callback.
notestring
Free-form note shown in your PayLio dashboard. Not visible to customers.

Sample request

Request · curl
curl -X POST https://paylio.org/api/v1/wallet \
  -H "Authorization: Bearer plio_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address":  "0xF977814e90dA44bFA03b6295A0616a897441aceC",
    "callback": "https://example.com/orders/12345/paylio-callback",
    "amount":   "105.78",
    "currency": "USD",
    "email":    "[email protected]"
  }'

Response — 200 OK

Response · JSON
{
  "address_in":         "0xa1B2c3...derived",
  "polygon_address_in": "0x32e854bD1270670C832634CA87858fFd9F3e2c78",
  "ipn_token":          "f7e9d3a1-4b8e-4a2f-9c6e-1234567890ab",
  "callback_url":       "https://example.com/orders/12345/paylio-callback",
  "payment_id":         "clx9k2m3a0001a8w0b3v4r5g6",
  "short_code":         "a8wB3v4R",
  "short_url":          "https://paylio.org/p/a8wB3v4R",
  "checkout_url":       "https://paylio.org/pay/clx9k2m3a0001a8w0b3v4r5g6",
  "payment_type":       "card",
  "status":             "unpaid"
}

Response fields

address_instring
The opaque deposit address embedded in checkout_url. Normally you don't need to render it yourself.
polygon_address_instring
Decrypted Polygon address. Useful for internal reconciliation.
ipn_tokenstring
Pass to /api/v1/payment-status to verify the callback or poll status. Save it on your order row.
checkout_urlurl
Redirect the customer here.
short_urlurl
Branded short link to the same checkout page (good for email / SMS).
payment_idstring
PayLio internal ID. Alternative input for /payment-status.
payment_typestring
Always "card" for API-created payments at this stage.
statusstring
Always "unpaid" at creation. Updates after payment.
04·Endpoint

Check Payment Status

Server-to-server status check. Use it to verify a callback (always do this!) or to poll while the customer is still on the checkout page.

GET/api/v1/payment-status

Request parameters

ipn_tokenstring
The token from /wallet. Either this or payment_id is required.
payment_idstring
PayLio payment ID.

Sample request

Request · cURL
curl "https://paylio.org/api/v1/payment-status?ipn_token=f7e9d3a1-..." \
  -H "Authorization: Bearer plio_live_YOUR_KEY"

Response — 200 OK

Response · JSON
{
  "status":           "paid",
  "value_coin":       "105.6",
  "txid_in":          "0xa22a82b4aefbc55f6382e1b5c0b4f0e3c034a654df3bcac431f7fed1942e22bc",
  "txid_out":         "0x94c2c3e84c2021e6bf377aebf8abf03b49570611bb0c336e357d7f4516f56244",
  "coin":             "polygon_usdc",
  "address_in":       "0x32e854bD1270670C832634CA87858fFd9F3e2c78",
  "payment_id":       "clx9k2m3a0001a8w0b3v4r5g6",
  "amount":           "105.78",
  "currency":         "USD",
  "forward_status":   "completed",
  "forwarded_amount": "105.6",
  "paid_at":          "2026-04-28T13:01:42.000Z",
  "created_at":       "2026-04-28T12:59:11.000Z"
}

Response fields

statusstring
unpaid · paid · canceled.
value_coinstring
Amount received in the settlement coin (e.g. USDC).
txid_instring
Hash of the deposit transaction into PayLio's processing wallet.
txid_outstring
Hash of the payout transaction to your merchant wallet.
coinstring
Ticker of the settlement coin (e.g. polygon_usdc).
forward_statusstring
pending · processing · completed · failed. Treat completed as final.
forwarded_amountstring
Final amount delivered to your wallet (after all fees).
05·Webhook

Callback

On payment completion PayLio appends data to your callback URL and GETs it. Treat callbacks as untrusted hints — always verify with /payment-status.

Callback parameters

statusstring
paid on success.
value_coinstring
USDC amount received.
coinstring
Settlement coin ticker.
txid_instring
Hash of the customer's deposit tx.
txid_outstring
Hash of the payout to your wallet.
address_instring
Matches polygon_address_in from /wallet.
ipn_tokenstring
The token from /wallet.
payment_idstring
PayLio payment ID.

Sample callback URL

Inbound GET
https://example.com/orders/12345/paylio-callback
  ?value_coin=105.6
  &coin=polygon_usdc
  &txid_in=0xa22a82b4aefbc55f6382e1b5c0b4f0e3c034a654df3bcac431f7fed1942e22bc
  &txid_out=0x94c2c3e84c2021e6bf377aebf8abf03b49570611bb0c336e357d7f4516f56244
  &address_in=0x32e854bD1270670C832634CA87858fFd9F3e2c78
  &ipn_token=f7e9d3a1-...
  &payment_id=clx9k2m3a0001a8w0b3v4r5g6
  &status=paid

Sample handler

Express · Node.js
// Express · Node.js
app.get("/orders/:id/paylio-callback", async (req, res) => {
  const { ipn_token } = req.query;

  // 1. ALWAYS re-verify — query strings can be spoofed if your URL leaks.
  const verify = await fetch(
    `https://paylio.org/api/v1/payment-status?ipn_token=${ipn_token}`,
    { headers: { Authorization: `Bearer ${process.env.PAYLIO_API_KEY}` } },
  ).then((r) => r.json());

  if (verify.status !== "paid") {
    return res.status(400).send("Not yet paid");
  }

  // 2. Mark the order paid — make this idempotent (e.g. WHERE status != 'paid').
  await markOrderPaid(req.params.id, {
    txid:       verify.txid_out,
    amountUsdc: verify.value_coin,
  });

  // 3. Respond 200 within 10s. Do heavy work in a background job.
  res.status(200).send("ok");
});
Three rules:
  1. Always re-verify with /payment-status before fulfilling.
  2. Make your handler idempotent — we retry on non-2xx responses.
  3. Respond 200 within 10 s; do heavy work async.
06·Reference

Error Codes

Errors return JSON of the form { "error": "...", "code": "..." } (the code field is included when actionable).

HTTPCauseWhat to do
400Validation failed (missing field, invalid wallet, amount below minimum, …).Read error — safe to retry after fixing input.
401Missing, invalid, or revoked API key.Generate a new key in dashboard › API Keys.
404Payment not found, or owned by a different user.Verify the ipn_token / payment_id.
429Too many requests in a short window.Honour the Retry-After header and back off with jitter.
500Server error (upstream down, RPC unreachable, …).Retry with exponential backoff. Contact support if it persists.

Sample error response

Error · 400
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "address must be a valid Polygon (USDC) wallet starting with 0x",
  "code":  "invalid_wallet"
}
Ready to ship

Integrate in an afternoon.

Generate your first API key, copy a sample request, and start receiving USDC today. No KYC, no setup fee, no SDK to install.

Generate API keyTalk to a developer