Payment Integration

Payment Integration

This guide explains how to integrate 3PAY payments end-to-end. 3PAY supports two payment integration models:

1. Invoice payments (one-time transactions)
2. Per-user wallets (persistent balances)

Choose the model that matches your product, then follow the corresponding flow below.

Choose your payment model

Use Invoice Payments if you need:

• One payment request per transaction (checkout, pay-by-link)
• Per-transaction reconciliation (invoice ID)
• Clear “created → successful” lifecycle per order

Use Per-User Wallets if you need:

• One wallet per user (platforms, brokers)
• Users can deposit multiple times into a persistent balance
• Balance-based product experience (account funding)

A) Invoice Payment Integration (recommended for checkout)

Flow overview

1. Create invoice
2. Show payment instructions to the customer
3. Track status via webhooks (recommended) and/or polling
4. Mark order as paid once the invoice becomes Successful
5. (Optional) Handle late payments / wrong invoice via support process

Step 1 — Create the invoice

From your backend, create an invoice with:

• amount
• asset (e.g., USDT)
• network (ERC20 / TRC20)
• metadata (orderId, customerId, etc.)`

Step 2 — Present payment instructions

Return invoice details to your frontend or checkout UI.

Your UI should clearly display:

• Amount
• Asset and network (explicitly)
• Destination address (invoice address)
• Invoice reference (invoice ID)
• Expiry behavior (if applicable)

⚠️

Always show the network (ERC20 vs TRC20). Sending on the wrong network may result in failed or delayed processing.

Step 3 — Track payment status (webhooks recommended)

Configure webhooks to receive invoice/payment events and update your order state.

Recommended approach:

• Treat webhooks as the primary mechanism
• Use polling only as a fallback (e.g., UI refresh)

Integration behavior:

• When status is Initiated, show “Waiting for confirmations”
• When status is Successful, finalize the order and grant access

Step 4 — Reconcile and finalize

When the invoice becomes Successful:

• Mark the order as paid

• Store:

  • invoiceId
  • transaction hash (if included/available)
  • amount/asset/network
  • timestamps

For audits, the transaction hash can be verified from the dashboard.

Step 5 — Handle wrong-invoice payments

If a user pays an old invoice by mistake, 3PAY may be able to recover the payment if it was sent to an invoice address under 3PAY control.

Route these cases to support with:

• invoiceId (paid)
• transaction hash
• amount/network

B) Per-User Wallet Integration (recommended for platforms/brokers)

Flow overview

1. Create user (requires userId and email)
2. Fetch wallet details (address + network)
3. User deposits to their wallet address
4. Track deposit status via webhooks and/or balance queries
5. Use wallet balance inside your product (funding, trading, etc.)

Step 1 — Create the user

Create a 3PAY user mapped to your internal user record.

Required fields:

• userId (string, required)
• email (string, required)

Optional:

• phone, firstName, lastName, description

Step 2 — Retrieve wallet details

Retrieve the user’s wallet details to obtain the deposit address.`

Step 3 — Display deposit instructions

Your UI should display:

• Wallet address
• Network (ERC20 vs TRC20)
• Asset (USDT)
• Warnings about wrong address/network irreversibility

⚠️

3PAY is not liable for end-user mistakes such as incorrect wallet addresses or wrong networks.

Step 4 — Track deposits

Recommended:

• Use webhooks for deposit events
• Use Get Wallet Balance for UI refresh and reconciliation

Only treat the deposit as final when marked Successful or confirmed.

Step 5 — Use the balance in your product

Once deposits are successful:

• Credit the user’s internal balance / account
• Allow product actions (fund trading account, unlock features, etc.)
• Record transaction references for audit