Payment experiences

A payment experience represents something your business wants to collect payment for. Create it once and provide the appropriate payment URL depending on who will complete it.

People can open a hosted checkout, while AI agents can use a programmatic payment URL. Both entry points represent the same payment, so the amount, reference and resulting payment state remain consistent regardless of how it is completed.

Create a payment

For a one-time payment, create a payment link with type set to charge.

curl --request POST \
  --url https://api.mitu.ai/v1/payment-links \
  --header "x-api-key: $MITU_API_KEY" \
  --header "Idempotency-Key: payment-ORDER-8841" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "charge",
    "amount": 25.00,
    "currency": "USD",
    "description": "Order 8841",
    "reference": "ORDER-8841",
    "expiresAt": "2026-10-01T00:00:00Z",
    "paymentMethods": ["x402", "mpp_spt"],
    "metadata": {
      "order_id": "8841"
    }
  }'

Parameters

Send an Idempotency-Key header so a retried request does not create a second link. For 24 hours, a request with the same key and body returns the original link. The same key with a different body returns 409. See Idempotency.

Payment URLs

Creating a payment returns separate URLs for human and agent payers.

{
  "id": "pay_n8d7piu1yc6h",
  "type": "charge",
  "amount": "25.00",
  "currency": "USD",
  "reference": "ORDER-8841",
  "url": {
    "checkout": "https://mitu.ai/pay/pay_n8d7piu1yc6h",
    "agent": "https://api.mitu.ai/pay/pay_n8d7piu1yc6h"
  }
}

Use url.checkout when a person should complete the payment and url.agent when an AI agent should complete it programmatically. Do not interchange them. The checkout URL serves a human payment experience, while the agent URL participates in the agent payment flow.

Both URLs belong to the same payment. You do not need to create a second payment if the payer changes from a person to an AI agent or vice versa.

Human payments

Send url.checkout through the channel where your customer is already interacting with your business, such as your website, email, SMS or WhatsApp. The customer opens the hosted checkout, reviews what they are paying for and completes the payment using an available payment method.

Your application does not need to build a separate checkout experience to collect the payment. Track the resulting payment through the API and verified webhook events rather than relying on the state shown in the customer’s browser.

Agent payments

Give url.agent to an AI agent when the payment should be completed programmatically. The agent receives the payment requirement and completes it using one of the supported methods available for that payment.

Mitu handles the underlying agent payment flow. Your application does not need to implement x402 or MPP simply because an AI agent may complete the payment.

See Agent payments for the payment flow and supported methods.

Payment types

Charge

Use charge for a one-time payment where the amount is already known. This works well for orders, bookings, deposits, service fees and other transactions that should be paid once.

{
  "type": "charge",
  "amount": 25.00,
  "currency": "USD",
  "reference": "ORDER-8841"
}

Subscription

Use subscription when the payer is subscribing to a recurring plan. The amount and currency come from the associated subscription plan rather than being configured directly on the payment.

Use planId for a specific plan, or allow the payer to choose from multiple plans where supported.

See Subscriptions for plans, billing intervals and subscription lifecycle.

Session

Use session when the payer should fund an amount that can be used across an ongoing interaction rather than completing a separate payment for every action.

Configure the maximum amount that can be funded using sessionMaxDeposit and optionally set when the session expires. This model works well for longer or metered interactions where multiple paid actions happen as part of the same session.

Per request

Use per_request when payment is associated with calls to an API path. Configure the relevant path using endpointPattern.

This is useful when payment is tied directly to API usage rather than a standalone order or checkout. If your main goal is charging AI agents for API calls, see Sell your API to AI agents.

Reconcile payments

Set reference to an identifier your own system already understands. When the payment completes, use that reference to associate the payment with the corresponding order, booking, invoice or other business record.

For example:

ORDER-8841
BOOKING-9832
INV-2026-441

Do not rely on a browser redirect or an AI client’s response to decide that a payment has completed. Use a verified payment event or retrieve the current payment state through the API.

Keeping your own reference on the payment also means your reconciliation does not depend entirely on storing and looking up Mitu’s payment identifier.

See Webhooks and Events for handling payment events.

Payment experiences and fulfilment

A completed payment tells you that money was received. It does not necessarily mean the underlying order, booking, service or other business action has been fulfilled.

Keep payment state and fulfilment state separate in your system. After payment completes, use your reference to determine what the payment belongs to and continue the appropriate business workflow.

For paid API operations where payment happens before your API is called, see Agent payments.

Related