PayerURL API Documentation

Authentication #authentication

How it works

All API requests require your api_key and api_secret sent as HTTP headers. Never expose your secret in client-side code.

Base URL https://api.payerurl.com/api/v2

O-PublicKey

Your API Key (public)
Found in your PayerURL Dashboard → API Settings. Safe to log, not to share publicly.

O-SecretKey

Your API Secret (private)
Used for HMAC-SHA256 signature on every request. Never expose in frontend code.

EXAMPLE REQUEST HEADERS

# Required headers for every API call
O-PublicKey: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
O-SecretKey: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

SDKs & Libraries #sdks

🐍

Python

binance-and-crypto-payment

pip install binance-and-crypto-payment

🐘

PHP

payerurl/payerurl-php

composer require payerurl/php

🟨

Node.js

payerurl-node

npm install payerurl-node

🔷

Go

github.com/payerurl/go-sdk

go get github.com/payerurl/go

🛒

WooCommerce

payerurl-woocommerce

WordPress Plugin

🛍️

Shopify

payerurl-shopify

PHP Bridge

Create Payment #create-payment

POST /api/v2/payment/create Initiate a new crypto payment

Parameter	Type	Required	Description
order_id	string	required	Your unique order identifier
amount	float	required	Payment amount in `currency` units (e.g. 29.99)
currency	string	required	Fiat currency for the invoice amount (USD, EUR, JPY…)
coin	string	required	Crypto to receive. E.g. `BTC`, `ETH`, `USDT_TRC20`
success_url	string	required	Redirect URL after successful payment
cancel_url	string	required	Redirect URL when buyer cancels
webhook_url	string	optional	POST callback URL for payment status updates
buyer_name	string	optional	Customer's name for the payment page
buyer_email	string	optional	Customer's email for receipt delivery
notes	string	optional	Internal notes or order description

CURL

curl -X POST https://api.payerurl.com/api/v2/payment/create \
  -H "O-PublicKey: pk_live_xxxxxx" \
  -H "O-SecretKey: sk_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-20240608-001",
    "amount": 29.99,
    "currency": "USD",
    "coin": "USDT_TRC20",
    "success_url": "https://yoursite.com/payment/success",
    "cancel_url": "https://yoursite.com/payment/cancel",
    "webhook_url": "https://yoursite.com/webhook/payerurl",
    "buyer_name": "Md Muhit",
    "buyer_email": "user@example.com"
  }'

PHP

// composer require payerurl/php
$client = new PayerURL\Client([
    'api_key'    => 'pk_live_xxxxxx',
    'api_secret' => 'sk_live_xxxxxx',
]);

$payment = $client->payment()->create([
    'order_id'    => 'ORD-20240608-001',
    'amount'      => 29.99,
    'currency'    => 'USD',
    'coin'        => 'USDT_TRC20',
    'success_url' => 'https://yoursite.com/payment/success',
    'cancel_url'  => 'https://yoursite.com/payment/cancel',
    'webhook_url' => 'https://yoursite.com/webhook/payerurl',
]);

// Redirect buyer to payment page
header('Location: ' . $payment['data']['redirect_url']);
exit();

PYTHON

# pip install binance-and-crypto-payment
from payerurl import PayerURLClient

client = PayerURLClient(
    api_key="pk_live_xxxxxx",
    api_secret="sk_live_xxxxxx"
)

payment = client.payment.create(
    order_id="ORD-20240608-001",
    amount=29.99,
    currency="USD",
    coin="USDT_TRC20",
    success_url="https://yoursite.com/payment/success",
    cancel_url="https://yoursite.com/payment/cancel",
    webhook_url="https://yoursite.com/webhook/payerurl",
)

# Redirect buyer
redirect_url = payment["data"]["redirect_url"]

NODE.JS

// npm install payerurl-node
const { PayerURL } = require('payerurl-node');

const client = new PayerURL({
  apiKey:    'pk_live_xxxxxx',
  apiSecret: 'sk_live_xxxxxx',
});

const payment = await client.payment.create({
  order_id:    'ORD-20240608-001',
  amount:      29.99,
  currency:    'USD',
  coin:        'USDT_TRC20',
  success_url: 'https://yoursite.com/payment/success',
  cancel_url:  'https://yoursite.com/payment/cancel',
  webhook_url: 'https://yoursite.com/webhook/payerurl',
});

const { redirect_url } = payment.data;
// res.redirect(redirect_url)

200 OK

JSON RESPONSE

{
  "status": 1,
  "message": "Payment created successfully",
  "data": {
    "payment_id":    "pymt_3xK9mZ7qAbCdEfGh",
    "order_id":     "ORD-20240608-001",
    "amount":       29.99,
    "currency":     "USD",
    "coin":         "USDT_TRC20",
    "coin_amount":  "29.99",
    "wallet":       "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "redirect_url": "https://pay.payerurl.com/p/pymt_3xK9mZ7qAbCdEfGh",
    "status":       "pending",
    "expires_at":   "2024-06-08T13:30:00Z",
    "created_at":   "2024-06-08T13:00:00Z"
  }
}

Get Payment Status #get-payment

GET /api/v2/payment/status/{payment_id} Fetch current payment state

CURL

curl -X GET https://api.payerurl.com/api/v2/payment/status/pymt_3xK9mZ7qAbCdEfGh \
  -H "O-PublicKey: pk_live_xxxxxx" \
  -H "O-SecretKey: sk_live_xxxxxx"

JSON RESPONSE

{
  "status": 1,
  "data": {
    "payment_id":   "pymt_3xK9mZ7qAbCdEfGh",
    "order_id":    "ORD-20240608-001",
    "amount":      29.99,
    "coin_amount": "29.99",
    "coin":        "USDT_TRC20",
    "status":      "completed",
    "tx_hash":     "c3ab8ff13720e8ad9047dd39466b3c8974e592c2...",
    "confirmations": 21,
    "paid_at":     "2024-06-08T13:12:45Z"
  }
}

Payment Status Values

pending confirming completed expired cancelled underpaid

Webhook Events #webhooks

01

Buyer pays

Customer sends crypto to the generated wallet address

02

PayerURL detects

Network confirmations tracked; status updated automatically

03

Webhook fired

POST request sent to your webhook_url with HMAC signature

WEBHOOK PAYLOAD

{
  "payment_id":   "pymt_3xK9mZ7qAbCdEfGh",
  "order_id":    "ORD-20240608-001",
  "status":      "completed",
  "amount":      "29.99",
  "currency":    "USD",
  "coin":        "USDT_TRC20",
  "coin_amount": "29.99",
  "tx_hash":     "c3ab8ff13720e8ad9047dd39466b3c8974e592c2...",
  "wallet":      "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "signature":   "a8b3c2d4e5f6...",
  "timestamp":   1717844565
}

HMAC Signature Verification #webhook-verify

⚠ Security requirement

Always verify the HMAC signature before processing any webhook. Reject requests with invalid or missing signatures.

1

Collect fields. Concatenate payment_id + order_id + amount + timestamp with pipe delimiters.

2

Generate HMAC-SHA256. Sign the concatenated string using your api_secret as the key.

3

Compare signatures. Use a constant-time comparison. If they don't match, return 401 and ignore the payload.

PHP — HMAC VERIFICATION

$payload   = file_get_contents('php://input');
$data      = json_decode($payload, true);
$apiSecret = 'sk_live_xxxxxx';

// Build the signature string
$sigStr = implode('|', [
    $data['payment_id'],
    $data['order_id'],
    $data['amount'],
    $data['timestamp'],
]);

$expected = hash_hmac('sha256', $sigStr, $apiSecret);

if (!hash_equals($expected, $data['signature'])) {
    http_response_code(401);
    exit('Invalid signature');
}

// Safe to process
if ($data['status'] === 'completed') {
    // Fulfil order $data['order_id']
}

Supported Cryptocurrencies #currencies

BTC

Bitcoin

ETH

Ethereum

TRC

USDT_TRC20

USDT Tron

ERC

USDT_ERC20

USDT Ethereum

USDC

USD Coin

BNB

BNB Chain

LTC

Litecoin

TRX

TRON

TON

The Open Network

Error Codes #errors

400

INVALID_PARAMS

Missing or malformed request parameters

401

AUTH_FAILED

Invalid API key or secret, or HMAC mismatch

404

NOT_FOUND

Payment ID does not exist for this account

409

DUPLICATE_ORDER

A payment with this order_id already exists

422

COIN_UNSUPPORTED

Requested cryptocurrency is not supported or disabled

429

RATE_LIMITED

Too many requests. Limit: 120 req/min per API key

500

SERVER_ERROR

Internal error. Retry with exponential backoff

ERROR RESPONSE FORMAT

{
  "status":  0,
  "error":   "INVALID_PARAMS",
  "message": "The 'coin' field is required",
  "code":    400
}

Build crypto paymentswithout the complexity

Build crypto payments
without the complexity