Integration Guide
A comprehensive developer guide for integrating Hashpay crypto payment gateway: server-side order creation, hosted checkout and direct API flows, mobile webview deep linking, webhook handling, and production launch.
Choose your integration path
Hashpay offers two primary integration models tailored to your business architecture and user experience requirements:
| Integration Path | Best For | Implementation Effort |
|---|---|---|
| Hosted Payment Page (Webview) | Web e-commerce, mobile apps (Flutter, React Native, iOS, Android), and POS terminals. Hashpay manages token selection, wallet connections, live rate locking, and dynamic QR display. | 1 server API call + redirect or webview modal |
| Direct API (Custom In-App UI) | Merchants requiring 100% white-label checkout screens inside their own native application or checkout flow. You design the UI while Hashpay provides rate locking and on-chain verification. | 4 server API calls + custom front-end UI |
Environment matrix & base URLs
Hashpay maintains strict isolation between Sandbox (Testnet) and Production (Mainnet). Ensure your backend client uses the appropriate base URL and API keys:
| Parameter | Sandbox (Testnet) | Production (Mainnet) |
|---|---|---|
| Base API URL | https://api.hashpay.id/v2/testnet | https://api.hashpay.id/v2/mainnet |
| Hosted Checkout URL | https://webview.hashpay.id/sandbox | https://webview.hashpay.id |
| Supported Blockchains | Ethereum (Sepolia), BNB Chain (Testnet), Tron (Shasta), Solana (Devnet) | Ethereum, BNB Chain, Tron, Solana |
| Settlement Assets | USDT & USDC (Testnet Faucet) | USDT & USDC (Real Mainnet Assets) |
| API Credentials | Testnet Secret Key (sec_test_...) | Mainnet Secret Key (sec_live_...) |
End-to-end integration phases
- Order Creation & Rate Quotation — Your server verifies order limits, creates an order via
POST /merchant/fiat/order, and receives a hosted checkout session URL (data.url) and scoped key. - Front-End Presentation — Deliver the payment interface to the buyer: open the hosted page via browser redirect, iframe, or mobile in-app webview; or render custom QR codes via Direct API.
- Blockchain Monitoring & Rate Lock — Hashpay locks the real-time crypto exchange rate for 15 minutes. Our real-time node watchers detect incoming blockchain transfers within 2 to 5 seconds.
- Webhook Notification & Fulfillment — Once required block confirmations are reached, Hashpay sends a cryptographically signed HTTP POST webhook (
transaction.success) to your server. Your server verifies the signature and fulfills the customer order. - Reconciliation & Settlement — Funds are automatically swept to your business settlement address or paid out directly to local Indonesian bank accounts.