Guide

How to add payments to an AI agent, step by step

How to add payments to an AI agent, step by step

How to add payments to an AI agent, step by step

From sandbox keys to a live purchase: create a session, collect the card, get the user's passkey approval, pay with a one-time token, report the result.

Guide: How to Add Payments to an AI Agent

Once an agent has found the right product at the right price and the user has agreed to buy it, it needs a way to pay. That step means handling card data your app shouldn't store, getting an approval the card issuer will trust, and completing checkout on another company's website.

This guide covers the six steps from sandbox keys to a live purchase. Your servers never handle a card number.

Before you start

You need a Prava account. Sign up on the Prava dashboard with your email or Google. New keys are sandbox keys, so nothing you do there charges a real card.

Step 1: Get your keys

In the dashboard, enter your company name and Prava issues two keys:

  • pk_test_..., a publishable key for the browser, used to start the SDK

  • sk_test_..., a secret key that stays on your server and creates sessions

Step 2: Create a session on your server

A session is one checkout: who's paying, how much, and for what. The quickstart has the full request and response.

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "user@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": {
          "name": "Your Store",
          "url": "https://yourstore.com",
          "country_code_iso2": "US"
        },
        "product_details": [{
          "description": "Example Product",
          "unit_price": "49.99",
          "quantity": 1
        }]
      }]
    }
  }'
curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "user@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": {
          "name": "Your Store",
          "url": "https://yourstore.com",
          "country_code_iso2": "US"
        },
        "product_details": [{
          "description": "Example Product",
          "unit_price": "49.99",
          "quantity": 1
        }]
      }]
    }
  }'
curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "user@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": {
          "name": "Your Store",
          "url": "https://yourstore.com",
          "country_code_iso2": "US"
        },
        "product_details": [{
          "description": "Example Product",
          "unit_price": "49.99",
          "quantity": 1
        }]
      }]
    }
  }'

The response includes a session_token and an iframe_url. Sessions last 15 minutes, and you should use one per checkout.

Step 3: Collect the card

Pick one of two modes. The docs compare them in integration modes.

  • Hosted: send the user to iframe_url. Prava brings them back to your callback_url when they're done. No frontend SDK needed.

  • Embedded: set integration_type: "embedding" on the session and mount the card form inside your app.

import { PravaSDK } from '@prava-sdk/core';

const prava = new PravaSDK({ publishableKey: 'pk_test_xxx' });

await prava.collectPAN({
  sessionToken: session.session_token,
  iframeUrl: session.iframe_url,
  container: '#card-form',
  onSuccess: (data) => console.log(`Collected: ${data.brand} •••• ${data.last4}`),
  onError: (err) => console.error(err.code, err.message),
});
import { PravaSDK } from '@prava-sdk/core';

const prava = new PravaSDK({ publishableKey: 'pk_test_xxx' });

await prava.collectPAN({
  sessionToken: session.session_token,
  iframeUrl: session.iframe_url,
  container: '#card-form',
  onSuccess: (data) => console.log(`Collected: ${data.brand} •••• ${data.last4}`),
  onError: (err) => console.error(err.code, err.message),
});
import { PravaSDK } from '@prava-sdk/core';

const prava = new PravaSDK({ publishableKey: 'pk_test_xxx' });

await prava.collectPAN({
  sessionToken: session.session_token,
  iframeUrl: session.iframe_url,
  container: '#card-form',
  onSuccess: (data) => console.log(`Collected: ${data.brand} •••• ${data.last4}`),
  onError: (err) => console.error(err.code, err.message),
});

You only ever get the card brand, last four digits, expiry and an enrollment ID. You can match the form to your brand in the dashboard: logo, name and color.

Step 4: Get the user's approval

The user confirms the purchase with a passkey: Face ID, Touch ID or a security key. The first time on a new device, their bank may also send a one-time code, and a passkey is created for next time.

Step 5: Pay

Once the user approves, get the payment result. It contains a single-use token locked to the store and amount in the session, plus a one-time CVV. The token comes from Visa Intelligent Commerce or Mastercard Agent Pay, depending on the user's card. Use it at the store's checkout with your own automation, or let Prava complete the checkout for you: in 5 to 20 seconds on UCP stores, and in 10 to 20 seconds on most other store websites with Prava's Browser Harness.

If a checkout fails, start a new session. Tokens can't be reused.

Step 6: Report the result

Always report whether the store approved or declined the payment, so the user and the card network both have the final status.

To hear about payments, cards and spending limits without polling, set up webhooks in the dashboard. Events are signed, retried for up to 72 hours and can be replayed for 30 days.

Going live

When your sandbox runs pass, apply for production access from the dashboard and track the application there. Once you're approved, create live keys. Live keys only work against the production API, and test keys only against the sandbox.

Building with a coding agent?

The prava-sdk-integration skill walks Claude Code, Codex and other coding agents through these steps.

Adding product search and checkout

Payments are one part of Prava's API. The Shop API finds products and returns exact quotes across UCP (Universal Commerce Protocol) stores and merchants like Macy's, and Prava can complete checkout on the store for you. With one integration, your agent can go from a product search to a confirmed order. See how the pieces fit together.

Summary

  • Adding payments to an agent takes six steps: keys, a session, the card form, the user's approval, the payment, and a status report.

  • Your servers never touch card data. You get a one-time token for the approved store and amount, and a one-time CVV.

  • Build in the sandbox, then apply for production from the dashboard.

FAQ

Do I need to be PCI compliant? No. Card details go into Prava's secure form and vault, never your servers.

Which languages are supported? Node, Python and Java on the backend; JavaScript, React and React Native on the frontend.

Does the session currency have to match the card's country? No. The card network handles conversion.

How long does integration take? Most teams integrate in an afternoon.

Sources

Prava team

Copyright © 2026 Prava Payments Inc. All rights reserved

Copyright © 2026 Prava Payments Inc. All rights reserved