Native XRP on the XRP Ledger works like every other coin in the PayGate.to API, with one twist: your payout wallet may carry a destination tag. The customer never needs one; they pay a one-time r… address and PayGate.to forwards the XRP to your address with your tag. Merchant overview: Accept XRP payments.
Tickers
| Ticker | Asset | Payout wallet |
|---|---|---|
xrp | Native XRP on the XRP Ledger | r…, r…?dt=TAG or an X-address |
bep20/xrp | An XRP token on BNB Smart Chain | 0x… (your EVM wallet) |
This guide is about xrp.
Your payout wallet
| Form | Example | When |
|---|---|---|
| Classic address | rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn | Your own self-custodial wallet |
| Classic + tag | rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn?dt=777 | Your wallet or account requires a tag |
| X-address | X7qvLs7gSnNoKvZzNWUT2e8st17QPY84SkdtoNKGbhoPHEW | Address and tag in one string |
The two last examples are the same destination. How to get one: Get an XRP address with a destination tag.
Step 1: Create the payment address
curl "https://api.paygate.to/crypto/xrp/wallet.php?address=rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn%3Fdt%3D777&callback=https%3A%2F%2Fshop.example8585859.com%2Fpaygate%2Fcallback%3Forder%3D1001"The ?dt= inside the address is part of a query value, so it's URL-encoded as %3Fdt%3D. The response has address_in (a one-time r… address), callback_url and ipn_token. A wallet on another network is refused with HTTP 400.
Step 2: Amount and QR code
curl "https://api.paygate.to/crypto/xrp/convert.php?value=49.90&from=USD"
# {"status": "success", "value_coin": "51.78123", "exchange_rate": "1.03770"}
curl "https://api.paygate.to/crypto/xrp/qrcode.php?address=ADDRESS_IN&amount=51.78123"
# {"status": "success", "qr_code": "iVBORw0KGgo…"} (base64 PNG)Show the customer the amount, address_in and the QR code. Tell them no destination tag is needed.
Step 3: The callback
GET /paygate/callback?order=1001&value_coin=51.78123&coin=xrp&txid_in=…&txid_out=…
&address_in=r…&value_forwarded_coin=51.25&address_out=%7B%22rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn%3Fdt%3D777%22%3A%221.0000%22%7Daddress_out reports your payout as r…?dt=TAG (or plain r… without a tag), also when you configured an X-address. Compare in that form, or let the SDK do it:
use PayGate\Crypto\XrpAddress;
XrpAddress::payoutForm('X7qvLs7gSnNoKvZzNWUT2e8st17QPY84SkdtoNKGbhoPHEW'); // 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn?dt=777'
$toMe = $data->getPayoutFor('X7qvLs7gSnNoKvZzNWUT2e8st17QPY84SkdtoNKGbhoPHEW'); // works with any formimport { xrpPayoutForm } from 'paygate-to';
xrpPayoutForm('X7qvLs7gSnNoKvZzNWUT2e8st17QPY84SkdtoNKGbhoPHEW'); // 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn?dt=777'
const toMe = data.payoutFor(process.env.PAYGATE_XRP_WALLET);A payout to the same address with a different tag is not yours: getPayoutFor('r…?dt=778') returns null. Verify the signature first: Verify PayGate.to callback signatures.
Hosted checkout
In the POST /crypto/multi-hosted-wallet.php body the key is xrp, and the value is not URL-encoded (it's JSON):
{ "xrp": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn?dt=777", "fiat_amount": 49.90, "fiat_currency": "USD", "callback": "https://shop.example8585859.com/paygate/callback?order=1001" }Other key names, such as ripple or xrpl, are ignored. See Build a hosted multi-coin checkout.
Limits to show customers
- Minimum: 2 XRP at the time of writing (
GET /crypto/xrp/info.phpreturns the live value). - Reserve: a brand-new payout address needs 1 XRP to exist on the ledger. The first payout funds it.
- Speed: XRP Ledger payments are final in seconds, so callbacks arrive quickly.
We ran every call above against the live API while writing this guide (an X-address payout wallet, conversion, a QR code, and a refused 0x… wallet), and the callback matching with the PHP and Node.js SDKs.
Frequently asked questions
Do I need a destination tag?
Only if your receiving account needs one. A self-custodial wallet address of your own usually doesn't.
Why does my callback show an r-address when I set an X-address?
PayGate.to decodes X-addresses into the classic address plus tag. It's the same destination.
Can a customer pay with a tag?
They can, but they don't need to: the one-time address identifies the order.
