Payment Module

The Payment module orchestrates payment processing across multiple providers with a unified interface for authorization, capture, and refunds.

Payment Flow

Authorize ──► Hold funds on customer's payment method
    │
    ├── Capture ──► Collect the held funds
    │
    ├── Cancel  ──► Release the hold
    │
    └── (timeout) ──► Auto-void after configurable window

Supported Providers

Provider	Methods	Features
Stripe	Cards, ACH, Apple Pay, Google Pay	3D Secure, subscriptions
PayPal	PayPal balance, cards	Express checkout
Authorize.net	Cards	Legacy support
Ethereum	ETH, ERC-20 tokens	On-chain verification
Bitcoin	BTC, Lightning	QR code payment

Data Model

{
  "id": "pay_xyz789",
  "orderId": "order_abc123",
  "provider": "stripe",
  "status": "captured",
  "amount": 6791,
  "currency": "USD",
  "providerPaymentId": "pi_1234567890",
  "capturedAt": "2025-01-15T10:35:00Z",
  "metadata": {
    "stripePaymentIntentId": "pi_1234567890"
  }
}

API Examples

Authorize a Payment

curl -X POST https://api.hanzo.ai/checkout/authorize \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_abc123",
    "paymentMethod": "stripe",
    "paymentIntentId": "pi_1234567890"
  }'

const payment = await commerce.checkout.authorize({
  orderId: 'order_abc123',
  paymentMethod: 'stripe',
  paymentIntentId: 'pi_1234567890',
})

if (payment.status === 'requires_action') {
  window.location.href = payment.action.redirectUrl
}

payment, err := client.Checkout.Authorize(ctx, &sdk.AuthorizeInput{
    OrderID:       "order_abc123",
    PaymentMethod: "stripe",
    PaymentIntentID: "pi_1234567890",
})

Capture Payment

curl -X POST https://api.hanzo.ai/checkout/capture \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "order_abc123", "paymentId": "pay_xyz789"}'

Issue a Refund

curl -X POST https://api.hanzo.ai/checkout/refund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_abc123",
    "paymentId": "pay_xyz789",
    "amount": 2999,
    "reason": "customer_request"
  }'

Webhook Events

curl -X POST https://api.hanzo.ai/webhook \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks",
    "events": [
      "payment.authorized",
      "payment.captured",
      "payment.refunded",
      "payment.failed"
    ]
  }'

Configuration

payment:
  providers:
    stripe:
      enabled: true
      secret_key: ${STRIPE_SECRET_KEY}
      webhook_secret: ${STRIPE_WEBHOOK_SECRET}
    paypal:
      enabled: true
      client_id: ${PAYPAL_CLIENT_ID}
      client_secret: ${PAYPAL_CLIENT_SECRET}
      mode: live  # sandbox | live
    ethereum:
      enabled: false
      rpc_url: ${ETH_RPC_URL}
  auto_capture: false         # capture immediately on authorize
  capture_deadline_days: 7    # void uncaptured after N days

Never log or store raw card numbers or CVVs. Always use tokenized payment methods provided by the payment processor.

On this page