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

Accept crypto payments in PHP (paygate-php)

A complete, tested PHP example: create a payment address, show amount and QR code, or use the hosted checkout, then verify the signed callback with paygate-php.

3 min readUpdated Intermediate
On this page
  1. Install
  2. Option A: payment address and QR code on your page
  3. Option B: hosted multi-coin checkout
  4. The callback handler
  5. Framework requests
  6. Frequently asked questions

The official paygate-php SDK wraps the PayGate.to crypto API: create payment addresses, convert amounts, generate QR codes, build hosted checkouts and verify signed callbacks. It needs PHP 7.4+ with ext-json and ext-openssl, and nothing else. Full reference: PHP SDK docs.

Install

bash
composer require paygate-to/paygate-php

Option A: payment address and QR code on your page

php
<?php
require 'vendor/autoload.php';

use PayGate\Callback\CallbackToken;

$paygate = new PayGate\Client();
$tokens  = new CallbackToken(getenv('PAYGATE_CALLBACK_SECRET'));   // 64 random hex chars, kept on your server

$orderId  = '1001';
$callback = $tokens->callbackUrl('https://shop.example8585859.com/paygate/callback.php', ['order' => $orderId]);

$crypto = $paygate->crypto();
$wallet = $crypto->createWallet('trc20_usdt', 'TYourTronAddress', $callback);
$quote  = $crypto->convert('trc20_usdt', '49.90', 'USD');
$qr     = $crypto->qrCode('trc20_usdt', $wallet->getAddressIn(), $quote['value']);

echo 'Send ', $quote['value'], ' USDT (TRC20) to ', htmlspecialchars($wallet->getAddressIn());
echo '<img src="', $qr['data_uri'], '" alt="Payment QR code">';
  • Coins can be written trc20_usdt or trc20/usdt. Use a payout wallet on that coin's network.
  • Save $wallet->getAddressIn() with the order, and the amount you expect.
  • Options: ['pending' => true] for an extra callback when the payment is first seen, ['confirmations' => 3] for more confirmations.

Option B: hosted multi-coin checkout

php
$hosted = $paygate->crypto()->createHostedWallet([
    'evm'    => '0xYourEvmWallet',
    'btc'    => 'bc1qYourBitcoinWallet',
    'xmr'    => '8YourMoneroSubaddress',
    'xrp'    => 'rYourXrpAddress',
], '49.90', 'USD', $callback);

header('Location: ' . $paygate->crypto()->hostedPaymentUrl($hosted, true /* customer pays the network fee */));

Networks: evm, btc, bitcoincash, ltc, doge, solana, trc20, xmr, zec, ton, xrp. See Build a hosted multi-coin checkout.

The callback handler

php
<?php
require 'vendor/autoload.php';

use PayGate\Callback\CallbackData;
use PayGate\Callback\CallbackToken;

$paygate = new PayGate\Client();
$tokens  = new CallbackToken(getenv('PAYGATE_CALLBACK_SECRET'));

// 1. Signature over YOUR registered URL + the raw query string, as received
$result = $paygate->callbacks()->verifyRequest('https://shop.example8585859.com/paygate/callback.php');
if (!$result->isValid()) { http_response_code(403); exit; }

$data = CallbackData::fromRequest();

// 2. The order reference was issued by your server
if (!$tokens->verify($data->get('order'), $data->get('token'))) { http_response_code(403); exit; }

// 3. Pending notifications (if enabled): don't ship
if ($data->isPending()) { exit('ok'); }

// 4. Credit each blockchain transaction once
$order = findOrder($data->get('order'));
if ($order->hasTransaction($data->getTxidIn())) { exit('ok'); }
$order->addPayment($data->getTxidIn(), $data->getCoin(), $data->getValueCoin());

// 5. Right coin, enough of it, and paid out to YOUR wallet
$toMe = $data->getPayoutFor('TYourTronAddress');
$paid = $toMe !== null && (float) $order->receivedTotal() >= 0.98 * (float) $order->expectedCoin;
$order->setStatus($paid ? 'paid' : 'underpaid');

echo 'ok';

Why each step matters is explained in Verify PayGate.to callback signatures. Reply with plain ok to stop repeat notifications.

Framework requests

If your framework gives you a request object, pass the raw query string:

php
$result = $paygate->callbacks()->verify(
    'https://shop.example8585859.com/paygate/callback.php',
    $request->server->get('QUERY_STRING'),           // raw, undecoded
    $request->headers->get('X-PayGate-Signature'),
    $request->headers->get('X-PayGate-Key-Id')
);

Don't use helpers that sort or re-encode the query: one changed byte breaks the signature. On Laravel, use the Laravel package instead.

Frequently asked questions

Does the SDK need cURL?

No. It uses cURL when available and PHP streams otherwise.

How do I test callbacks locally?

Expose a local server with a tunnel and create a wallet with that public callback URL, or sign test requests with your own key in your test suite. Never ship test keys.

Can I accept XRP with a destination tag?

Yes: pass rYourAddress?dt=777 (or an X-address) as the wallet. getPayoutFor() accepts your wallet in any of those forms. See XRP payment API.

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