prava-agent-payments

Prava — Agent Payment Collection

Collect card payments on behalf of users via the Prava CLI. The user approves once, then the agent can create payment sessions and receive tokenized card credentials to complete purchases.

When to Activate

Activate this skill when:

• The user asks you to buy something, make a purchase, or pay for something
• The user asks to set up Prava or connect their card for agent purchases
• The user says "pay with Prava", "use Prava", or similar

Prerequisites: CLI Installation

Before running any prava command, check if the CLI is installed:

which prava

If not found, install it:

npm install -g @prava-sdk/cli

If the install fails due to permissions, try:

sudo npm install -g @prava-sdk/cli

After install, verify:

prava --version

Version Check (automatic)

The CLI automatically checks for updates on every API call. Watch for two notices in command output:

• CLI update notice — Run npm update -g @prava-sdk/cli. If the notice says "Critical update required", you MUST update before continuing.
• Skill update notice — Run npx skills update prava-agent-payments -g to get the latest skill instructions. Do this before continuing with any payment flow.

Do not run separate version-check commands — the CLI handles this automatically.

Steps to Collect a Payment

1. Ensure agent is linked

Run: prava status

Decision tree:

• "active" — Move to step 2.
• "pending" — Remind user to open the approval URL and approve. IMMEDIATELY run prava setup poll — do NOT wait for user to respond.
• "No agent configured" — Run prava setup. Show the linking URL to the user. IMMEDIATELY run prava setup poll — do NOT wait for user to respond or confirm. Read cli-setup reference.

IMPORTANT: If the user's original intent was to make a purchase and you just completed setup, proceed IMMEDIATELY to step 2.

2. Pre-check: confirm purchase context

Before calling prava sessions create, confirm you have ALL of:

• Merchant identified (name and URL)
• Product(s) finalized (with real, discovered prices)
• Total amount as string (e.g., "8.50")
• Currency code (e.g., USD)
• Clear description for each product

If ANY are missing, gather them FIRST through your normal discovery flow. Do NOT call prava sessions create with guessed or hallucinated values.

3. Collect payment

prava sessions create \
  --total-amount "8.50" --currency USD \
  --merchant-name "Blue Bottle Coffee" \
  --merchant-url "https://bluebottlecoffee.com" \
  --merchant-country US \
  --product '{"description":"1x Latte","unit_price":"5.00"}' \
  --product '{"description":"1x Croissant","unit_price":"3.50"}'

The command:

1. Creates the session on the backend.
2. Prints a payment URL and session ID — show the URL to the user.
3. Exits immediately (does NOT block).

IMMEDIATELY run the poll command — do NOT wait for user to respond:

prava sessions poll --session-id <session_id>

This polls up to 10 minutes and returns tokenized card credentials. The user opens the payment URL in their browser while the poll waits.

Read cli-sessions reference for full details.

4. Complete the purchase

IMMEDIATELY use the returned credentials to complete checkout at the merchant's site via browser automation.

The CLI outputs:

Token:        4323126882557932     (16-digit Visa network token)
Cryptogram:   957                  (3-digit one-time dynamic CVV)
Expiry:       12/2028

• Token is a Visa network token — use it where a card number is expected.
• Cryptogram is a single-use dynamic CVV — use it where CVV is expected.
• Expiry is the token's expiry date.

Do NOT ask the user anything between steps 3 and 4. The credentials expire in 30 minutes. Complete checkout immediately.

Important: This is a Payment Subroutine

Steps 1-4 are a SINGLE unbreakable sequence within the larger purchase flow. The user's original intent (e.g., "buy coffee") must not be interrupted.

CLI Quick Reference

prava setup --name "<name>" [--description "<desc>"]   # prints URL, exits immediately
prava setup poll                                        # waits for user to approve the link
prava status                                            # checks link status (also detects approval)
prava sessions create --total-amount <amt> --currency <CUR> --merchant-name "<name>" --merchant-url "<url>" --merchant-country <XX> --product '<json>' [--product ...]   # creates session, prints URL, exits immediately
prava sessions poll --session-id <id>                   # waits for card tokenization

Output Contract

• stdout: human-readable output
• stderr: errors as plain text
• Exit 0 = success (also: setup when already linked — no-op)
• Exit 1 = error (network, timeout, invalid input, CLI version too old)
• Exit 2 = agent not configured or not yet approved

Automatic Behaviors

Auto-link-check: If you run sessions create while the agent is pending (not yet approved), the CLI automatically checks if the user approved since last check. If approved, it updates local state and proceeds. You don't need to run prava status between setup and sessions create.

Version check: The Prava backend may require a minimum CLI version. If the CLI is too old:

• Minor/patch mismatch: warning printed, continues working
• Major version mismatch: CLI blocks and exits with code 1

If you see a version error, run: npm update -g @prava-sdk/cli

Anti-Patterns

• Running sessions create before agent is linked (check prava status first).
• Running sessions create before completing purchase discovery.
• Guessing or hallucinating amount, currency, or purchase context.
• Asking user for keys, card numbers, or credentials. The CLI handles all auth locally.
• Pausing between receiving credentials and completing checkout.
• Running setup when already linked (harmless — exits 0, but unnecessary).

---

Built by Prava Payments — the payment stack for AI agents.