Core concepts
The Stripe-like object model, API key authentication, sandbox and production environments, and how customers work.
The object model
Payoes follows a Stripe-like mental model adapted for Stellar. Every resource has a prefixed public ID that appears in the API, the dashboard, and hosted URLs.
Payment intent (pay_)
A single payment request with amount, assets, status, and checkout_url.
Checkout session (cs_)
A hosted checkout flow spawned from an invoice or payment link visit.
Payment link (plink_)
Reusable checkout entry at /c/plink_...; each visit starts a new checkout session.
Invoice (inv_)
Draft, then finalize to spawn a checkout session; statuses draft, open, paid, void.
Customer (cus_)
The payer: email, name, primary Stellar address, and payment history.
Transaction
Completed payments store the Stellar tx_hash for explorer lookup.
Authentication
All REST API requests carry a Bearer API key. The full key is shown only once at creation; Payoes stores a hash and cannot recover it. To rotate, create a new key, update your configuration, then revoke the old one: revoked keys stop working immediately.
Authenticated request
- 1
Attach the Bearer key
Send every request with an Authorization: Bearer header carrying your pk_test_ or pk_live_ key.
- 2
Keep it server-side
The full key is shown once at creation and stored only as a hash, so keep it out of browser and mobile code.
- 3
Handle 401s
A missing or invalid key returns 401 Unauthorized; rotate by creating a new key, then revoking the old one.
Server-side only
Never expose keys in browser JavaScript or mobile apps.
Scoped per environment
A key belongs to one business and one environment.
Every request logged
Method, path, status, and duration under Developers, then API Logs.
Environments
Sandbox runs on Stellar Testnet with pk_test_ keys and test tokens; production runs on Mainnet with pk_live_ keys and real value. Each environment has its own settlement wallet, and identity verification through Persona is required before production mode unlocks.
Keys carry the environment
A pk_test_ key always creates sandbox payments; pk_live_ creates production ones.
Free Testnet funding
Fund a test wallet from the Stellar Laboratory faucet and pay yourself to test.
Production gate
Persona verification (ID + liveness) plus a Mainnet settlement wallet.
Payments expire
Default 60 minutes; expired payments trigger a payment.expired webhook.
Customers
Customers group payments, enrich webhooks, and act as a light CRM. Pass customer_id when creating a payment to pre-link it, or let Payoes auto-create a customer from the payer wallet it sees at checkout.
Auto-created from checkout
Payoes reads the payer address on-chain and links or creates the customer.
History included
GET /v1/customers/{id} returns the profile plus linked payments.
Not login accounts
Customers never sign in; there are no saved payment methods that bypass wallet approval.
Ready to build?
Grab a sandbox key and make your first request in minutes.
← Back to home