API Integration Overview

Environments

3PAY provides two separate environments:

Sandbox (Staging)

Use for testing and integration.

• Dashboard: https://sandbox.3pa-y.com/
• Uses testnets (e.g., Sepolia for ERC20, Nile for TRC20)
• Sandbox API keys and webhooks are separate from live

Live (Production)

Use for real transactions.

• Dashboard: https://dashboard.3pa-y.com
• Uses mainnet networks
• Requires verification (KYC/KYB) before processing live flows

⚠️

Sandbox and live data do not carry over. Treat them as two separate systems.

Authentication

3PAY API requests are authenticated using API keys.

• Generate your Sandbox API keys from the sandbox dashboard
• Generate your Live API keys from the live dashboard
• Store keys securely (server-side only)

API Reference link placeholder: Authentication / API Keys

Core integration models

3PAY supports two primary acceptance models. Your integration will typically follow one of these:

1) Invoice-based payments (one-time transactions)

Use when you want a single payment request per transaction (e.g., checkout / pay-by-link).

High-level flow:

1. Create invoice
2. Present payment instructions to customer
3. Listen for webhook events and/or poll invoice status
4. Mark order as paid once successful

API Reference link placeholders: Create Invoice, Get Invoice, Invoice Webhooks

2) Per-user wallet payments (persistent balances)

Use when you want one wallet per user and deposits that accumulate into a balance (e.g., platforms, brokers).

High-level flow:

1. Create user (requires userId and email)
2. Retrieve wallet details (address)
3. User deposits to their wallet address
4. Retrieve wallet balance and/or consume webhook events

API Reference link placeholders: Create User, Get Wallet Details, Get Wallet Balance, Wallet Webhooks

Webhooks

Webhooks are the recommended way to keep your system in sync with 3PAY without polling.

Best practices:

• Configure webhooks separately for sandbox and live
• Verify webhook authenticity (signature verification recommended)
• Treat webhook delivery as at-least-once (handle duplicates safely)
• Persist webhook events for audit/debugging

Idempotency & safe retries

When creating invoices or withdrawal requests, your system should be resilient to network retries.

Recommended practices:

• Do not create duplicate invoices/withdrawals on retry
• Log request IDs and responses

Status & reconciliation

Every successful on-chain transaction includes a transaction hash, visible in the dashboard when viewing the transaction record.

Recommended practices:

• Use the transaction hash as the on-chain reference for audits and disputes
• Only treat payments as final when marked Successful
• Use webhooks + API queries for reconciliation when needed

API Reference link placeholders: Transaction object / Payment status fields

Errors & rate limits

Your integration should be designed to handle:

• Validation errors (bad input)
• Authentication errors (invalid key)
• Network mismatch errors (ERC20 vs TRC20)
• Temporary errors (retry with backoff)

If rate limits exist, implement:

• Exponential backoff
• Request batching where possible

API Reference link placeholders: Error Format, Rate Limits (if applicable)

Security checklist

Before going live:

• Keep API keys server-side
• Enable 2FA for dashboard users
• Restrict dashboard access via roles (where available)
• Validate destination addresses for withdrawals/payouts
• Educate end users: wrong wallet address/network is irreversible