Customers

Customers represent payers in your merchant account. Use them to group payments, enrich webhooks, and build a simple CRM on top of Payoes.

What a customer stores

Field	Description
`id`	Public ID (`cus_...`)
`email`	Contact email
`name`	Display name
`primary_stellar_address`	Main Stellar wallet for this payer
`notes`	Internal merchant notes
`metadata`	Custom key-value pairs

Customers are scoped to your organization and environment (sandbox or production).

Manual creation

Create a customer from the dashboard or API before sending a payment:

curl -X POST https://payoes.com/api/v1/customers \
  -H "Authorization: Bearer pk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@example.com"
  }'

Link a customer to a payment

When creating a payment, pass customer_id to pre-link the checkout:

curl -X POST https://payoes.com/api/v1/payments \
  -H "Authorization: Bearer pk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing_currency": "USD",
    "pricing_amount": "25.00",
    "customer_id": "cus_abc123xyz",
    "description": "Pro plan"
  }'

This is similar to attaching a Stripe Customer to a PaymentIntent.

Auto-create from checkout

If you do not pass customer_id, Payoes still links payers automatically:

Customer completes hosted checkout
Payoes verifies the transaction on Horizon
Payoes reads the payer wallet (from address)
Payoes creates or updates a customer for that wallet
The payment is linked to that customer

This is useful when you share checkout links without knowing the payer wallet in advance.

Payment fields

Completed payments include:

Field	Description
`customer_id`	Linked customer public ID
`payer_address`	Wallet that signed the Stellar transaction

Webhook payloads for payment.completed include both fields.

Retrieve customer history

curl https://payoes.com/api/v1/customers/cus_abc123xyz \
  -H "Authorization: Bearer pk_test_YOUR_KEY"

The response includes the customer profile and an array of linked payments.

What customers are not

Not login accounts for your dashboard
Not custodial wallets (Payoes never holds private keys)
Not saved payment methods that can charge without wallet approval

Next steps

Quickstart

Create a payment and complete checkout.

Webhooks

React to payment.completed events.

Get started

Core concepts

Payments

What a customer stores

Manual creation

Link a customer to a payment

Auto-create from checkout

Payment fields

Retrieve customer history

What customers are not

Next steps

Quickstart

Webhooks

​What a customer stores

​Manual creation

​Link a customer to a payment

​Auto-create from checkout

​Payment fields

​Retrieve customer history

​What customers are not

​Next steps

Quickstart

Webhooks

What a customer stores

Manual creation

Link a customer to a payment

Auto-create from checkout

Payment fields

Retrieve customer history

What customers are not

Next steps