A payment session is the direct way to pay when you already know the merchant, the items, and the
total. You create the session, the owner enters their card in Prava’s secure page, and you receive
one-time credentials to complete the checkout.
Use this flow when you found the product. If you want Prava to help discover the product too,
see Agentic shopping instead.
The agent must be linked first. If it isn’t, session commands exit with
Agent not linked. Run: prava setup --name "<name>". prava sessions create
prava sessions create \
--total-amount "8.50" \
--currency USD \
--merchant-name "Blue Bottle Coffee" \
--merchant-url "https://bluebottlecoffee.com" \
--merchant-country US \
--product '{"description":"Latte","unit_price":"5.00","quantity":1}' \
--product '{"description":"Croissant","unit_price":"3.50","quantity":1}'
| Option | Required | Description |
|---|
--total-amount <amount> | Yes | Total as a string, e.g. "8.50". Must equal the sum of unit_price × quantity across all products. |
--currency <code> | Yes | ISO 4217 code, e.g. USD, EUR, GBP, INR. |
--merchant-name <name> | Yes | Merchant display name (shown to the owner). |
--merchant-url <url> | Yes | Full merchant URL including https://. |
--merchant-country <code> | Yes | ISO 3166-1 alpha-2 country, e.g. US. |
--product <json> | Yes | A product line item as JSON. Repeat the flag for each distinct item. |
--product is a JSON object:
{ "description": "Latte", "unit_price": "5.00", "quantity": 1 }
For multiple units of the same item, set "quantity" — don’t repeat --product or bake counts
into the description. The total must reconcile with the line items.
Session created.
Session ID: ses_abc123
Payment URL: https://collect.prava.space?session=…
Share this URL to complete card entry.
Run `prava sessions poll --session-id ses_abc123` to wait for card entry.
prava sessions poll
Wait for the card to be entered and tokenized:
prava sessions poll --session-id ses_abc123
| Option | Required | Description |
|---|
--session-id <id> | Yes | The Session ID from sessions create. |
Waiting for card entry on session ses_abc123...
....
Card tokenized.
Token: 4323126882557932
Cryptogram: 957
Expiry: 12/2028
poll waits up to 10 minutes for the owner to enter the card.
What you receive
| Field | Format | Use it as |
|---|
| Token | 16-digit number | The card number at checkout. |
| Cryptogram | 3-digit number | The CVV / security code at checkout. |
| Expiry | MM/YYYY | The card expiry at checkout. |
These credentials are single-use and expire quickly. Complete the checkout immediately after
polling — don’t cache, log, or reuse them. If they expire, create a new session.
Exit codes
Session commands use exit codes so an agent can branch reliably:
| Code | Meaning |
|---|
0 | Success. |
1 | Error or timeout (e.g. session expired, tokenization failed). |
2 | Not linked / no agent configured — run prava setup. |
Common outcomes
| Output | What it means | What to do |
|---|
Session expired. Run \prava sessions create` again.` | The owner didn’t finish card entry within 10 minutes. | Re-create the session; have the card ready. |
Tokenization failed. | The card couldn’t be processed. | Try again, or a different card. See Troubleshooting. |
Invalid product JSON: … | A --product value isn’t valid JSON. | Fix the JSON: '{"description":"…","unit_price":"…","quantity":1}'. |
Failed to create session: … | The order was rejected. | Check the amount reconciles with the line items and the URL includes https://. |
