Developer docs v0.1.0

Agentic flows

End-to-end sequences for agent payments, from the simplest to the most automated. Each says what Payware supports today and what is planned. In the first two a person stays in control, the third is unattended and needs your own limits, and none of them depends on a protocol that is still changing. The last three are planned.

The agent never touches a card. It creates a payment link, shares it, and learns the result from an event.

  1. The agent calls POST /v1/payment-links with an amount, currency and optional description, return_url and expires_in_days, sending an Idempotency-Key.
  2. The agent shows or sends the link's url to the person (message, email or chat).
  3. The person opens the page, gives an email and phone number, and pays by card on NETOPIA Payments' secure page, or with Apple Pay or Google Pay where available. The bank asks for authentication when it needs to.
  4. The link becomes completed, a payment is recorded with the payer's email, and your webhook endpoint receives payment.succeeded or payment.failed.

Use this whenever a human should make the final decision: it is the human-present purchase described in the protocols, with the checkout hosted by Payware.

Same shape, for a recurring plan. Create a subscription link with kind: "subscription" and a price_id. The payer saves a card on NETOPIA Payments' secure page, Payware creates the customer, starts the subscription and charges the first period. Wallets are not offered here, because renewals need a saved card. See Subscription links.

3. A merchant's agent charges a stored card (available)

For back-office automation, such as a setup fee or a top-up for a customer who has already enrolled a card.

  1. The customer enrolls a card once through hosted enrollment (see Enrollments), which yields an instrument.
  2. The agent calls POST /v1/payments with the customer_id and an Idempotency-Key. See Standalone payments.
  3. The first response may be pending; the final result arrives as payment.succeeded or payment.failed. A decline is final and is never retried, so an agent that wants another attempt creates a new payment with a new key.

This is unattended and moves money, so keep your own limits around it until Payware can enforce them for you.

4. A customer lets an agent spend within limits (in development)

The customer approves an amount, a budget and an expiry for an agent on a page Payware hosts, on a device they control. Each later charge is checked against that approval, and Payware keeps it as evidence for disputes. It follows the same idea as an open mandate in AP2 and Verifiable Intent: constraints signed once by the person, then used by the agent without them. Payware will check each charge itself, rather than rely on the agent to stay inside the limit.

5. An assistant sells your products (in development)

An AI assistant such as ChatGPT or Gemini discovers a merchant, builds a cart and completes the checkout on the buyer's behalf, using ACP or UCP. The merchant stays merchant of record. Payware's part would be to accept a scoped, single-use payment credential, limited to one merchant, one checkout, a maximum amount and an expiry, so the card number never reaches the assistant or Payware. This depends on NETOPIA Payments providing the card vault and credential flow.

6. An agent pays per use (in development)

For software paying for an API call, a page or a tool: the seller answers 402, the agent pays, and the seller delivers once settlement is confirmed. Settlement happens in stablecoin through a licensed partner, so Payware never holds the funds. This needs a partner and a regulatory review first, so it comes last.

What every flow has in common

  • A hosted step for anything sensitive. Card entry, bank challenges and approvals happen on a page the person controls, never inside the agent's conversation.
  • One idempotency key per intent. Agents retry; the key makes the retry harmless.
  • Events over guesses. A response saying a payment started is not a result. Wait for the event or read the status.
  • Evidence. Keep who asked, who approved and what was charged. Payware's events and payments list are the record on its side.