Knowledge Base
  1. Home
  2. Knowledge Base
  3. Developer guides
Developer guides

XRP payment API with destination tags (developer guide)

Accept native XRP with the PayGate.to API: payout wallets with destination tags or X-addresses, amount and QR code, hosted checkout and callback matching.

3 min readUpdated Intermediate
On this page
  1. Tickers
  2. Your payout wallet
  3. Step 1: Create the payment address
  4. Step 2: Amount and QR code
  5. Step 3: The callback
  6. Hosted checkout
  7. Limits to show customers
  8. Frequently asked questions

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

TickerAssetPayout wallet
xrpNative XRP on the XRP Ledgerr…, r…?dt=TAG or an X-address
bep20/xrpAn XRP token on BNB Smart Chain0x… (your EVM wallet)

This guide is about xrp.

Your payout wallet

FormExampleWhen
Classic addressrf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2JpnYour own self-custodial wallet
Classic + tagrf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn?dt=777Your wallet or account requires a tag
X-addressX7qvLs7gSnNoKvZzNWUT2e8st17QPY84SkdtoNKGbhoPHEWAddress 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

bash
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

bash
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

text
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%7D

address_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:

php
use PayGate\Crypto\XrpAddress;

XrpAddress::payoutForm('X7qvLs7gSnNoKvZzNWUT2e8st17QPY84SkdtoNKGbhoPHEW');   // 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn?dt=777'
$toMe = $data->getPayoutFor('X7qvLs7gSnNoKvZzNWUT2e8st17QPY84SkdtoNKGbhoPHEW');   // works with any form
js
import { 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):

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.php returns 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.

This guide is also available as Markdown for AI assistants and offline reading.