# 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.

Source: https://withoutkyc.to/knowledge-base/developers/xrp-payment-api/
Updated: 2026-11-15

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](https://withoutkyc.to/knowledge-base/accept-crypto/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](https://withoutkyc.to/knowledge-base/wallet-setup/xrp-wallet-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](https://withoutkyc.to/knowledge-base/developers/verify-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](https://withoutkyc.to/knowledge-base/developers/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.

> **XRP is live in every [PayGate.to crypto plugin](https://withoutkyc.to/crypto-payment-gateway-no-kyc-instant-payouts/) and the [crypto API](https://withoutkyc.to/docs/crypto-payment-api/).**

## 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.
