PayLioDocs

API Reference

Create Checkout

Create a hosted card checkout that settles as USDC on Polygon in your wallet.

POSThttps://paylio.org/api/v1/wallet

Returns a checkout_url to redirect the customer to, plus the IDs you need to verify the payment later. Parameters can be sent as a JSON body (recommended) or as query-string parameters on a GET request.

Body parameters#

addressstringrequired
Your Polygon wallet that receives USDC (0x…). Mixed-case addresses must have a valid checksum; the zero address is rejected.
callbackstringrequired
HTTPS URL that receives the webhook. Max 2048 characters. Must be publicly reachable: localhost, private IPs and URLs with credentials are rejected.
amountstring | numberrequired
Order amount between 0.01 and 10000, with at most two decimals. A string such as "49.99" is recommended.
currencystring
USD (default), EUR, CAD or INR.
passFeeToCustomerboolean
If true, the checkout amount is raised so you receive the full amount. Also accepted as pass_fee_to_customer. See fee pass-through.
providerstring
On-ramp provider ID. Defaults to multi, which lets the customer choose. See Providers.
emailstring
Customer email. Pre-fills the checkout. Together with a single provider, the customer is sent straight to that provider.
notestring
Up to 500 characters. Shown in your dashboard and included in webhooks. It also appears in short-link previews, so do not put private data here.

Example#

Request#

curl -X POST https://paylio.org/api/v1/wallet \
  -H "Authorization: Bearer plio_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address":  "0xYourPolygonWallet",
    "callback": "https://example.com/paylio/webhook",
    "amount":   "49.99",
    "currency": "USD",
    "passFeeToCustomer": true
  }'

Response#

200 OK

Response · JSON
{
  "payment_id":           "3f6c2a1e-8b4d-4c7a-9e21-5d0b7f9a1c34",
  "ipn_token":            "f7e9d3a1-4b8e-4a2f-9c6e-1234567890ab",
  "checkout_url":         "https://paylio.org/pay/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f9a1c34",
  "short_code":           "a8wB3v4R",
  "short_url":            "https://paylio.org/p/a8wB3v4R",
  "callback_url":         "https://example.com/paylio/webhook",
  "address_in":           "0xa1B2c3...",
  "polygon_address_in":   "0x32e854bD1270670C832634CA87858fFd9F3e2c78",
  "payment_type":         "card",
  "provider":             "multi",
  "amount":               "54.34",
  "original_amount":      "49.99",
  "customer_fee_amount":  "4.35",
  "pass_fee_to_customer": true,
  "fee_percent":          8,
  "status":               "unpaid"
}

Response fields#

payment_idstring
Unique payment ID (UUID). Store it on your order.
ipn_tokenstring
Secret used to verify webhook signatures. Store it on your order and never expose it to the customer.
checkout_urlstring
Hosted checkout. Redirect the customer here.
short_urlstring
Short link to the same checkout, handy for email or chat.
amountstring
Amount the customer pays. Includes the fee when pass_fee_to_customer is true.
original_amountstring | null
The amount you requested, before fee pass-through.
customer_fee_amountstring | null
Fee added to the checkout amount, if any.
fee_percentnumber
Your account's card fee in percent.
providerstring
The provider used for this checkout.
statusstring
Always unpaid on creation.
address_in / polygon_address_instring
Internal settlement addresses, useful for reconciliation only.

Next step

Set up your webhook handler, then always confirm with Payment Status before you fulfil the order.

Errors#

Validation errors return 400 with a readable error message. Provider problems add a code such as below_minimum or currency_locked. See Errors & Rate Limits for the full list.