Payments

Hanzo Commerce supports multiple payment providers including Stripe, PayPal, Authorize.net, and cryptocurrency payments via Ethereum and Bitcoin.

Payment Flow

Cart → Order → Authorize → Capture → Complete
                    ↓
              (Hold/Cancel)

Payment Statuses

Status	Description
`pending`	Payment initiated, awaiting action
`authorized`	Funds held, ready to capture
`captured`	Funds collected
`cancelled`	Authorization voided
`refunded`	Funds returned (partial or full)
`failed`	Payment failed

Supported Providers

Provider	Type	Features
Stripe	Card, ACH	Subscriptions, 3D Secure
PayPal	Wallet	Express checkout
Authorize.net	Card	Legacy integration
Ethereum	Crypto	ERC-20 tokens
Bitcoin	Crypto	BTC, Lightning

Stripe Integration

Setup

Configure Stripe in your environment:

STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

Authorize Payment

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

For payment intents (recommended):

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

3D Secure

Handle 3D Secure authentication:

{
  "status": "requires_action",
  "action": {
    "type": "redirect_to_url",
    "redirectUrl": "https://hooks.stripe.com/3d_secure_2/...",
    "returnUrl": "https://yourstore.com/checkout/complete"
  }
}

Capture Payment

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

Partial Capture

Capture less than the authorized amount:

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

PayPal Integration

Setup

PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
PAYPAL_MODE=live  # or sandbox

Create PayPal Order

curl -X POST https://api.hanzo.ai/checkout/authorize \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_abc123",
    "paymentMethod": "paypal",
    "returnUrl": "https://yourstore.com/checkout/complete",
    "cancelUrl": "https://yourstore.com/checkout/cancel"
  }'

Response:

{
  "status": "requires_action",
  "action": {
    "type": "redirect_to_url",
    "redirectUrl": "https://www.paypal.com/checkoutnow?token=..."
  },
  "paypalOrderId": "5O190127TN364715T"
}

Capture After Approval

curl -X POST https://api.hanzo.ai/checkout/capture \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_abc123",
    "paypalOrderId": "5O190127TN364715T"
  }'

Cryptocurrency Payments

Ethereum

curl -X POST https://api.hanzo.ai/checkout/authorize \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_abc123",
    "paymentMethod": "ethereum",
    "currency": "ETH"
  }'

Response:

{
  "status": "pending",
  "paymentAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
  "amount": "0.0234",
  "currency": "ETH",
  "expiresAt": "2024-01-15T11:00:00Z",
  "qrCode": "data:image/png;base64,..."
}

Bitcoin

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

Response:

{
  "status": "pending",
  "paymentAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkf...",
  "amount": "0.00123456",
  "currency": "BTC",
  "expiresAt": "2024-01-15T11:00:00Z"
}

Monitor Blockchain Transactions

Payments are automatically confirmed when transactions are detected:

{
  "status": "confirmed",
  "txHash": "0x123abc...",
  "confirmations": 12,
  "blockNumber": 18500000
}

Refunds

Full Refund

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

Partial Refund

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

Webhooks

Configure webhooks to receive payment events:

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

Webhook Payload

{
  "id": "evt_123",
  "type": "payment.captured",
  "data": {
    "paymentId": "pay_xyz789",
    "orderId": "order_abc123",
    "amount": 6578,
    "currency": "USD",
    "provider": "stripe"
  },
  "createdAt": "2024-01-15T10:35:00Z"
}

Verify Webhook Signature

import "github.com/hanzoai/commerce/util/webhook"

func handleWebhook(c *gin.Context) {
    payload, err := io.ReadAll(c.Request.Body)
    signature := c.GetHeader("X-Hanzo-Signature")

    if err := webhook.Verify(payload, signature, webhookSecret); err != nil {
        c.JSON(401, gin.H{"error": "invalid signature"})
        return
    }

    // Process event
}

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

const commerce = new Commerce({ apiKey: 'your_key' })

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

// Handle 3D Secure if needed
if (payment.status === 'requires_action') {
  window.location.href = payment.action.redirectUrl
}

// Capture payment
await commerce.checkout.capture({
  orderId: 'order_abc123',
  paymentId: payment.id
})

// Refund
await commerce.checkout.refund({
  orderId: 'order_abc123',
  paymentId: payment.id,
  amount: 1500,
  reason: 'partial_return'
})

Go

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

// Capture payment
err = client.Checkout.Capture(ctx, &sdk.CaptureInput{
    OrderID:   "order_abc123",
    PaymentID: payment.ID,
})

// Refund
err = client.Checkout.Refund(ctx, &sdk.RefundInput{
    OrderID:   "order_abc123",
    PaymentID: payment.ID,
    Amount:    1500,
    Reason:    "partial_return",
})

Security Best Practices

Never log or store full payment tokens or card numbers. Use tokenization provided by payment processors.

PCI Compliance: Use tokenized payment methods

Webhook Validation: Always verify webhook signatures

Idempotency: Use idempotency keys for payment requests

Amount Verification: Verify amounts server-side before capture

Fraud Detection: Enable provider fraud protection features

On this page