Skip to main content
BettaPay Logo
BettaPay
All guides
Beginnertestnetfreighterfriendbot

Testing with Stellar Testnet

Build a safe development loop with Freighter, friendbot, test USDC, and the Stellar Laboratory.

BettaPay TeamUpdated Jul 19, 202610 min read

The Stellar testnet is a full copy of the network that uses valueless tokens, so you can build and test payment flows without risking real money. This guide sets up a repeatable development loop: install Freighter, switch to testnet, fund an account with friendbot, get test USDC, run a full BettaPay payment, and inspect it in the Stellar Laboratory.

Do this first
This is the foundation for every other guide. Complete it once and you'll have a funded testnet wallet ready for your first payment.

Step 1 — Install Freighter and switch to testnet

1

Install and select the Test Network

  1. Install the Freighter extension from freighter.app and create (or import) a wallet. Save your recovery phrase.
  2. Open Freighter, click the network selector at the top, and choose Test Net. Everything you do now is on testnet.
  3. Copy your public key (starts with G…) — you'll fund it next.
Always confirm the network
Freighter shows the active network on every signing prompt. Before you sign anything in these guides, confirm it reads Test Network.

Step 2 — Fund your account with friendbot

A brand-new Stellar account holds nothing and isn't yet on the ledger. Friendbot creates and funds testnet accounts with 10,000 test XLM. Replace the address with your Freighter public key:

fund-account.sh
# Fund a testnet account with 10,000 test XLM.
curl "https://friendbot.stellar.org/?addr=GYOUR_PUBLIC_KEY_HERE"

# A successful response is the funding transaction as JSON.
# Re-run it any time your test XLM runs low.

Prefer a UI? The Stellar Laboratory has a "Fund account with friendbot" button that does the same thing.

Step 3 — Get test USDC

XLM covers network fees, but BettaPay settles in USDC, so you need a test USDC balance. Two things are required: a trustline to the testnet USDC asset, and some tokens.

3

Add a trustline and receive test USDC

  1. In Freighter, choose Manage Assets → Add asset and add USDC using the testnet issuer published in the API reference (asset code USDC). This creates the trustline.
  2. Use the BettaPay testnet USDC faucet (in the dashboard under Developers → Testnet tools) to send test USDC to your address.

Confirm the balance appears in Freighter before continuing. Without a trustline, any USDC sent to you will bounce.

Note
Testnet USDC has no value and is periodically reset with the network. Top up from the faucet whenever you need more.

Step 4 — Create a test payment link

With a funded wallet you can run a real payment. In a BettaPay merchant account set to testnet, create a payment link exactly as in Accepting Your First Payment — for example a 1.00 USD link. Keep the amount small so your faucet balance lasts across many tests.

Step 5 — Pay with Freighter

5

Complete the test checkout

  1. Open the payment link and click Pay with wallet.
  2. Approve the Freighter connection and review the USDC amount.
  3. Confirm the network says Test Network, then sign. The payment confirms in a few seconds and the dashboard shows Succeeded.

Step 6 — Inspect the transaction in Stellar Laboratory

The Stellar Laboratory lets you look at the raw ledger. Take the transaction hash from the payment detail in your dashboard and:

  • Paste it into Explore Endpoints → Transactions → Single Transaction (make sure the Lab is set to Testnet).
  • Review the operations — you should see a payment operation moving USDC from the customer to your settlement wallet.
  • Check the memo and asset match what BettaPay recorded.

You can also inspect any address's balances and history in stellar.expert (testnet).

Reset your test data

  • Fresh wallet — create a new account in Freighter and re-fund it with friendbot to start from a clean slate.
  • Clear BettaPay test data — under Developers → Testnet tools you can wipe test payments and links without touching production data.
  • Network resets — the Stellar testnet is periodically reset. When that happens, existing testnet accounts and balances disappear; just re-fund with friendbot and re-add your trustline.
Keep testnet and mainnet separate
Never reuse a testnet key as a production settlement wallet, and double-check your merchant account's network before going live. Testnet funds are not real; mainnet funds are.

Common issues

Friendbot says "account already funded"

The account already exists on testnet. That's fine — you can receive payments. Friendbot only creates an account once; use the faucet for more test USDC.

USDC doesn't show up after sending

You're almost certainly missing the trustline. Add the USDC asset in Freighter (Step 3) and resend from the faucet.

"op_underfunded" when paying

Not enough USDC (or XLM for fees). Re-fund XLM with friendbot and top up USDC from the faucet, then retry the checkout.

Laboratory shows "not found" for my transaction

The Lab is probably set to the wrong network. Switch it to Testnet and paste the hash again.

Feature status
Testnet payments, the friendbot funding flow, and Laboratory inspection are available now. The in-dashboard USDC faucet and test-data reset tools live under Developers → Testnet tools.

Next steps