API Documentation

Create a payment. gateway defaults to stripe. Stripe only receives amount/currency (+ our internal invoice_id). Crypto uses an OxaPay invoice and returns that hosted checkout URL. Other fields stay in PayGate.

Request body

{
    "order_id": "ORDER-001",          // required
    "amount": 1000,                    // required (cents)
    "currency": "USD",                 // required fiat price currency
    "gateway": "stripe",               // optional: stripe | oxapay
    "pay_currency": "usdttrc20",       // optional crypto coin; payer chooses if omitted
    "customer_reference": "CUST-001", // optional; reuse saved card (Stripe only)
    "charge": true,                    // optional: charge saved card now (Stripe only)
    "return_url": "https://yoursite.com/thanks", // optional success return
    "cancel_url": "https://yoursite.com/cancel", // optional cancel return
    "webhook_url": "https://...",     // optional merchant IPN (local only)
    "customer": { "name": "…", "email": "…" }, // optional (local only)
    "description": "…"                // optional (local only)
}

Without charge, returns a hosted pay URL. Stripe events: payment_intent.succeeded, payment_intent.payment_failed. OxaPay is paid when it reports Paid. Crypto payments cannot be refunded or rebilled here.

curl — hosted pay page

curl -X POST https://pay.aethermedia.art/api/payments/create \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "order_id": "ORDER-001",
    "amount": 1000,
    "currency": "USD",
    "customer_reference": "CUST-001",
    "return_url": "https://yoursite.com/thanks",
    "cancel_url": "https://yoursite.com/cancel",
    "webhook_url": "https://yoursite.com/ipn"
  }'

curl — charge saved card

curl -X POST https://pay.aethermedia.art/api/payments/create \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "order_id": "ORDER-002",
    "amount": 1000,
    "currency": "USD",
    "customer_reference": "CUST-001",
    "charge": true
  }'

curl — crypto invoice

curl -X POST https://pay.aethermedia.art/api/payments/create \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "order_id": "ORDER-003",
    "amount": 1000,
    "currency": "USD",
    "gateway": "oxapay",
    "pay_currency": "USDT",
    "return_url": "https://yoursite.com/thanks"
  }'

checkout_url is the OxaPay hosted page. Omit pay_currency to let the payer pick a coin.

Response (hosted)

{
    "success": true,
    "payment": {
        "order_id": "ORDER-001",
        "status": "pending",
        "amount": 1000,
        "currency": "USD",
        "gateway": "stripe",
        "type": "one_time",
        "checkout_url": "https://pay.example.com/pay/...",
        "customer_reference": "CUST-001"
    }
}

With charge: true, status is usually paid and checkout_url is null.

List payments (paginated).

curl https://pay.aethermedia.art/api/payments \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Accept: application/json"

Get one payment by order ID.

curl https://pay.aethermedia.art/api/payments/ORDER-001 \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Accept: application/json"

Cancel a pending payment.

curl -X POST https://pay.aethermedia.art/api/payments/ORDER-001/cancel \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Accept: application/json"

Full or partial refund (amount in cents). Stripe only.

curl -X POST https://pay.aethermedia.art/api/payments/ORDER-001/refund \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"amount": 500, "reason": "Customer request"}'

Charge the saved card from the original payment. Currency stays the original. Stripe only.

curl -X POST https://pay.aethermedia.art/api/payments/ORDER-001/rebill \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "order_id": "REBILL-002",
    "amount": 1500
  }'

List customers (paginated).

curl https://pay.aethermedia.art/api/customers \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Accept: application/json"

Get one customer by reference.

curl https://pay.aethermedia.art/api/customers/CUST-001 \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Accept: application/json"

Webhook callbacks

When you provide a webhook_url, we POST payment status updates to it. Each payload is signed with HMAC-SHA256 using your merchant webhook secret (Profile page). Failed deliveries can be resent from the payment webhook detail.

Headers

• X-Signature — hash_hmac('sha256', rawBody, webhook_secret)
• X-Webhook-Event — e.g. payment.paid, payment.failed, payment.cancelled, payment.refunded
• X-Webhook-ID — unique event ID
• X-Payment-Id — internal payment id

Payload

{
    "order_id": "ORDER-001",
    "status": "paid",
    "amount": 1000,
    "currency": "USD",
    "gateway": "stripe",
    "event_type": "payment.paid",
    "timestamp": "2026-01-01T00:00:00Z"
}