Payments & connected services

Architecture and responsibilities

1. 01

   Report API and orders

   Bind price, payment asset, recipient and expiry to the report.

   Merchant backend / Order DB
2. 02

   Payment-term handling

   Select supported chains and assets and display terms for review.

   @hazbase/kit/x402
3. 03

   Authentication and payment

   Submit payment with an authenticated session and operation authorization.

   @hazbase/kit/wallet / @hazbase/auth
4. 04

   Settlement and access

   Verify payment against the order server-side and grant access once.

   Payment verification / Access DB

Example data model

Map application records to the data managed by the chain or APIs. Field names and values below illustrate the application model for this architecture.

Processing flow

1. 1

   Create a payment request for the order

   Return payment terms for the report request. Payment-request creation and merchant configuration follow the connected service’s integration contract. The Wallet SDK used here does not register arbitrary merchant orders.

   Merchant API → HTTP 402 / paymentRequestId
2. 2

   Validate and display the terms

   Parse the response and check chain, asset, recipient, resource URL and amount limit against policy. Display the report and amount and obtain the user’s payment confirmation.

   summarizeX402Request / isX402RequestExpired
3. 3

   Pay with an authenticated wallet

   Obtain emailSession, smartAccountAddress, deviceBindingId and highTrustToken through the authentication flow. Send the approved amount and recipient as expectedAmountAtomic and expectedPayTo.

   payX402WithHazbaseWallet(input)
4. 4

   Track the same payment attempt

   If processing continues, retain paymentAttemptId and query its status. Distinguish submitted, verified and settled states; a slow response must not trigger a new payment.

   getX402HazbaseWalletPaymentStatus({ emailSession, paymentRequestId, paymentAttemptId })
5. 5

   Verify on the server and grant access

   The merchant server verifies trusted payment status or proof against the order, purchaser, amount, asset and recipient. Save access using a DB transaction and unique constraint, then return the report.

   Server payment verification → accessGrant → report response

Before using the code

• Provide a valid paymentRequestId issued by the connected service and its supported chain, asset and merchant recipient.
• Integrate a payment confirmation screen and the session, device registration and operation authorization required by the Wallet API.
• Keep authentication tokens out of logs, URLs and public configuration. Pass values from that user’s authentication flow in auth.

npm install --save-exact @hazbase/kit@0.9.0 ethers@6.16.0

The TypeScript functions below are called from your application with the appropriate connections, permissions and data. Integrate the UI, persistence and recovery using the architecture above.

Inspect payment terms and submit the approved request

Use inspectReportPayment to extract the terms, display them for confirmation, then call payApprovedReport. payload is the JSON from the payment service; policy contains your service’s accepted terms.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

import { summarizeX402Request, isX402RequestExpired, type HazbaseX402Request } from '@hazbase/kit/x402';
import { createHazbaseWalletClient, type PayX402WithHazbaseWalletInput } from '@hazbase/kit/wallet';
import { getAddress } from 'ethers';

export function inspectReportPayment(
  payload: Record<string, unknown>,
  resourceUrl: string,
  policy: { network: string; asset: string; payTo: string; maxAmountAtomic: bigint },
) {
  const request = summarizeX402Request(payload, { sourceUrl: resourceUrl }, {
    networks: [policy.network],
    assets: [{ address: policy.asset }],
    requirePayTo: true,
  });
  if (!request) throw new Error('Unsupported payment request.');
  const terms = request.requirement;
  if (terms.resource !== resourceUrl || getAddress(terms.payTo) !== getAddress(policy.payTo)) {
    throw new Error('Payment does not match the requested service.');
  }
  const amount = BigInt(terms.amountAtomic);
  if (amount <= 0n || amount > policy.maxAmountAtomic) throw new Error('Amount is outside policy.');
  if (isX402RequestExpired(request, Date.now())) throw new Error('Payment request expired.');
  return request;
}

export async function payApprovedReport(
  request: HazbaseX402Request,
  auth: Pick<PayX402WithHazbaseWalletInput,
    'emailSession' | 'smartAccountAddress' | 'deviceBindingId' | 'highTrustToken'>,
) {
  // Call only after the user confirms the displayed resource and payment terms.
  if (isX402RequestExpired(request, Date.now())) throw new Error('Payment request expired.');
  const wallet = createHazbaseWalletClient();
  return wallet.payX402WithHazbaseWallet({
    ...auth,
    paymentRequestId: request.paymentRequestId,
    expectedAmountAtomic: request.requirement.amountAtomic,
    expectedPayTo: request.requirement.payTo,
    waitForReceipt: false,
  });
}

Implementation considerations

Extending the architecture

Related API and SDK reference