Payment API

The Payment API handles payment processing across multiple providers including Stripe, PayPal, Bitcoin, and Ethereum. It supports both direct charges and authorize-then-capture flows.

Payment Structure

{
  "id": "pay_xyz789",
  "orderId": "order_abc123",
  "provider": "stripe",
  "status": "captured",
  "amount": 5638,
  "currency": "USD",
  "method": {
    "type": "card",
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2025
  },
  "providerRef": "pi_3N8abc123def456",
  "authorizedAt": "2024-06-15T10:00:00Z",
  "capturedAt": "2024-06-15T10:05:00Z",
  "metadata": {},
  "createdAt": "2024-06-15T10:00:00Z"
}

Payment Flow

Flow	Description
Charge	Single-step: authorize and capture immediately
Authorize + Capture	Two-step: authorize first, capture later (e.g., at fulfillment)

Supported Providers

Provider	Methods	Currencies
`stripe`	Card, Apple Pay, Google Pay	135+ currencies
`paypal`	PayPal balance, card via PayPal	25+ currencies
`bitcoin`	On-chain BTC, Lightning Network	BTC
`ethereum`	ETH, ERC-20 tokens	ETH, USDC, USDT

Endpoints

Charge

POST /checkout/charge

Authorize and capture payment in a single step. Creates an order from the cart.

curl -X POST https://api.hanzo.ai/checkout/charge \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": "cart_abc123",
    "provider": "stripe",
    "paymentMethodId": "pm_card_visa",
    "metadata": {
      "source": "web-checkout"
    }
  }'

Response:

{
  "orderId": "order_abc123",
  "paymentId": "pay_xyz789",
  "status": "captured",
  "amount": 5638,
  "currency": "USD",
  "provider": "stripe",
  "providerRef": "pi_3N8abc123def456"
}

Authorize

POST /checkout/authorize

Authorize payment without capturing. Funds are held but not transferred.

curl -X POST https://api.hanzo.ai/checkout/authorize \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": "cart_abc123",
    "provider": "stripe",
    "paymentMethodId": "pm_card_visa"
  }'

Response:

{
  "orderId": "order_abc123",
  "paymentId": "pay_xyz789",
  "status": "authorized",
  "amount": 5638,
  "currency": "USD",
  "expiresAt": "2024-06-22T10:00:00Z"
}

Authorizations typically expire after 7 days. Capture before expiry to complete the charge. Expired authorizations release the held funds.

Capture

POST /checkout/capture/:id

Capture a previously authorized payment.

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

Response:

{
  "id": "pay_xyz789",
  "status": "captured",
  "amount": 5638,
  "capturedAt": "2024-06-17T08:00:00Z"
}

You can capture a partial amount. The remaining authorization is automatically voided.

List Payments

GET /payment

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`display`	number	Items per page (default: 20, max: 100)
`sort`	string	Sort field (e.g. `createdAt:desc`)
`status`	string	`authorized`, `captured`, `refunded`, `failed`
`provider`	string	Filter by provider
`orderId`	string	Filter by order
`since`	string	Created after ISO date

curl "https://api.hanzo.ai/payment?status=captured&provider=stripe&sort=createdAt:desc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 1283,
  "models": [
    {
      "id": "pay_xyz789",
      "orderId": "order_abc123",
      "provider": "stripe",
      "status": "captured",
      "amount": 5638,
      "currency": "USD",
      "createdAt": "2024-06-15T10:00:00Z"
    }
  ]
}

Get Payment

GET /payment/:id

curl https://api.hanzo.ai/payment/pay_xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Refund Payment

POST /payment/:id/refund

Issue a full or partial refund on a captured payment.

curl -X POST https://api.hanzo.ai/payment/pay_xyz789/refund \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2999,
    "reason": "Item returned"
  }'

Response:

{
  "id": "refund_abc456",
  "paymentId": "pay_xyz789",
  "amount": 2999,
  "status": "processed",
  "reason": "Item returned",
  "provider": "stripe",
  "providerRef": "re_3N8def789ghi012",
  "createdAt": "2024-06-20T14:00:00Z"
}

Crypto Payments

Bitcoin

curl -X POST https://api.hanzo.ai/checkout/charge \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": "cart_abc123",
    "provider": "bitcoin",
    "network": "mainnet"
  }'

Response:

{
  "orderId": "order_btc001",
  "paymentId": "pay_btc789",
  "status": "pending",
  "amount": 5638,
  "crypto": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "amountBtc": "0.00082",
    "network": "mainnet",
    "expiresAt": "2024-06-15T10:30:00Z"
  }
}

Ethereum

curl -X POST https://api.hanzo.ai/checkout/charge \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": "cart_abc123",
    "provider": "ethereum",
    "token": "USDC"
  }'

Response:

{
  "orderId": "order_eth001",
  "paymentId": "pay_eth789",
  "status": "pending",
  "amount": 5638,
  "crypto": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "amountToken": "56.38",
    "token": "USDC",
    "chainId": 1,
    "expiresAt": "2024-06-15T10:30:00Z"
  }
}

Webhooks

Payment events are delivered via Webhooks. Key payment events:

Event	Description
`payment.authorized`	Payment successfully authorized
`payment.captured`	Payment captured
`payment.failed`	Payment attempt failed
`payment.refunded`	Refund processed

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

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

// Charge (single-step)
const charge = await commerce.checkout.charge({
  cartId: 'cart_abc123',
  provider: 'stripe',
  paymentMethodId: 'pm_card_visa'
})

// Authorize + Capture (two-step)
const auth = await commerce.checkout.authorize({
  cartId: 'cart_abc123',
  provider: 'stripe',
  paymentMethodId: 'pm_card_visa'
})

const captured = await commerce.checkout.capture(auth.paymentId, {
  amount: 5638
})

// Refund
await commerce.payments.refund('pay_xyz789', {
  amount: 2999,
  reason: 'Item returned'
})

// Crypto payment
const btcPayment = await commerce.checkout.charge({
  cartId: 'cart_abc123',
  provider: 'bitcoin',
  network: 'mainnet'
})

Go

charge, err := client.Checkout.Charge(ctx, &sdk.ChargeInput{
    CartID:          "cart_abc123",
    Provider:        "stripe",
    PaymentMethodID: "pm_card_visa",
})

auth, err := client.Checkout.Authorize(ctx, &sdk.AuthorizeInput{
    CartID:          "cart_abc123",
    Provider:        "stripe",
    PaymentMethodID: "pm_card_visa",
})

captured, err := client.Checkout.Capture(ctx, auth.PaymentID, &sdk.CaptureInput{
    Amount: 5638,
})

refund, err := client.Payments.Refund(ctx, "pay_xyz789", &sdk.RefundInput{
    Amount: 2999,
    Reason: "Item returned",
})

On this page