x402 Help and Documentation

Learn how Zahlen helps merchants observe and control payments made by software agents. This guide explains the x402 payment path, dashboard, CSV import, policy checks, replay protection, settlement and delivery tracking, reconciliation, and audit evidence.

Open x402 Merchant Dashboard x402 API Developer Guide All Help Documents

What x402 Does

x402 is a way for a website or online service to ask for payment through the same web request that asks for a protected resource. A software agent may request data, a report, an API result, or another paid service. The merchant can answer with an HTTP 402 payment challenge that explains what must be paid before the resource is released.

Zahlen adds payment intelligence and control around that exchange. It checks the payment request, applies merchant rules, records what happened, watches for risky behavior, and connects the payment to the final delivery result.

Zahlen is the intelligence and control layer Zahlen does not act as the customer's wallet and does not hold private keys. Payment verification and settlement can be performed through a separate facilitator or provider.

How an x402 Payment Moves Through Zahlen

  1. A software agent asks a merchant for a protected resource.
  2. The merchant returns an HTTP 402 challenge with the price and payment instructions.
  3. The agent submits a payment authorization or proof.
  4. Zahlen checks the merchant, endpoint, agent, wallet, amount, asset, network, and facilitator.
  5. Zahlen checks spending limits, recent activity, unusual behavior, and possible replay attempts.
  6. The verification adapter confirms whether the proof is valid.
  7. The payment is settled through the selected provider when settlement is required.
  8. The merchant releases or denies the requested resource.
  9. Zahlen connects the request, payment, settlement, and delivery into one history.

Each lifecycle uses a correlation ID. This ID helps Zahlen follow one request from its first payment challenge through the final delivery and reconciliation result.

Open the x402 Merchant Dashboard

Open the x402 Merchant Dashboard from the Zahlen Workspace or from the link at the top of this guide. You may be asked to sign in before the dashboard opens.

Your access is limited to your merchant and tenant The merchant list and dashboard results are scoped to the signed-in account. A merchant should not be able to view another merchant's x402 activity or audit evidence.

Runtime Status Badges

The badges at the top of the dashboard explain how the x402 service is operating.

Gateway StatusShows whether the isolated x402 gateway is available.
Live PaymentsShows whether live payment activity is allowed. Live payments remain disabled by default until production approval.
Append-only EvidenceConfirms that new evidence is added without replacing earlier records.
Safe testing comes first Zahlen can use a deterministic local facilitator to prove the complete lifecycle without sending real money. A real provider is connected only after the simulated path and its failure handling have been tested.

Merchant and Activity Window

Merchant

Select the merchant whose x402 activity you want to review. Changing the merchant also updates the CSV template link so imported records use the correct merchant scope.

Activity Window

Choose the last 24 hours, 7 days, or 30 days. The dashboard cards and tables update to match that time window.

Refresh

Select Refresh to load the newest recorded activity. A loading message appears while the dashboard is being updated.

Upload x402 Events CSV

The CSV feature lets a merchant load x402 lifecycle observations without building an API connection first. Files must use UTF-8 text, be no larger than 2 MB, and contain no more than 1,000 rows.

Download the correct example

  • No merchant selected: select Download example bundle. The ZIP contains a merchant example and a 1,000-row test file with a useful mix of successful and unsuccessful outcomes.
  • Merchant selected: select Download template. The CSV is prepared for the selected merchant.

Preview before import

  1. Select a CSV file from your computer.
  2. Select Preview CSV.
  3. Review each row's status, source event, correlation ID, record count, and reason codes.
  4. Correct invalid rows in the source file when needed, then preview the file again.
  5. Select Import valid rows when the preview is acceptable.

The Import valid rows button shows a spinner only while Zahlen is ingesting the file. Valid rows are appended. Invalid or duplicate rows are reported and do not overwrite earlier evidence.

Preview does not save records Preview checks the file and reports problems. You must select Import valid rows to append the accepted observations to the x402 evidence ledgers.

Activity Summary Cards

TransactionsResource requests represented in the selected time window.
Payment AttemptsSubmitted payment proofs or authorizations.
SettledPayments recorded as completed by the facilitator or provider.
DeliveredProtected resources recorded as released to the requesting agent.
Replay AttemptsRepeated payment proofs or requests that may be duplicates.
ExceptionsPayment and delivery histories that do not match as expected.

Use these cards as a quick starting point. Open the tables below them to understand the specific transactions behind each total.

Transaction Activity

This table provides one joined view of each x402 lifecycle. It shows the time, agent, wallet, resource, amount, policy result, settlement result, delivery result, and reconciliation state.

ResourceThe protected item or service the agent requested.
Amount and AssetWhat the agent was asked to pay and which payment asset was used.
PolicyWhether Zahlen allowed, denied, or sent the request for review.
ReconciliationWhether request, payment, settlement, and delivery agree.

Select Download in the Audit evidence column to save the evidence bundle for one correlation ID.

Agent and Wallet History

Zahlen treats an agent ID and wallet address as identities. The history table shows how often each identity appears, how many payment attempts it made, how many replays were detected, and when it was last seen.

Identity is not permission Recognizing an agent or wallet does not automatically allow a payment. The current merchant policy must still approve the merchant, endpoint, amount, asset, network, and other required conditions.

Policy Decisions

The policy engine gives each evaluated request an Allow, Deny, or Review result. The decision includes clear reason codes, supporting evidence, the policy version, and an anomaly score.

Known Agent and WalletChecks whether the identity is recognized or permitted.
Merchant and EndpointChecks whether the merchant and requested service are authorized.
Per-request LimitStops one request from exceeding its allowed amount.
Daily and Rolling LimitsControls total spending over a set period.
VelocityChecks whether too many attempts are happening too quickly.
Payment RestrictionsChecks the asset, network, and facilitator against merchant rules.
Service HealthStops or reviews payment when the merchant service is unhealthy.
Anomaly ScoreSummarizes how unusual or risky the request appears.
Review is not the same as approval A Review result means the request needs more attention. Do not release the protected resource until your approved process has resolved the review.

Duplicate and Replay Protection

A replay happens when the same payment proof or request is submitted again. This may be an accident, a delayed retry, or an attempt to receive the same paid service more than once.

Zahlen records replay evidence instead of replacing the original event. The Anomalies and Replay Attempts table shows the agent, wallet, anomaly score, replay count, and reason codes connected to the activity.

Do not delete the first record to clear a duplicate Original evidence is immutable. Corrections and later outcomes must be recorded as new events so the history remains complete and defensible.

Settlement, Delivery, and Reconciliation

Settlement answers whether the payment completed. Delivery answers whether the merchant released the protected resource. Reconciliation compares every stage and reports whether the full story makes sense.

Paid but Not DeliveredThe payment completed, but the resource was not released.
Delivered Without PaymentThe resource was released without confirmed payment.
Verification FailureThe submitted proof could not be accepted.
Repeated ProofThe same proof appeared more than once.
Unresolved SettlementThe final payment result is still missing or uncertain.
ReconciledThe request, payment, settlement, and delivery records agree.

Use the Reconciliation Exceptions table as a work queue. Review the exception code and correlation ID, then use the audit bundle to inspect the complete lifecycle.

Downloadable Audit Evidence

Each transaction can provide a ZIP evidence bundle tied to its correlation ID. The bundle is designed to show the recorded request, challenge, proof, verification, policy decision, settlement, delivery, replay evidence, and reconciliation result that exist for that lifecycle.

  1. Find the transaction in Transaction Activity.
  2. Confirm that the merchant, agent, amount, and resource match the issue you are reviewing.
  3. Select Download in the Audit evidence column.
  4. Keep the original ZIP unchanged when it will be used for an investigation or formal review.
  5. Record any correction as a new event rather than editing the earlier evidence.

Security and Privacy

  • Zahlen never stores private keys.
  • Wallet addresses and agent identifiers are treated as identities, not credentials.
  • Original x402 events remain append-only and are not overwritten by corrections.
  • Merchant and tenant boundaries are checked before data or evidence is returned.
  • Live payments are disabled by default until the production-hardening gate is approved.
  • Provider adapters keep Zahlen's records independent of one facilitator, processor, or network.
Share only what is needed Use correlation IDs and audit bundles carefully. Follow your company's security and data retention rules when sharing evidence with support, auditors, or payment providers.

Troubleshooting

The dashboard has no merchant options

Confirm that your signed-in account is connected to an active merchant. If you are using the example bundle, import its valid rows to create the isolated example merchant activity.

Import valid rows is disabled

Select a file and run Preview CSV first. The import button becomes available only after a successful preview finds rows that can be imported.

A row is marked invalid

Read the row's reason codes. Check required values, date and amount formats, lifecycle order, merchant scope, and allowed status values. Correct the source file and preview it again.

A row is marked duplicate

The event may already exist or may reuse proof evidence. Zahlen reports the duplicate and keeps the first record unchanged. Confirm the source event and correlation ID before retrying.

Dashboard totals did not change

Confirm that the import finished, select the correct merchant and activity window, and then select Refresh. Records outside the selected time window will not appear in the totals.

Audit evidence will not download

Confirm that you are signed in to the same merchant that owns the correlation ID. Also check that the transaction exists and that your session has not expired.

Recommended x402 Review Workflow

  1. Confirm the gateway and live-payment status badges.
  2. Select the correct merchant and activity window.
  3. Review Transactions, Payment Attempts, Settled, Delivered, Replays, and Exceptions.
  4. Open Transaction Activity and find the lifecycle you need to review.
  5. Check the agent and wallet history for earlier behavior.
  6. Read the policy decision, reason codes, and anomaly score.
  7. Review anomalies and repeated proofs.
  8. Compare settlement with delivery and check reconciliation exceptions.
  9. Review spend and velocity trends for broader context.
  10. Download the audit evidence bundle when a detailed review is needed.
Do not release a resource based on payment proof alone Use the verification, policy, settlement, replay, and service-health results required by your merchant policy. A submitted proof is evidence to check, not automatic approval.