Documentation

Base URL: /api/v1

curl -X POST https://pay.amuix.com/api/v1/payment-intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order_123" \
  -H "Content-Type: application/json" \
  -d '{"plan_code":"pro_month","customer_id":"cus_xxx"}'

Introduction

Amuix Pay is the payment platform for the Amuix ecosystem. It owns checkout, payment intents, billing, ledger, and webhooks. Acquirers are adapters.

Authentication

Use publishable keys (pk_test_…) in the browser and secret keys (sk_test_…) on the server. Never expose secret keys to clients.

Payment Intents

POST /api/v1/payment-intents with Idempotency-Key. Prefer plan_code or checkout_session_id so the server sets the amount.

Confirm

POST /api/v1/payment-intents/:id/confirm with payment_method. Statuses include requires_action, processing, succeeded, failed.

Cards & wallets

Cards are tokenised. Apple Pay / Google Pay / Samsung Pay buttons render only when the device/browser reports availability.

Instant EFT

Bank redirect flows complete asynchronously. Redirect is not proof of payment — webhooks/server confirmation update status.

Refunds

POST /api/v1/refunds with payment_id and optional amount. Partial refunds are supported; over-refunds are rejected.

Webhooks

Outgoing events are signed with X-Amuix-Signature and X-Amuix-Timestamp. Incoming provider webhooks verify signatures before state changes.

Testing

Use /test for sandbox or Paystack test keys. Sandbox scenarios: success, declined, 3ds, insufficient_funds, timeout, instant_eft. With Paystack configured, checkout redirects to Paystack hosted payment.

Paystack

Set PAYSTACK_SECRET_KEY and NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY. Webhook: POST /api/v1/webhooks/paystack (HMAC SHA512). Callback verifies amount and currency server-side before entitlements.