Merchant Login Get Started
⚡ Developer Hub & API Docs

Build Multi-Chain Crypto Payments

Integrate seamless non-custodial crypto checkout using host prompt modals or direct API redirects with full sandbox testnet support.

1. Overview

TwinkPay gateway empowers merchants to accept USDT, USDC, BNB, TRX, and Native Cryptocurrencies across BSC, TRON, and Ethereum with zero exact-cut merchant fees and instant auto-payouts.

🚀 Quick Start Summary

  1. Generate a Sandbox API Key or Live API Key from your Merchant Portal.
  2. Call our API endpoint POST /api/payments/orders to create a payment order.
  3. Redirect the customer to the returned checkout_url.
  4. Listen to instant status updates via Webhooks.

2. Sandbox & Testnet Testing

Every merchant gets free access to test integration on BSC Testnet & TRON Nile Testnet without spending real crypto.

1 Sandbox API Key

Use your sandbox API key in request headers for all testnet interactions:

Authorization: Bearer sandbox_sample_key_12389

2 Test Coins & Faucets

Get testnet coins instantly for scanning and sweeper simulation:

3. Authentication

Authenticate all REST API requests by passing your Merchant API key in the HTTP Authorization header or X-API-KEY header:

Authorization: Bearer YOUR_LIVE_OR_SANDBOX_API_KEY

Alternative header format:

X-API-KEY: YOUR_LIVE_OR_SANDBOX_API_KEY

4. Hosted Redirect Checkout (Recommended Default)

Redirect your customer cleanly to the hosted checkout page. Once payment is confirmed or cancelled, the customer will automatically be redirected back to your success_url or cancel_url.

Javascript / Vue / React Integration:

// 1. Create order on your backend and retrieve checkout_url const res = await fetch('/api/create-order', { method: 'POST' }); const data = await res.json(); // 2. Simple full-page redirection (Best user experience across all devices) window.location.href = data.checkout_url;

PHP / Server-Side Integration:

// Direct server header redirect header('Location: ' . $orderData['checkout_url']); exit;

5. Create Payment Order

Generates an order and reserves a dedicated temporary deposit address with frozen exchange rate snapshot.

POST /api/payments/orders

Request Headers:

Authorization: Bearer YOUR_API_KEY Content-Type: application/json Accept: application/json

Request Payload:

{ "amount": 50.00, "currency": "USDT_BEP20", "customer_email": "[email protected]" }

Response (201 Created):

{ "success": true, "data": { "order_id": "ORD-992384712", "amount": "50.000000", "currency": "USDT_BEP20", "chain": "BSC", "deposit_address": "0x5E64A528783088f73158E09a9ce85fe9F8AbED37", "status": "pending", "checkout_url": "https://twinkpay.org/checkout/ORD-992384712", "expires_at": "2026-09-27T16:30:00.000000Z" } }

6. Webhooks

TwinkPay delivers secure HTTP POST webhook notifications directly to your server when transactions are confirmed on-chain.

{ "event": "order.paid", "order_id": "ORD-992384712", "amount": "50.000000", "currency": "USDT_BEP20", "tx_hash": "0xe8684aa299a6f434263d021123978d53f0ddd20fdcc3984b7d5412ef55c42a64", "confirmed_at": "2026-09-27T15:05:12.000000Z" }

7. Troubleshooting: 401 Unauthenticated Error

🚨 Error: {"message": "Unauthenticated."} (401)

If your backend receives a 401 Unauthenticated response when attempting to create an order:

  • Wrong Endpoint URL: Ensure your request is posted to /api/payments/orders (API Key authentication). Calling /api/v1/orders uses Sanctum Session auth and will fail with 401.
  • Missing Authorization Header: Ensure your request header contains Authorization: Bearer YOUR_API_KEY or X-API-KEY: YOUR_API_KEY.
  • Active Subscription Status: If using a Live API Key, ensure your merchant account has an active subscription. If using a Sandbox API Key, check that your registered domain matches your site domain.