Payment Infrastructure for Stellar, Without the Blockchain Complexity.

Payoes is a developer first payment infrastructure for Stellar that makes blockchain payments as simple as traditional payment gateways.

Features · Screenshots · Testing · User Feedback · Social · Quick Start · Architecture · Contributing

---

About

Payoes is a developer first payment infrastructure that makes blockchain payments as easy to integrate as traditional payment gateways. By abstracting wallets, blockchain transactions, and payment settlement behind familiar APIs, Payoes enables developers and businesses to build modern payment experiences without blockchain complexity.

Why Payoes

Blockchain payments are rapidly gaining adoption, but integration remains a major challenge for developers and businesses.

According to Source: Ripple's 2026 Digital Asset Survey:

• 74% of financial leaders believe stablecoins improve cash flow efficiency.
• 57% prefer an integrated payment infrastructure partner.
• 71% prefer a unified payment solution over fragmented payment tools.

Despite this growing demand, developers are still expected to manage wallets, blockchain transactions, smart contracts, and payment settlement on their own.

Payoes bridges this gap by providing a developer first payment infrastructure that abstracts blockchain complexity into familiar payment workflows. Instead of building payment infrastructure from scratch, developers can integrate Stellar payments using modern APIs while leveraging the speed, security, and transparency of the Stellar network.

Features

• Crypto Payments
  Accept Stellar asset payments through a modern payment gateway. Payoes abstracts wallets, blockchain transactions, and payment processing so developers can integrate crypto payments without blockchain expertise.

• Checkout, Payment Links & Invoicing
  Create hosted checkout pages, reusable payment links, and professional invoices to deliver a seamless payment experience for customers while simplifying payment collection for businesses.

• On Chain Settlement & Verification
  Every successful payment is securely settled on the Stellar network and permanently recorded on chain, providing transparent, immutable, and publicly verifiable payment records.

• Cross Asset Settlement
  Let customers pay with their preferred Stellar asset while merchants automatically receive settlement in their preferred asset through Stellar Path Payments.

• Developer Integration
  Integrate Payoes into any application using developer friendly REST APIs, official SDKs, and real time webhooks designed for fast and reliable payment integrations.

• Platform Integrations
  Connect Payoes with popular commerce platforms, business applications, and developer tools through ready to use integrations, plugins, APIs, and webhooks.

Screenshots

Product walkthrough of the Payoes merchant dashboard, hosted checkout, settlement flow, integrations, and KYC onboarding. The UI is fully responsive — the same flows work on desktop and mobile without a separate app.

Desktop

Landing Page	Dashboard	Payment
Settlement	Integrations	KYC Verification

Mobile

Landing Page

Dashboard

Testing

Payoes ships automated tests for every Soroban smart contract in contracts/. The suite currently runs 24 passing tests across both crates:

Crate	Tests	Coverage
payoes	8	Escrow flow, legacy pay, admin controls, settlement, refunds
payoes-shielded-pool	16	ZK deposit/withdraw, Merkle tree, Groth16 proof verification, admin

Run all contract tests from the repo root:

npm run test:contracts

Or directly:

bash scripts/test-contracts.sh

_{payoes (8 tests) + shielded-pool (16 tests)}

Every push and pull request to main runs the full build and contract test suite through our CI pipeline. Production deploys only proceed after CI passes, via .github/workflows/deploy.yml.

User Feedback

We collect product feedback through a Google Form and export responses to a Google Sheet for analysis (downloadable as Excel via File → Download → Microsoft Excel).

What we learned

Metric	Summary
Total responses	70+
Avg. experience score	4.3 / 5
Avg. transaction ease	4.2 / 5
Avg. UI/UX score	4.2 / 5

Top positive themes: easy API integration, clean hosted checkout, fast Stellar settlement, muxed deposit reconciliation, and cross-asset path payments.

Top improvement requests: more wallet options, dashboard CSV export, clearer refund docs, recurring/subscription payments, and commerce platform plugins.

What's next

The roadmap below maps the most common feedback themes to concrete next steps. Items already in progress link to the git commits that shipped or started the work.

Feedback theme	User ask	Next phase plan	Related commit
Commerce integrations	"Add WooCommerce / Shopify plugin"	Harden Shopify & WooCommerce webhook flows, publish setup guides, and ship one-click install templates	6b1225b — Discord/Slack notification integrations
Wallet coverage	"Support more wallets beyond Freighter"	Expand Stellar Wallets Kit adapters and improve connect-wallet UX on mobile checkout	3a861d0 — checkout success UI & wallet kit fixes
Cross-chain USDC	"Pay from EVM chains"	Extend CCTP checkout chains, improve bridge quote clarity, and reduce relayer latency	945a351 — CCTP checkout & settlement
Private payments	"Stronger privacy for payers"	Roll out zk_shielded checkout on Mainnet after KYB verification and pool audits	0335e79 — shielded private payments
Settlement speed	"Webhooks sometimes arrive late"	Replace polling with Horizon SSE workers for near-real-time deposit detection	86ba118 — Horizon SSE settlement workers
Smart contract trust	"Is the Soroban contract production-ready?"	Expand contract test coverage, add CI gates, and publish deployment verification in README	287daf4 — full contract test suite & CI job
Dashboard reporting	"Export data to CSV for accounting"	Add CSV export for payments, settlements, and transactions in the merchant dashboard	Planned — Q3 2026
Refund clarity	"How does the refund flow work?"	Document escrow refund paths and add in-dashboard refund status tracking	Planned — Q3 2026
Recurring billing	"Subscription / recurring payments"	Design invoice schedules with on-chain escrow renewal and webhook billing events	Planned — Q4 2026
UI polish	"Add dark mode"	Ship theme toggle across marketing site, dashboard, and hosted checkout	Planned — Q3 2026

We review the exported spreadsheet after each Testnet cohort and reprioritize the roadmap quarterly.

Social Media

Follow Payoes on X for product updates, demos, and Stellar ecosystem news: @payoesofficial

Launch

Our pinned post introduces Payoes as developer-first payment infrastructure on Stellar — hosted checkout, payment links, webhooks, and near-zero fees with ~5s settlement:

Accept crypto payments without the infrastructure headache. Payoes runs on Stellar: near-zero fees, settlement in seconds, open source. Hosted checkout, payment links, webhooks — all from your browser. Start free → payoes.com
#Stellar #Web3

More posts cover wallet integrations, the analytics dashboard, multi-org roles, and how Stellar settlement compares to traditional card processors — all on the @payoesofficial profile.

Demos & resources

Content	Link
Product demo video	YouTube — Payoes walkthrough
Pitch deck	Canva deck
Product screenshots	Screenshots above

Posts tag the Stellar ecosystem: #Stellar · #BuildOnStellar · #Payoes · #Web3 · #Payments · #DevTools

Stellar Usage

Payoes is built on Stellar as the settlement layer. customers pay through wallets or QR codes; funds move through on-chain payment routing, path payments, and on-chain verification on Testnet or Mainnet.

Payment flow

1. Customer pays via wallet or QR deposit
2. Hosted checkout (Stellar Wallets Kit)
3. Muxed deposit address (SEP-23), detected by Horizon
4. Soroban settlement contract: register, deposit, settle or refund
5. Same asset: settle on contract (merchant + platform fee)
6. Cross asset: release to operator, Path Payment via DEX, record settlement
7. Merchant settlement wallet, webhooks, and explorer links

Soroban Smart Contract

The Payoes contract in contracts/ is the on-chain payment router for every new payment.

Capability	What it does
register_payment	Locks payment terms: merchant, paid token, settlement amount, platform fee, expiry
deposit	Holds customer funds on-chain; auto-refunds if the amount is too low
settle_same_asset_deposit	Atomically pays the merchant and platform fee when paid and settlement assets match
release_deposit_to_operator	Releases held funds for cross-asset conversion by the settlement worker
record_settlement / record_refund	Finalizes contract state after Horizon settlement or refund
Admin controls	Pause switch, fee recipient, authorization signer rotation

Contract events (payment_registered, payment_deposit_received, payment_settled, payment_refunded) provide an auditable on-chain trail. Rust unit tests cover legacy pay, same-asset settlement, and underpayment refunds.

Deployed Contract (Testnet)

Field	Value
Deployed contract address	CDD7VS6OPAAEHUNHJ2RUTLG5FZZWSWR2GZL5XFQBTQOTIO3ZEY5M6JJS
Transaction hash of a contract call	a7cc6f93204306dfe5b3141c86a71d44082c0da6e237910be6498452f02356ee (register_payment)

Deployed Contract (Mainnet)

Field	Value
Deployed contract address	CANYTHWVKNUVAM2WZUAKIPP3AD6C5CBDPDDHZPJOPBRJRWRBOVGGZNUI
Transaction hash of a contract call	3bad5589c13d05f97d6059e52ca3a73e312c022585171fb790586cc18f2b3ccf (initialize)

See the settlement flow diagram in docs/architecture/.

Path Payments and DEX Liquidity

Customers can pay in one Stellar asset while merchants settle in another (for example, pay in XLM, receive USDC).

1. Payoes quotes the required paid amount using live pricing and slippage buffers.
2. The settlement worker queries Horizon strictReceivePaths to find the best route through the Stellar DEX.
3. The operator submits a pathPaymentStrictReceive transaction to deliver the exact settlement amount to the merchant wallet.
4. The Soroban contract records the final settlement on-chain.

This uses Stellar's native order books and liquidity paths instead of custom swap logic.

Trustlines

Issued assets on Stellar (such as USDC) require trustlines before an account can hold them.

Payoes validates trustlines before checkout and settlement:

• Customers must trust the asset they pay with (clear error if missing).
• Merchants must trust settlement assets on their receiving wallet.
• Operator accounts auto-sync trustlines for accepted merchant assets during payment creation and quote refresh.

Merchants can add missing trustlines from the dashboard via changeTrust transactions signed in their connected wallet.

Muxed Accounts (SEP-23)

Each payment gets a unique muxed deposit address (M...) derived from the operator account and the payment ID. This gives Payoes:

• One deposit destination per checkout without creating a new keypair per payment
• Easier reconciliation when many customers pay in parallel
• QR-friendly deposit URLs that map to a single payment intent

Horizon deposit detection matches both classic and muxed destination fields when confirming payments.

Horizon API

Horizon is Payoes' read and submit layer for classic Stellar operations:

Use case	Horizon capability
Build payment XDR	Load account sequence, network passphrase
Path finding	strictReceivePaths for cross-asset quotes and settlement
Payment verification	Fetch transaction + operations; validate destination, asset, amount, memo
QR / background deposits	Horizon SSE stream on operator account payments
Explorer links	Tx hashes surfaced in the dashboard link to Stellar Expert

A background Horizon stream in the web process detects escrow QR deposits and drives on-chain settlement for sandbox and production. Run a single web replica (replicas: 1).

Network Duality

Every organization runs in sandbox or production. Payoes maps environments directly to Stellar networks:

Payoes environment	Stellar network	Horizon	Soroban
sandbox	Testnet	Testnet Horizon	Testnet contract + RPC
production	Mainnet	Mainnet Horizon	Mainnet contract + RPC

API keys, payments, webhooks, and settlement wallets are scoped per environment. The dashboard mode switcher lets merchants test on Testnet before going live on Mainnet with the same integration code.

Wallet Integration

Hosted checkout connects to the Stellar wallet ecosystem through Stellar Wallets Kit:

• Freighter, Albedo, and xBull supported out of the box
• Network validation ensures the wallet matches the checkout environment (Testnet vs Mainnet)
• Customers sign deposit transactions in-wallet; operator secrets never reach the browser
• QR mode generates web+stellar:pay URIs for wallet apps that support URI scanning

Merchants connect a settlement wallet (for example via Freighter) during onboarding to receive funds.

Private Payments (ZK Shielded)

Payoes supports an optional zk_shielded checkout flow. Customers deposit the exact invoice amount into a Soroban shielded pool, then Payoes withdraws to the merchant with a Groth16 zero-knowledge proof that breaks the on-chain link between depositor and payee.

Customer flow

1. Open hosted checkout from a payment link, invoice, or API payment.
2. In the Connect Wallet tab, enable Pay privately (when available).
3. Connect a Stellar wallet and click Pay.
4. Sign the shielded pool deposit, then Payoes generates the withdraw proof and settles to the merchant.

If the customer does not opt in, checkout uses the normal public escrow flow. Private payment is not available when paying from a cross-chain (CCTP) source network.

Privacy model

Visible on-chain	Hidden
Exact withdraw amount	Which deposit funded the payment
Merchant settlement address	Customer wallet at settlement
Pool deposit transaction (customer wallet visible on deposit)	Link between deposit and merchant payment

Because the withdraw amount is exact and public, unique invoice amounts can leak metadata through timing analysis. Payoes does not store payerAddress for zk_shielded payments.

Merchant and operator requirements

Requirement	Sandbox (Testnet)	Production (Mainnet)
Shielded pool contract deployed	Yes	Yes
Merchant KYB	No	Yes (verification_status = verified)
Escrow payment flow	Yes	Yes

Private payments appear at checkout automatically when the shielded pool is configured for the organization's environment. Operators deploy the pool from contracts/shielded-pool/ and set verifying keys:

./scripts/sync-zk-artifacts.sh
npm run soroban:deploy-shielded-pool

Set these keys in .env.local (see .env.example):

Variable	Purpose
SOROBAN_TESTNET_SHIELDED_POOL_CONTRACT_ID / SOROBAN_MAINNET_SHIELDED_POOL_CONTRACT_ID	Deployed shielded pool contract ID
SOROBAN_TESTNET_RPC_URL / SOROBAN_MAINNET_RPC_URL	Soroban RPC for pool reads and submissions
STELLAR_TESTNET_OPERATOR_SECRET / STELLAR_MAINNET_OPERATOR_SECRET	Operator account that authorizes pool transactions

Full setup, circuit sources, and architecture notes: Private payments guide and contracts/README.md.

Cross-Chain USDC (Circle CCTP v2 on Stellar)

Payoes lets customers pay USDC invoices from EVM chains using Circle CCTP v2, with Stellar as the destination (CCTP domain 27). USDC is burned on the source chain, attested by Circle Iris, minted on Stellar through a forwarder contract, then settled through the normal Soroban escrow flow.

Customer flow

1. Open hosted checkout and select USDC as the paid asset.
2. In the Connect Wallet tab, open the network selector and choose a source chain (for example Base, Ethereum, Arbitrum, Polygon, or Optimism).
3. Connect an EVM wallet (browser extension) on the matching network.
4. Review the bridge quote (payment amount, fees, total burn amount) and click Pay.
5. Approve USDC spend and confirm the CCTP burn transaction in the wallet.
6. Payoes polls Circle for attestation, relays the mint on Stellar, and completes escrow settlement.

Stellar-native USDC payments use the regular Stellar wallet flow; CCTP applies only when the customer selects a non-Stellar source network.

Supported checkout chains

Chains exposed in the checkout network selector (see apps/web/src/lib/cctp/chain-registry.ts):

Chain	Sandbox network	Mainnet network	Fast transfer
Base	Base Sepolia	Base	Yes
Ethereum	Sepolia	Ethereum	Yes
Arbitrum	Arbitrum Sepolia	Arbitrum	Yes
Polygon	Polygon Amoy	Polygon	No
Optimism	OP Sepolia	OP Mainnet	Yes

Sandbox organizations use testnet EVM chains and Circle Iris sandbox; production organizations use mainnet chains and production Iris. Chain registry entries include RPC URLs, USDC contract addresses, and Token Messenger contracts for each environment.

Fee structure

Quotes combine Circle protocol fees and a Payoes bridge service fee:

Component	When it applies	Notes
CCTP protocol fee	Fast transfer on supported chains	Fetched from Circle Iris; quoted with a 20% buffer
Payoes bridge fee	All cross-chain USDC checkouts	CCTP_SERVICE_FEE_USDC (default 0.05 USDC), retained by the operator to cover relayer cost
Standard transfer	Chains without fast transfer, or when fast is unavailable	Protocol fee is 0; only the bridge fee applies

The checkout panel shows Amount, Fee, and Total (total USDC burned on the source chain).

Merchant and configuration requirements

• Payment must allow USDC and use the escrow flow (payment_flow: escrow).
• No extra merchant dashboard setup; settlement follows the same escrow path after Stellar mint.
• Operators need a funded Stellar operator account (STELLAR_TESTNET_OPERATOR_SECRET or STELLAR_MAINNET_OPERATOR_SECRET) to submit the mint_and_forward relay transaction.
• Optional: set CCTP_SERVICE_FEE_USDC in .env.local (see .env.example) to adjust the bridge fee.

CCTP implementation lives under apps/web/src/lib/cctp/ (chain registry, fee quotes, EVM adapters, Iris client, Stellar relayer).

---

Resources

Resource	Link
Website	https://payoes.com
X (Twitter)	@payoesofficial
Documentation	https://docs.payoes.com
Payoes SDK	https://www.npmjs.com/package/@payoes/sdk
Demo Video	https://www.youtube.com/watch?v=QL7icAGV0t4
Pitch Deck	https://canva.link/r0khw89qvqiv4ft
Testnet Smart Contract	CDD7VS6OPAAEHUNHJ2RUTLG5FZZWSWR2GZL5XFQBTQOTIO3ZEY5M6JJS
Testnet Contract Call Tx	a7cc6f93204306dfe5b3141c86a71d44082c0da6e237910be6498452f02356ee (register_payment)
Mainnet Smart Contract	CANYTHWVKNUVAM2WZUAKIPP3AD6C5CBDPDDHZPJOPBRJRWRBOVGGZNUI
Mainnet Contract Call Tx	3bad5589c13d05f97d6059e52ca3a73e312c022585171fb790586cc18f2b3ccf (initialize)
User Feedback Form	Google Form
User Feedback (Exported Responses)	Google Sheets

Requirements

• Node.js >= 20
• npm >= 10
• Docker (for local PostgreSQL and MinIO)

Quick Start

git clone git@github.com:yazidalg/payoes.git
cd payoes
npm install
npm run docker:up
cp .env.example .env.local
npm run db:migrate
npm run dev              # http://localhost:3000

For the full local setup (environment variables, docs server), see the Getting started guide in apps/docs/.

Scripts

Script	Description
npm run dev	Start the Next.js dev server on port 3000.
npm run build	Produce an optimized production build.
npm run start	Serve the production build locally.
npm run lint	Run ESLint across the web app.
npm run docker:up	Start PostgreSQL and MinIO via Docker Compose.
npm run docker:down	Stop Docker Compose services.
npm run db:migrate	Apply Drizzle database migrations.
npm run db:setup	Initialize the database schema.
npm run db:studio	Open Drizzle Studio for database inspection.
npm run docs:dev	Start Mintlify docs on port 3001.
npm run test:contracts	Run all Soroban smart contract tests (cargo test --workspace).

Architecture

Payoes is a monorepo that combines a Next.js application, a Soroban settlement contract, and shared packages. Merchants integrate through REST APIs or platform plugins; customers pay on hosted checkout pages without creating a Payoes account.

Diagrams use the C4 model. Source files and full write-up live in docs/architecture/.

API surfaces

Payoes exposes two authenticated API surfaces that share the same domain services (src/lib/<domain>/service.ts):

Surface	Path	Auth	Used by
Public REST API	/api/v1/**	Bearer API key (sandbox or production)	Merchant backends, SDK, integrations
Internal API	/api/** (non-v1)	Auth.js session	Dashboard UI
Inbound webhooks	/api/webhooks/**	Provider signatures	Persona, Shopify, WooCommerce

Every organization-scoped resource is filtered by organizationId and environment. Sandbox maps to Stellar Testnet; production maps to Mainnet.

Repository layout

Path	Role
apps/web	Next.js app: marketing site, dashboard, hosted checkout, REST API, background workers
apps/docs	Mintlify API documentation
packages/sdk	@payoes/sdk npm package for merchant integrations
contracts	Soroban smart contract for on-chain payment routing and settlement
docs/architecture	C4 PlantUML diagram sources

---

Contributing

Contributions are welcome: bug reports, feature requests, and pull requests all help improve Payoes for developers and organizations alike.

Before opening a PR:

1. Install dependencies: npm install
2. Start local services: npm run docker:up
3. Run migrations: npm run db:migrate
4. Verify the build: npm run build
5. Run lint: npm run lint
6. Keep commits scoped and follow conventional prefixes (feat:, fix:, style:, refactor:, chore:, docs:).
7. For UI changes, include before/after screenshots in your PR description when practical.

---

Acknowledgements

Built for organizations that want modern payment infrastructure on Stellar, standing on open-source foundations:

• Next.js · React · Tailwind CSS
• Stellar: onchain payments and asset infrastructure
• shadcn/ui: dashboard components and design patterns
• Mintlify: developer documentation

_{Payment Infrastructure for Stellar, Without the Blockchain Complexity. · yazidalg/payoes}