Skip to main content
This guide explains how to fund a customer’s embedded wallet using Pepay invoices. When a payment succeeds, Pepay settles into your preferred settlement token and deposits that token to the customer’s wallet address (pass-through settlement).

​
Use cases

  • In-app balance top-ups
  • Marketplace escrow or buyer credits
  • Game currency funding
  • Wallet-based receipts or loyalty programs
  • Embedded commerce balances (prepaid funds)

​
How it works (client perspective)

  1. Your app creates or retrieves the customer’s embedded wallet address.
  2. You create a Pepay invoice with a receiver override pointing to that wallet.
  3. The customer pays the invoice using any supported token.
  4. Pepay settles the payment into your preferred settlement token and deposits it to the wallet address you provided.
  5. You confirm the deposit via invoice events and credit the user’s in-app balance.
Key implications:
  • The deposit asset is always your settlement token (not necessarily the payor’s token).
  • The settlement network is derived from your settlement token (wallet must support that chain).
  • Your app should display a consistent “deposit asset” to avoid confusion.

​
Prerequisites

  • Pepay dashboard access
  • A merchant API key (scope=merchant)
  • An embedded wallet provider (you control wallet creation + address management)
  • A backend service to create invoices and process events
Base URL for examples: https://api-beta.pepay.io

​
Step 1 - Set your settlement token

Pick the token you want deposits to arrive in (for example, USD1 on BSC). This is configured in the dashboard under settlement preferences. The settlement token determines:
  • Which chain the deposit arrives on
  • Which asset the wallet receives

​
Step 2 - Create or fetch the customer wallet

Use your embedded wallet provider to create a wallet and store:
  • customer_id (your ID)
  • wallet_address (customer’s wallet)
  • wallet_network (derived from the settlement token’s chain)
Make sure the wallet supports the settlement token’s chain.

​
Step 3 - Create an invoice with a receiver override

Pass the customer’s wallet address as a receiver override so the settlement deposit goes to their wallet. 
BASE_URL=https://api-beta.pepay.io

curl -X POST "$BASE_URL/api/v1/invoices" \
  -H "x-api-key: <merchant_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 25.00,
    "description": "Wallet top-up",
    "customer_id": "cust_123",
    "receiver_override_enable": true,
    "receiver_override_address": "0x1111111111111111111111111111111111111111"
  }'
Notes:
  • The settlement network is derived from your configured settlement token.
  • The wallet address must live on that network.

​
Step 4 - Present checkout

Use payment_url to show hosted checkout, or embed the session using payor endpoints with:
  • x-session-token
  • x-signature

​
Step 5 - Confirm settlement and credit balance

Listen for:
  • invoice.updated
  • invoice_payment.updated
When the invoice reaches a terminal paid state, credit the user’s balance in your app. Use invoice_id for reconciliation and a monotonic event cursor for idempotency.

​
Step 6 - Post-deposit UX

Show the user:
  • Amount credited (settlement token amount)
  • Settlement token symbol + chain
  • Invoice ID / receipt link

​
Integration checklist

  • Settlement token configured in dashboard
  • Embedded wallet addresses stored per customer
  • Invoices created with receiver override enabled
  • Checkout UI wired to payment_url or payor session headers
  • Webhook or WebSocket handlers for paid events
  • Balance crediting + idempotency implemented

​
SDK references

If you want help or a review of your embedded wallet flow, reach out at [email protected].