Skip to main content
The Payoes API is a REST JSON API for creating and managing Stellar payments, customers, and billing resources.

​
Base URL

All public integration endpoints are under /api/v1.

​
Authentication

See Authentication for key management and rotation.

​
Environments

API keys are scoped to a single environment:
Key prefixEnvironmentStellar network
pk_test_...SandboxTestnet
pk_live_...ProductionMainnet
List and retrieve operations only return resources created in the same environment as the API key. Sandbox and production data are fully isolated. See Environments for dashboard mode switching and settlement wallets.

​
Request format

  • Send JSON bodies with Content-Type: application/json
  • Use snake_case field names in request and response bodies
  • Amounts are strings with up to 7 decimal places (Stellar convention)

​
Response format

Successful responses return JSON objects. List endpoints wrap resources in a plural key (for example payments, customers). Errors return: 
{
  "error": "Human-readable message"
}

​
Object types

Resources include an object field for identification:
object valueResource
payment_intentPayment
checkout.sessionCheckout session
payment_linkPayment link
invoiceInvoice

​
Available endpoints

​
Payments

MethodPathDescription
POST/paymentsCreate a payment intent
GET/paymentsList payments
GET/payments/{id}Retrieve a payment

​
Customers

MethodPathDescription
POST/customersCreate a customer
GET/customersList customers
GET/customers/{id}Retrieve a customer and payment history

​
Checkout sessions

MethodPathDescription
GET/checkout-sessionsList checkout sessions
GET/checkout-sessions/{id}Retrieve a checkout session
Checkout sessions are created when you finalize an invoice or when a customer visits a payment link.
MethodPathDescription
POST/payment-linksCreate a reusable payment link
GET/payment-linksList payment links
GET/payment-links/{id}Retrieve a payment link

​
Invoices

MethodPathDescription
POST/invoicesCreate a draft invoice
GET/invoicesList invoices
GET/invoices/{id}Retrieve an invoice
POST/invoices/{id}/finalizeFinalize a draft invoice and get a checkout URL
Invoices can also be created with line items and sent by email from the dashboard. The hosted invoice page is available at /i/{invoice_id} after finalize. Full request and response schemas are in the endpoint sections of this API reference, generated from apps/docs/openapi/v1.yaml.

​
Hosted URLs

ResourceURL pattern
Payment checkout/c/{payment_id} or /c/{checkout_session_id}
Payment link/c/{payment_link_id}
Hosted invoice/i/{invoice_id}

​
Rate limiting

Rate limits are not enforced in the current release. Production deployments should implement limits. Check release notes for updates.

​
Idempotency

Idempotency keys are planned. Until then, use unique metadata values and guard webhook handlers against duplicate processing.

​
Changelog

VersionChanges
v1Payments, customers, checkout sessions, payment links, and invoices APIs