Core concepts

Payoes follows a Stripe-like mental model adapted for Stellar blockchain payments.

​

Roles

​

Resources

​

Organization

An organization represents one business on Payoes. During onboarding you provide a name, logo, and contact details. Each organization has:

• A sandbox or production environment
• Identity verification required before production mode (via Persona)
• A settlement wallet per environment
• Its own API keys, payments, and webhooks
• Team members with role-based access

Edit your organization profile in Settings → Organization. Complete Settings → Production to verify your identity with Persona before enabling live payments.

​

Team members

Users who can access your organization dashboard. The creator becomes the owner during onboarding. Owners and admins can invite teammates by email from Settings → Team Members. Invitees receive an email with a link to accept the invitation. They must sign in or create an account with the invited email address before joining.

​

Settlement wallet

The Stellar public key where customer payments are sent. Configured during onboarding and editable in Settings → Settlement Wallet. Payoes reads this address when building checkout transactions and when verifying payments on Horizon.

​

Organization assets

Each organization maintains a list of assets it accepts (USDC, XLM, EURC, custom Stellar assets, etc.) in Settings → Assets. All payment products inherit asset configuration from organization assets. Invoices do not store their own asset — a payment is created automatically with the organization’s default settlement asset and enabled allowed assets.

​

Payment intent

A single payment request, equivalent to a Stripe Payment Intent. Payment intents are created directly via the dashboard or API, or automatically when you finalize an invoice or start checkout from a payment link.

​

Checkout session

A hosted checkout flow, equivalent to a Stripe Checkout Session. Each session creates an underlying payment intent. Checkout sessions are created automatically when you finalize an invoice or when a customer visits a payment link. You can list and retrieve them via the API.

​

Payment link

A reusable shareable link, equivalent to a Stripe Payment Link. Each visit to a payment link starts a new checkout session and payment intent.

​

Invoice

A bill sent to a customer, equivalent to a Stripe Invoice. Create an invoice in draft, then finalize it to spawn a checkout session and payment intent.

​

Checkout

A public hosted page at /c/{checkout_id} where checkout_id is either cs_... (checkout session) or pay_... (legacy payment intent). The checkout flow:

1. Load payment details and merchant branding
2. Customer connects a Stellar wallet (Wallet Kit)
3. Payoes builds an unsigned transaction server-side
4. Customer signs and submits via their wallet
5. Payoes verifies the transaction on Horizon
6. Payment status updates to completed

Customers never log into Payoes.

​

Transaction

After a successful payment, the Stellar transaction hash (tx_hash) is stored on the payment intent record. You can look it up on Stellar Explorer for the corresponding network (testnet or mainnet).

​

API key

Secret credential for server-to-server API calls. Prefixes:

• pk_test_...: sandbox (Stellar testnet)
• pk_live_...: production (Stellar mainnet)

API keys are tied to one organization and one environment.

​

Webhook

HTTP callbacks sent to your server when payment events occur. Use webhooks to unlock products, send receipts, or update your database without polling.

​

Payment lifecycle

​

Sandbox vs production

See Environments for details.