Payr API

Payr is an account-less card → crypto on-ramp. Create a payment with a destination wallet and an amount, send your buyer to a hosted page or straight to an onramp provider, and Payr forwards the crypto on-chain — minus a flat 3%. No keys, no signup, no Stripe.

How it works Create payment Payment options Payment link Status Webhooks Lifecycle Assets & methods Errors

How it works

Create a payment. POST the destination wallet, asset/network and amount to /api/create-payment. You get back a code, a hosted_url, and a direct_link template.

Send the buyer to pay. Either redirect to the hosted_url (Payr lists every available onramp method) or build a direct link /go/{code}/{method} that forwards straight to one provider's card widget.

The provider does the card → crypto. Guardarian, Transak, MoonPay, etc. take the card and deliver crypto to a Cryptomus deposit wallet Payr controls.

Payr settles & forwards. On settlement Payr takes the 3% fee and forwards the rest on-chain to the buyer's wallet, then fires your webhook.

There are no API keys: every payment is identified by its opaque code (a UUID). The commission is 3% of the settled amount (payout = received × 0.97).

Create a payment

POST https://payr.to/api/create-payment

Field	Req	Description
`wallet`	yes	Destination wallet address (the buyer's own wallet).
`currency`	yes	Payout asset, e.g. `USDT`, `BTC`, `ETH`.
`network`	yes	Payout network, e.g. `TRON`, `ETH`, `POLYGON`.
`amount`	yes	Fiat amount the buyer pays.
`fiat_currency`	no	Defaults to `USD`. Supports USD, EUR, GBP, CAD, AUD and more.
`external_reference`	no	Your own order id (echoed back in webhooks).
`webhook_url`	no	Where Payr POSTs status updates.
`success_url` / `cancel_url`	no	Where to send the buyer afterwards.
`email`	no	Optional receipt email.

curl -X POST https://payr.to/api/create-payment \
  -d wallet=TXYZ...your-wallet \
  -d currency=USDT -d network=TRON \
  -d amount=200 -d fiat_currency=USD \
  -d external_reference=ORDER-9921 \
  -d webhook_url=https://yourapp.com/hooks/payr

{
  "status": "success",
  "message": "Payment created.",
  "data": {
    "code": "7c1f...-...-...",
    "amount_in_usd": 200,
    "commission": 3,
    "hosted_url":  "https://payr.to/pay/7c1f...",
    "direct_link": "https://payr.to/go/7c1f.../{method}",
    "webhook_secret": "whsec_3f9a...c21",
    "payment_options": [ { "name": "guardarian", "show_name": "Guardarian", "min_checkout": 20, "max_checkout": 10000 }, ... ]
  }
}

Then either redirect to hosted_url, or replace {method} in direct_link with a method name from payment_options.

Payment options

GET https://payr.to/api/payment-options?fiat_amount=200&fiat_currency=USD

Lists the onramp methods available for an amount, already filtered by each method's min_checkout/max_checkout. Use it to render your own picker.

Payment link

GET https://payr.to/api/payment-link?code={code}&method={method}

Returns the provider redirect URL for a chosen method:

{ "status": "success", "data": { "redirect_url": "https://.../widget..." } }

Or skip the JSON and use the 302 forwarder directly — ideal as a shareable link:

GET https://payr.to/go/{code}/{method}

Status

GET https://payr.to/api/status?code={code}

{
  "status": "success",
  "data": {
    "code": "7c1f...", "status": "COMPLETED",
    "currency": "USDT", "network": "TRON",
    "amount_in_usd": "200.00", "commission_usd": "6.00", "payout_usd": "194.00",
    "payout_txid": "0x...", "external_reference": "ORDER-9921"
  }
}

Webhooks

If you pass a webhook_url, Payr POSTs JSON as the payment progresses. Each request carries:

X-Payr-Signature — HMAC-SHA256(rawBody, webhook_secret)
X-Payr-Event — the event name (also in the body)

The webhook_secret is the value returned once in the create-payment response — it is unique per payment. Store it against your order, and verify every webhook before trusting it. The secret itself is never sent in a webhook; only the signature is.

// PHP — verify an incoming Payr webhook
$body   = file_get_contents('php://input');
$sig    = $_SERVER['HTTP_X_PAYR_SIGNATURE'] ?? '';
$secret = lookup_webhook_secret_for($body);   // the whsec_... you stored at create time
if (!hash_equals(hash_hmac('sha256', $body, $secret), $sig)) {
    http_response_code(400); exit;            // reject — not from Payr
}
$event = json_decode($body, true);            // trusted from here

Event	When
`payment.received`	Onramp funded; settled to USDC; payout dispatched.
`payment.completed`	Crypto delivered on-chain to the buyer's wallet.
`payment.failed`	Payout failed.

{
  "event": "payment.completed",
  "code": "7c1f...",
  "external_reference": "ORDER-9921",
  "status": "COMPLETED",
  "payout_txid": "0x...",
  "payout_usd": "194.00",
  "wallet_address": "TXYZ...", "currency": "USDT", "network": "TRON",
  "timestamp": 1716282600
}

Payment lifecycle

PENDING — created, buyer hasn't funded yet.
RECEIVED — onramp delivered crypto, settled to USDC.
PROCESSING — payout to the destination wallet submitted.
COMPLETED — crypto delivered on-chain. ✅
FAILED — payout failed.
EXPIRED — never funded in time.

Forward transitions are atomic and de-duplicated, so a payout is dispatched at most once per payment even under duplicate provider/webhook delivery.

Supported assets & methods

Payout assets include USDT (Tron/ETH/BSC/Polygon), USDC (ETH/Polygon/BSC), BTC, ETH, LTC, BNB, SOL, TRX.

Onramp methods (card → crypto): Guardarian, Transak, Mercuryo, MoonPay, Paybis, Kado, Wert, Ramp, Robinhood, Coinbase Pay, Onramp.money, Sardine, Stix, Binance Connect — plus EUR/GBP/CAD provider variants. Availability depends on the amount (per-method min/max).

Response envelope & errors

Every JSON response is { status, message, data, timestamp }. status is success or failed. On failure, message explains why and the HTTP code is 4xx/5xx.

{ "status": "failed", "message": "No payment methods are available for that amount.", "data": [], "timestamp": 1716282600 }

Questions? support@payr.to