Payments API

Record payments, manage payment methods, process refunds, and handle checkout sessions.

Record Payment


POST /api/billing/payments
Content-Type: application/json

Body

Field	Type	Required	Description
`invoiceId`	UUID	Yes	Invoice being paid
`amount`	string	Yes	Payment amount
`paymentMethod`	string	Yes	`stripe`, `xendit`, `lemonsqueezy`, `bank_transfer`, `manual`
`providerReference`	string	No	External payment ID

Response 201 Created

List Payments


GET /api/billing/payments

Create Checkout Session

Start a hosted checkout flow with a payment provider:

Stripe


POST /api/billing/checkout/stripe
Content-Type: application/json
 
{
  "invoiceId": "01JQX...",
  "successUrl": "https://app.example.com/success",
  "cancelUrl": "https://app.example.com/cancel"
}

Returns a Stripe Checkout Session URL.

Xendit


POST /api/billing/checkout/xendit
Content-Type: application/json
 
{
  "invoiceId": "01JQX...",
  "successUrl": "https://app.example.com/success"
}

Returns a Xendit invoice URL.

Refunds


POST /api/billing/refunds
Content-Type: application/json
 
{
  "paymentId": "01JQX...",
  "amount": "25.00",
  "reason": "Partial refund for unused period"
}

Payment Methods

List Customer Payment Methods


GET /api/billing/payment-methods?customerId=01JQX...

Add Payment Method


POST /api/billing/payment-methods
Content-Type: application/json
 
{
  "customerId": "01JQX...",
  "type": "stripe",
  "providerMethodId": "pm_xxx",
  "isDefault": true
}

Credits

Add Store Credit


POST /api/billing/credits
Content-Type: application/json
 
{
  "customerId": "01JQX...",
  "amount": "50.00",
  "description": "Goodwill credit"
}

Issue Credit Note


POST /api/billing/credit-notes
Content-Type: application/json
 
{
  "invoiceId": "01JQX...",
  "amount": "25.00",
  "reason": "Service credit"
}