Paynch Button v2.2.0 - Official Documentation

📦 Quick Installation

Paste this HTML code where you want the payment button to appear:

<script src="https://pay.paynch.io/js/button35.js"
  data-shop="0xE5fF9d546278a7CE0DF261EB85945Df2F0Dcc3c6"
  data-amount="15.00"
  data-order-id="order-123"
  data-product-name="Premium Access"
  data-redirect="https://yourstore.com/thank-you"
  data-theme="light"
  data-language="en"
  data-currency="USDT"
  data-dev-mode="false">
</script>

✨ Done! With just this one line of code, you have a complete crypto payment system with automatic verification and responsive design.

⚙️ Configuration Parameters

Required Parameters

Parameter	Type	Description	Example
`data-shop` Required	String	Store contract address (Ethereum address)	`0xE5fF9d546278a7CE0DF261EB85945Df2F0Dcc3c6` (address created in your dashboard)
`data-amount` Required	Number	Amount in USDT (use dot as decimal separator)	`15.00` or `99.90`
`data-order-id` Required	String	Unique order ID (must be different for each transaction)	`order-123`, `ORD_abc456` (ID generated and saved in your database for each order/checkout)
`data-redirect` Optional for confirmation	URL	Create the confirmation file to integrate with your system	Redirect URL after successful payment confirmation

Optional Parameters

Parameter	Type	Default	Description
`data-product-name` Optional	String	`"Product"`	Product name displayed in the widget
`data-theme` Optional	String	`"default"`	Visual theme: `default`, `dark`, `light`
`data-language` Optional	String	`"en"`	Language: `en`, `pt-BR`, `es`
`data-currency` Optional	String	`"USDT"`	Token payment SYMBOL (If you use your own token to receive payments, you need to enter its symbol)
`data-dev-mode` Optional	Boolean	`false`	Development mode (simulates transactions)
`data-script-path` Optional	URL	`null`	Custom script path for payments

📝 Practical Examples

Example 1: Static HTML

<!DOCTYPE html>
<html>
  <head>
    <title>My Store</title>
  </head>
  <body>
    <h1>Premium Product</h1>
    <script
      src="https://pay.paynch.io/js/button35.js"
      data-shop="0xE5fF9d546278a7CE0DF261EB85945Df2F0Dcc3c6"
      data-amount="25.00"
      data-order-id="order-456"
      data-product-name="Premium Product"
      data-theme="light"
      data-language="en"
      data-currency="USDT"
      data-dev-mode="false">
    </script>
  </body>
</html>

Example 2: Dynamic PHP

<?php
// Product settings
$product = [
  'name' => 'Complete Web3 Course',
  'price' => 99.90
];
// Generate unique ID (store in database for later validation)
$orderId = uniqid('order_');
// Paynch config
$paynchConfig = [
  'contract' => '0xE5fF9d546278a7CE0DF261EB85945Df2F0Dcc3c6',
  'redirectUrl' => 'https://mystor.com/thank-you'
];
?>
<!-- Paynch Button -->
<script
  src="https://pay.paynch.io/js/button35.js"
  data-shop="<?= htmlspecialchars($paynchConfig['contract']) ?>"
  data-amount="<?= number_format($product['price'], 2, '.', '') ?>"
  data-order-id="<?= htmlspecialchars($orderId) ?>"
  data-product-name="<?= htmlspecialchars($product['name']) ?>"
  data-redirect="<?= $paynchConfig['redirectUrl'] ?>?orderId=<?= urlencode($orderId) ?>"
  data-theme="light"
  data-language="en"
  data-currency="USDT"
  data-dev-mode="false">
</script>

Example 3: Full E-commerce (PHP + MySQL)

<?php
// Connect to database
$pdo = new PDO(
  'mysql:host=localhost;dbname=store',
  'user',
  'pass'
);
// Fetch product
$productId = $_GET['id'] ?? 1;
$stmt = $pdo->prepare(
  "SELECT * FROM products WHERE id = ?"
);
$stmt->execute([$productId]);
$product = $stmt->fetch();
// Create order
$orderId = 'ORD' . time() . rand(1000, 9999);
$stmt = $pdo->prepare(
  "INSERT INTO orders (order_id, product_id, value, status)
   VALUES (?, ?, ?, 'pending')"
);
$stmt->execute([
  $orderId,
  $product['id'],
  $product['price']
]);
?>
<!-- Paynch Button -->
<script
  src="https://pay.paynch.io/js/button35.js"
  data-shop="<?= htmlspecialchars($paynchConfig['contract']) ?>"
  data-amount="<?= number_format($product['price'], 2, '.', '') ?>"
  data-order-id="<?= htmlspecialchars($orderId) ?>"
  data-product-name="<?= htmlspecialchars($product['name']) ?>"
  data-redirect="<?= $paynchConfig['redirectUrl'] ?>?orderId=<?= urlencode($orderId) ?>"
  data-theme="light"
  data-language="en"
  data-currency="USDT"
  data-dev-mode="false">
</script>

🎨 Visual Themes

The Paynch Button offers 3 pre-configured themes:

Default

Vibrant modern purple

data-theme="default"

Dark

Elegant dark mode

data-theme="dark"

Light

Clean minimalist light

data-theme="light"

💡 Tip: Choose the theme that best matches your website design. All are 100% responsive!

✨ Features

⚡ Zero Configuration

Just one line of code. No imports, no complex setup.

🔄 Retry Logic

Smart fallback system with multiple script paths.

🔍 Automatic Verification

Monitors the blockchain every 3 seconds until payment is confirmed.

📱 100% Responsive

Works perfectly on desktop, tablet, and mobile.

🌍 Multi-language

Native support for English (EN), Portuguese (PT-BR) and Spanish (ES).

🎨 3 Ready Themes

Default, Dark, and Light – pick the one that fits your site.

🛡️ Security & Best Practices

Order ID Validation

❌ DON'T DO: Predictable or duplicate IDs

                    $orderId = "order-1"; // VERY BAD!
$orderId = $_GET['id']; // INSECURE!
                

✅ DO: Unique and unpredictable IDs

                    // Good
$orderId = uniqid('ORD_', true);
// Excellent!
$orderId = 'ORD_' . time() . '_' . bin2hex(random_bytes(8));
                

Backend Validation (ESSENTIAL!)

Always validate the payment on the server before releasing the product:

<?php
// Confirmation page (thank-you.php)
$orderId = $_GET['orderId'] ?? null;
if (!$orderId) {
  die('Invalid Order ID');
}
// Query Paynch API
$paynchApi = 'https://api.paynch.io/paynch.php';
$contract = '0xE5fF9d546278a7CE0DF261EB85945Df2F0Dcc3c6';
$response = file_get_contents(
  "$paynchApi?contract=$contract&orderId=$orderId"
);
$data = json_decode($response, true);
if ($data['success'] === true && $data['count'] > 0) {
  // ✅ PAYMENT CONFIRMED!
  $pdo->prepare(
    "UPDATE orders
     SET status = 'paid'
     WHERE order_id = ?"
  )->execute([$orderId]);
  echo '✅ Payment confirmed!';
} else {
  echo '⏳ Waiting for confirmation...';
}
?>

Data Escaping (XSS Prevention)

// 🔐 SEMPRE use htmlspecialchars() para valores HTML
data-shop="<?= htmlspecialchars($paynchConfig['contract']) ?>"
data-order-id="<?= htmlspecialchars($orderId) ?>"
data-product-name="<?= htmlspecialchars($produto['nome']) ?>"

// 🌐 Para URLs, use urlencode()
data-redirect="<?= $baseUrl ?>?orderId=<?= urlencode($orderId) ?>"

⚠️ IMPORTANT: Always use dot (.) as decimal separator in data-amount:

✅ Correct: data-amount="15.00"
❌ Wrong: data-amount="15,00"

🚨 Troubleshooting

Problem: Button doesn't appear

Solution:

Check if all 3 required parameters are present (data-shop, data-amount, data-order-id)
Open browser console (F12) and look for errors
Verify the script URL is correct

Problem: Payment not detected

Solution:

Wait up to 10 minutes (200 checks × 3 seconds)
Verify the Order ID is correct
Confirm the transaction was sent to the correct contract
Get the order ID (passed as 'orderid' in URL) and check in the dashboard
Manually query the API: https://api.paynch.io/paynch.php?contract=...&orderId=...

Problem: Incorrect amount format

Common error: Using comma (,) in data-amount

✅ Correct: data-amount=""
❌ Wrong: data-amount=""

Use our AI if you need help

💬 Need Help? Our AI is available 24/7 to answer your integration and troubleshooting questions.
Open AI Support Chat

✅ Production Checklist

Before going live, verify:

Tested in data-dev-mode="true"
Validated all required parameters
Generated unique & unpredictable Order IDs
Implemented backend validation (essential!)
Tested full flow with real transaction
Configured redirect page
Escaped all dynamic data (XSS)
Formatted amounts with dot decimal
Tested on mobile and desktop
Set data-dev-mode="false"
Documented the contract used
Configured logs and monitoring