### Install Prava CLI

Source: https://docs.prava.space/prava-pay/quickstart

Global installation of the Prava CLI tool via npm.

```bash
npm install -g @prava-sdk/cli
```

--------------------------------

### create_mandate

Source: https://docs.prava.space/mcp/tools

Starts mandate setup and returns an approval URL for the owner to approve with a passkey.

```APIDOC
## create_mandate

### Description
Starts mandate setup and returns an `approval_url` for the owner to approve with a passkey. Spends nothing.

### Parameters
- **amount** (string) - Required - Per-charge cap, e.g. "120.00"
- **currency** (string) - Required - 3-letter ISO 4217, e.g. USD
- **merchant_name** (string) - Optional - Required unless merchant_scope is any
- **merchant_url** (string) - Optional - Required unless merchant_scope is any
- **merchant_country** (string) - Optional - 2-letter ISO 3166-1, e.g. US
- **recurring_frequency** (string) - Optional - one_time (default), weekly, monthly, yearly
- **merchant_scope** (string) - Optional - listed (default) or any (one-time only)
- **valid_until** (string) - Optional - ISO 8601; one-time is capped at 7 days
- **max_charges** (integer) - Optional - Maximum number of charges allowed against the mandate
- **products** (array) - Optional - Line items: { description, unit_price, quantity? }
```

--------------------------------

### Create a mandate setup session

Source: https://docs.prava.space/api-reference/create-session

Initiates a session specifically for mandate setup using cURL.

```bash
curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "40.00",
    "currency": "USD",
    "purchase_context": [{
      "merchant_details": { "name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US" },
      "product_details": [{ "description": "Monthly plan", "unit_price": "40.00" }]
    }],
    "mandate_setup": {
      "intent": "mandate_setup",
      "recurring_frequency": "monthly",
      "merchant_scope": "listed",
      "max_charges": 12
    }
  }'
```

--------------------------------

### Install Prava SDK

Source: https://docs.prava.space/sdk/overview

Install the core Prava SDK package using your preferred package manager.

```bash
npm install @prava-sdk/core
```

```bash
yarn add @prava-sdk/core
```

```bash
pnpm add @prava-sdk/core
```

--------------------------------

### Verify CLI Installation

Source: https://docs.prava.space/prava-pay/overview

Check the installed version of the Prava CLI.

```bash
prava --version
# 3.0.3
```

--------------------------------

### Install Prava Skills via CLI

Source: https://docs.prava.space/prava-pay/skills

Use these commands to install specific or all available skills into the agent's global directory.

```bash
npx --yes skills add https://github.com/Prava-Payments/prava-skills \
  --skill prava-shopping --global --yes --full-depth
```

```bash
npx --yes skills add https://github.com/Prava-Payments/prava-skills \
  --global --yes --full-depth
```

--------------------------------

### Initialize agent setup

Source: https://docs.prava.space/prava-pay/linking

Run this command to create the agent's local identity and generate an approval URL.

```bash
prava setup --name "Claude Code" --platform claude-code --description "Anthropic's coding agent"
```

--------------------------------

### Install Prava Skill

Source: https://docs.prava.space/prava-pay/overview

Add the required skill to enable the agent to perform shopping tasks.

```bash
npx --yes skills add https://github.com/Prava-Payments/prava-skills \
  --skill prava-shopping --global --yes --full-depth
```

--------------------------------

### API Response Examples

Source: https://docs.prava.space/api-reference/get-payment-result

Examples of successful and error responses returned by the payment result endpoint.

```json
{
  "session_id": "sess_123",
  "order_id": "ord_4a1b",
  "status": "awaiting_result",
  "transactions": [
    {
      "txn_id": "txn_1",
      "status": "awaiting_result",
      "line_items": [
        {
          "txn_ref_id": "tli_1",
          "merchant_name": "Acme Store",
          "total_amount": "49.99",
          "status": "awaiting_result",
          "token": "4111111111111111",
          "dynamic_cvv": "123",
          "expiry_month": "12",
          "expiry_year": "2030",
          "products": []
        }
      ]
    }
  ]
}
```

```json
{
  "error": { "code": "AUTH_1002", "message": "Missing or invalid Authorization header" }
}
```

```json
{
  "error": { "code": "NOT_FOUND", "message": "Session not found" }
}
```

--------------------------------

### Retrieve a mandate

Source: https://docs.prava.space/api-reference/mandate-get

Examples for fetching mandate details using various programming languages.

```bash
curl "https://sandbox.api.prava.space/v1/mandates/mdt_123" \
  -H "Authorization: Bearer sk_test_..."
```

```python
import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/mandates/mdt_123",
    headers={"Authorization": "Bearer sk_test_..."},
)
```

```javascript
const resp = await fetch("https://sandbox.api.prava.space/v1/mandates/mdt_123", {
  headers: {
    Authorization: "Bearer sk_test_...",
  },
});
```

--------------------------------

### Session creation output

Source: https://docs.prava.space/prava-pay/sessions

Example output returned after successfully creating a payment session, including the session ID and payment URL.

```text
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.
```

--------------------------------

### Delete Card Response Examples

Source: https://docs.prava.space/api-reference/delete-card

JSON response examples for successful deletions and common error scenarios.

```json
{ "success": true, "card_id": "card_1", "was_default": false, "network_token_deleted": true }
```

```json
{
  "error": { "code": "INVALID_REQUEST", "message": "Missing customer_id or card_id" }
}
```

```json
{
  "error": { "code": "NOT_FOUND", "message": "Card not found" }
}
```

--------------------------------

### Create a Payment Session on the Backend

Source: https://docs.prava.space/guides/add-payments-to-your-ai-app

Use these examples to pin an order and return a session token to your frontend. Ensure the secret key is stored in environment variables and sessions are created only when the user is ready to pay.

```typescript
// app/api/prava/session/route.ts
export async function POST(req: Request) {
  const { userId, email, amount, merchant, items } = await req.json();

  const res = await fetch('https://sandbox.api.prava.space/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PRAVA_SECRET_KEY}`, // sk_test_…
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      user_id: userId,
      user_email: email,
      total_amount: amount,            // e.g. "49.99"
      currency: 'USD',
      integration_type: 'embedding',   // card UI inside your page
      purchase_context: [{
        merchant_details: merchant,    // destination merchant, not your app: { name, url, country_code_iso2 }
        product_details: items,        // [{ description, unit_price, quantity }]
      }],
    }),
  });

  const session = await res.json();
  // → { session_id, session_token, iframe_url, order_id, expires_at }
  return Response.json({
    sessionId: session.session_id,
    sessionToken: session.session_token,
    iframeUrl: session.iframe_url,
  });
}
```

```typescript
// server.ts
import express from 'express';
const app = express();
app.use(express.json());

app.post('/api/prava/session', async (req, res) => {
  const { userId, email, amount, merchant, items } = req.body;

  const r = await fetch('https://sandbox.api.prava.space/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PRAVA_SECRET_KEY}`, // sk_test_…
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      user_id: userId,
      user_email: email,
      total_amount: amount,
      currency: 'USD',
      integration_type: 'embedding',
      purchase_context: [{
        merchant_details: merchant,
        product_details: items,
      }],
    }),
  });

  const session = await r.json();
  res.json({
    sessionId: session.session_id,
    sessionToken: session.session_token,
    iframeUrl: session.iframe_url,
  });
});

app.listen(3000);
```

--------------------------------

### Approval URL output

Source: https://docs.prava.space/prava-pay/linking

The output provided by the setup command containing the URL for the owner to authorize the agent.

```text
To link this agent, open this URL and approve:

https://pay.prava.space/link-agent?lid=lk_xxxxxxxx

Link expires in 15 minutes.
Run `prava setup poll` to wait for approval.
```

--------------------------------

### API Response Examples

Source: https://docs.prava.space/api-reference/mandate-charge

Examples of successful and error responses returned by the mandate charge endpoint.

```json
{
  "mandateId": "mdt_123",
  "instructionId": "ins_1",
  "transactionId": "txn_9",
  "orderId": "ord_9",
  "status": "awaiting_result",
  "fetchStatus": "SUCCESS",
  "credentials": { "token": "4111111111111111", "dynamicCvv": "123", "expiryMonth": "12", "expiryYear": "2030" },
  "deduplicated": false
}
```

```json
{
  "error": { "code": "MANDATE_FORBIDDEN", "message": "Caller does not own this mandate" }
}
```

```json
{
  "error": { "code": "MANDATE_NOT_ACTIVE", "message": "Mandate is not active" }
}
```

--------------------------------

### Charge a Mandate

Source: https://docs.prava.space/api-reference/mandate-charge

Use these examples to initiate a charge against a mandate by providing the amount and reference.

```bash
curl -X POST https://sandbox.api.prava.space/v1/mandates/mdt_123/charge \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "40.00", "reference": "invoice_2026_07" }'
```

```python
import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/mandates/mdt_123/charge",
    headers={"Authorization": "Bearer sk_test_..."},
    json={"amount": "40.00", "reference": "invoice_2026_07"},
)
```

```javascript
const resp = await fetch("https://sandbox.api.prava.space/v1/mandates/mdt_123/charge", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "40.00",
    reference: "invoice_2026_07",
  }),
});
```

--------------------------------

### Add the Prava MCP server

Source: https://docs.prava.space/mcp/connect

Configuration examples for adding the Prava MCP server to various client environments.

```bash
claude mcp add --transport http prava https://mcp.pay.prava.space/mcp
```

```json
{
  "mcpServers": {
    "prava": {
      "url": "https://mcp.pay.prava.space/mcp"
    }
  }
}
```

```text
Server URL:  https://mcp.pay.prava.space/mcp
Transport:   Streamable HTTP
Auth:        OAuth (automatic — the client discovers and registers itself)
```

--------------------------------

### Delete Card Request Examples

Source: https://docs.prava.space/api-reference/delete-card

Examples of how to perform a card deletion request using cURL, Python, and JavaScript.

```bash
curl -X POST https://sandbox.api.prava.space/v1/deleteCard \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "user_123", "card_id": "card_1", "reason": "CUSTOMER_CONFIRMED" }'
```

```python
import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/deleteCard",
    headers={"Authorization": "Bearer sk_test_..."},
    json={"customer_id": "user_123", "card_id": "card_1", "reason": "CUSTOMER_CONFIRMED"},
)
```

```javascript
const resp = await fetch("https://sandbox.api.prava.space/v1/deleteCard", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_id: "user_123",
    card_id: "card_1",
    reason: "CUSTOMER_CONFIRMED",
  }),
});
```

--------------------------------

### prava mandate create

Source: https://docs.prava.space/prava-pay/mandates

Initiates the setup of a mandate by printing a passkey approval URL for the user to authorize.

```APIDOC
## prava mandate create

### Description
Set up a mandate to authorize future charges. This command prints a passkey approval URL that the owner must visit to authorize the mandate.

### Parameters
- **--amount** (string) - Required - Per-charge cap, e.g., "120.00".
- **--currency** (string) - Required - ISO 4217 code, e.g., USD, EUR.
- **--merchant-name** (string) - Required (unless --scope any) - Merchant display name.
- **--merchant-url** (string) - Required (unless --scope any) - Full merchant URL including https://.
- **--merchant-country** (string) - Required (unless --scope any) - ISO 3166-1 alpha-2 country code.
- **--frequency** (string) - Optional - one_time (default), weekly, monthly, or yearly.
- **--scope** (string) - Optional - listed (default) or any.
- **--product** (json) - Optional - Product line item as JSON.
- **--valid-until** (string) - Optional - Validity hint (ISO 8601).
- **--max-charges** (integer) - Optional - Advisory hint on the number of charges.
- **-y, --yes** (boolean) - Optional - Skip confirmation prompt.
- **--json** (boolean) - Optional - Emit raw JSON output.

### Request Example
```bash
prava mandate create \
  --merchant-name "Nike" \
  --merchant-url "https://nike.com" \
  --merchant-country US \
  --amount 120.00 \
  --currency USD \
  --frequency one_time \
  --scope listed \
  -y
```
```

--------------------------------

### Retrieve payment result

Source: https://docs.prava.space/api-reference/get-payment-result

Use these examples to fetch the payment result for a specific session ID.

```bash
curl "https://sandbox.api.prava.space/v1/sessions/sess_123/payment-result" \
  -H "Authorization: Bearer sk_test_..."
```

```python
import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/sessions/sess_123/payment-result",
    headers={"Authorization": "Bearer sk_test_..."},
)
```

```javascript
const resp = await fetch("https://sandbox.api.prava.space/v1/sessions/sess_123/payment-result", {
  headers: {
    Authorization: "Bearer sk_test_...",
  },
});
```

--------------------------------

### Create a Session

Source: https://docs.prava.space/api-reference/create-session

Initializes a new session for a transaction or mandate setup. Requires a valid API key in the Authorization header.

```bash
curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": [{
      "merchant_details": { "name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US" },
      "product_details": [{ "description": "Widget", "unit_price": "24.99", "quantity": 2 }]
    }],
    "integration_type": "full_checkout",
    "callback_url": "https://acme.example.com/return"
  }'
```

```python
import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/sessions",
    headers={"Authorization": "Bearer sk_test_..."},
    json={
        "user_id": "user_123",
        "user_email": "jane@example.com",
        "total_amount": "49.99",
        "currency": "USD",
        "purchase_context": [{
            "merchant_details": {"name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US"},
            "product_details": [{"description": "Widget", "unit_price": "24.99", "quantity": 2}],
        }],
        "integration_type": "full_checkout",
        "callback_url": "https://acme.example.com/return",
    },
)
```

--------------------------------

### API Response examples

Source: https://docs.prava.space/api-reference/revoke-session

JSON response structures for successful and failed session revocation attempts.

```json
{ "success": true }
```

```json
{
  "error": { "code": "AUTH_1002", "message": "Missing or invalid Authorization header" }
}
```

```json
{
  "error": { "code": "NOT_FOUND", "message": "Session not found" }
}
```

--------------------------------

### API Response Examples

Source: https://docs.prava.space/api-reference/report-status

JSON response payloads for successful requests and common error scenarios.

```json
{ "status": "confirmed", "txn_ref_id": "tli_1", "txn_status": "APPROVED", "visa_confirmation": "SUCCESS" }
```

```json
{
  "error": { "code": "INVALID_STATE", "message": "No transaction awaiting payment result" }
}
```

```json
{
  "error": { "code": "NOT_FOUND", "message": "Session or txn_ref_id not found" }
}
```

--------------------------------

### API Response Examples

Source: https://docs.prava.space/api-reference/create-session

Standard JSON response structures for successful session creation and common error scenarios.

```json
{
  "session_id": "sess_9f2c...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/sess_9f2c...",
  "order_id": "ord_4a1b...",
  "expires_at": "2026-07-26T12:15:00Z"
}
```

```json
{
  "session_id": "sess_7d1a...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/sess_7d1a...",
  "order_id": "ord_88c2...",
  "expires_at": "2026-07-26T12:15:00Z",
  "authorizeOnly": true
}
```

```json
{
  "error": {
    "code": "VAL_2001",
    "message": "Validation failed",
    "details": { "currency": "Unsupported currency code" }
  }
}
```

```json
{
  "error": { "code": "AUTH_1001", "message": "Invalid API key" }
}
```

--------------------------------

### Install Prava SDK Integration Skill

Source: https://docs.prava.space/guides/add-payments-to-your-ai-app

Use this command to add the Prava SDK integration skill to your AI coding agent for automated flow implementation.

```bash
npx --yes skills add https://github.com/Prava-Payments/prava-skills \
  --skill prava-sdk-integration --global --yes --full-depth
```

--------------------------------

### Mandate response examples

Source: https://docs.prava.space/api-reference/mandate-get

JSON response structures for successful requests and common error scenarios.

```json
{
  "id": "mdt_123",
  "status": "active",
  "approvedAmount": "40.00",
  "currency": "USD",
  "spent": "40.00",
  "chargeCount": 1,
  "charges": [
    { "transactionId": "txn_9", "amount": "40.00", "currency": "USD", "status": "completed", "reference": "invoice_2026_07", "createdAt": "2026-07-26T00:00:00Z" }
  ]
}
```

```json
{
  "error": { "code": "MANDATE_FORBIDDEN", "message": "Caller does not own this mandate" }
}
```

```json
{
  "error": { "code": "MANDATE_NOT_FOUND", "message": "No such mandate" }
}
```

--------------------------------

### Collect PAN with Prava SDK

Source: https://docs.prava.space/sdk/cards/collect-pan

Examples for integrating card collection in React and Vanilla JavaScript environments.

```typescript
import { useEffect, useRef, useState } from 'react';
import { PravaSDK } from '@prava-sdk/core';
import type { CollectPANResult } from '@prava-sdk/core';

function CardEnrollment({ session }: { session: { session_token: string; iframe_url: string } }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const sdkRef = useRef<PravaSDK | null>(null);
  const [enrolled, setEnrolled] = useState<CollectPANResult | null>(null);

  useEffect(() => {
    const sdk = new PravaSDK({ publishableKey: 'pk_test_xxx' });
    sdkRef.current = sdk;
    return () => sdk.destroy();
  }, []);

  const handleEnroll = async () => {
    if (!sdkRef.current || !containerRef.current) return;

    const result = await sdkRef.current.collectPAN({
      sessionToken: session.session_token,
      iframeUrl: session.iframe_url,
      container: containerRef.current,
      onReady: () => console.log('Form loaded'),
      onChange: (state) => {
        console.log('Complete:', state.isComplete);
      },
      onSuccess: (data) => {
        console.log(`Enrolled: •••• ${data.last4}`);
        setEnrolled(data);
      },
      onError: (err) => console.error(err.code, err.message),
    });
  };

  return (
    <div>
      <div ref={containerRef} />
      <button onClick={handleEnroll}>Enroll Card</button>
      {enrolled && <p>Card enrolled: {enrolled.brand} •••• {enrolled.last4}</p>}
    </div>
  );
}
```

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

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

// Get session from your backend
const session = await fetch('/api/session').then(r => r.json());

// Collect card via secure iframe
const card = await prava.collectPAN({
  sessionToken: session.session_token,
  iframeUrl: session.iframe_url,
  container: '#card-form',
  onReady: () => console.log('Form loaded'),
  onChange: (state) => {
    document.getElementById('submit-btn').disabled = !state.isComplete;
  },
  onSuccess: (data) => {
    console.log(data.enrollmentId, data.last4, data.brand);
  },
  onError: (err) => console.error(err.code, err.message),
});
```

--------------------------------

### List Mandates API Requests

Source: https://docs.prava.space/api-reference/mandate-list

Examples for fetching mandates using cURL, Python, and JavaScript. Ensure the Authorization header is set with your secret key.

```bash
curl "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true" \
  -H "Authorization: Bearer sk_test_..."
```

```python
import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/mandates",
    headers={"Authorization": "Bearer sk_test_..."},
    params={"customer_id": "user_123", "standing_only": "true"},
)
```

```javascript
const resp = await fetch(
  "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true",
  {
    headers: {
      Authorization: "Bearer sk_test_...",
    },
  }
);
```

--------------------------------

### Report a Mandate Charge Request

Source: https://docs.prava.space/api-reference/mandate-report

Examples for reporting a mandate charge outcome using various programming languages.

```bash
curl -X POST https://sandbox.api.prava.space/v1/mandates/mdt_123/charges/txn_9/report \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "txn_status": "APPROVED", "txn_type": "PURCHASE", "authorization_code": "OK123", "response_code": "00", "amount_paid": "40.00" }'
```

```python
import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/mandates/mdt_123/charges/txn_9/report",
    headers={"Authorization": "Bearer sk_test_..."},
    json={
        "txn_status": "APPROVED",
        "txn_type": "PURCHASE",
        "authorization_code": "OK123",
        "response_code": "00",
        "amount_paid": "40.00",
    },
)
```

```javascript
const resp = await fetch(
  "https://sandbox.api.prava.space/v1/mandates/mdt_123/charges/txn_9/report",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_test_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      txn_status: "APPROVED",
      txn_type: "PURCHASE",
      authorization_code: "OK123",
      response_code: "00",
      amount_paid: "40.00",
    }),
  }
);
```

--------------------------------

### List Mandates API Responses

Source: https://docs.prava.space/api-reference/mandate-list

Example JSON responses for successful requests and common error scenarios.

```json
{
  "mandates": [
    {
      "id": "mdt_123",
      "status": "active",
      "state": "available",
      "recurringFrequency": "monthly",
      "merchantScope": "listed",
      "merchantName": "Acme Store",
      "approvedAmount": "40.00",
      "remaining": "40.00",
      "currency": "USD",
      "validUntil": "2027-07-26T00:00:00Z",
      "renewsAt": "2026-08-26T00:00:00Z",
      "lastCharge": null,
      "createdAt": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T00:00:00Z"
    }
  ]
}
```

```json
{
  "error": { "code": "AUTH_REQUIRED", "message": "Missing or invalid credentials" }
}
```

```json
{
  "error": { "code": "FORBIDDEN", "message": "Caller may not list these mandates" }
}
```

--------------------------------

### POST /v1/sessions

Source: https://docs.prava.space/api-reference/create-session

Creates a new payment session for a customer and order. Supports standard checkout or mandate setup based on the provided intent.

```APIDOC
## POST /v1/sessions

### Description
Create a short-lived, single-use session tied to one merchant, customer, and order. The response provides a `session_token` and `iframe_url` for frontend integration.

### Method
POST

### Endpoint
/v1/sessions

### Request Body
- **intent** (string) - Optional - Set to "mandate_setup" for mandate creation, or "checkout" for standard payments.
- **mandate_setup** (object) - Optional - Required for mandate setup flows; includes `recurring_frequency`, `merchant_scope`, `max_charges`, and `valid_until`.
- **card** (object) - Optional - Use `card_id` to pre-select an enrolled card or `vault_ref_id` for vault-ref flow.
```

--------------------------------

### Create a payment session

Source: https://docs.prava.space/prava-pay/quickstart

Initialize a new payment session with order details, merchant information, and product items.

```bash
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}'
```

--------------------------------

### Quick-add MCP Server by Tool

Source: https://docs.prava.space/ai

Commands and instructions for adding the Prava MCP server to various AI development environments.

```bash
claude mcp add --transport http prava-docs https://docs.prava.space/mcp
```

```text
MCP settings → "Add server" → paste the URL:
  https://docs.prava.space/mcp
```

```text
Settings → Connectors → "Add custom connector" →
  Name: Prava Docs
  URL:  https://docs.prava.space/mcp
```

--------------------------------

### Retrieve product details via CLI

Source: https://docs.prava.space/prava-pay/shopping

Fetches variants and offers for a specific product using its ID and merchant domain.

```bash
prava shop product --product-id prod_abc --merchant stumptowncoffee.com
```

--------------------------------

### Initialize SDK with Publishable Key

Source: https://docs.prava.space/authentication

Pass the publishable key during SDK initialization in client-side code.

```javascript
new PravaSDK({ publishableKey: 'pk_test_xxx' })
```

--------------------------------

### Search for products via CLI

Source: https://docs.prava.space/prava-pay/shopping

Executes a product search using a keyword query and optional intent, limit, and shipping destination parameters.

```bash
prava shop search --query "dark roast coffee" --intent "gift for a coffee lover" --limit 10 --ships-to US
```

--------------------------------

### Link an agent

Source: https://docs.prava.space/prava-pay/quickstart

Initialize the agent linking process by specifying a name and platform.

```bash
prava setup --name "Claude Code" --platform claude-code
```

--------------------------------

### Report Transaction Status

Source: https://docs.prava.space/api-reference/report-status

Examples for sending a POST request to update the status of a transaction session.

```bash
curl -X POST https://sandbox.api.prava.space/v1/sessions/sess_123/report-status \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "txn_ref_id": "tli_1", "txn_status": "APPROVED", "authorization_code": "OK123", "response_code": "00" }'
```

```python
import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/sessions/sess_123/report-status",
    headers={"Authorization": "Bearer sk_test_..."},
    json={
        "txn_ref_id": "tli_1",
        "txn_status": "APPROVED",
        "authorization_code": "OK123",
        "response_code": "00",
    },
)
```

```javascript
const resp = await fetch("https://sandbox.api.prava.space/v1/sessions/sess_123/report-status", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    txn_ref_id: "tli_1",
    txn_status: "APPROVED",
    authorization_code: "OK123",
    response_code: "00",
  }),
});
```

--------------------------------

### Create a payment session via cURL

Source: https://docs.prava.space/quickstart

Use this command to initialize a payment session on your backend. Requires a secret key for authorization.

```bash
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": [{
      "merchant_details": {
        "name": "Your Store",
        "url": "https://yourstore.com",
        "country_code_iso2": "US"
      },
      "product_details": [{
        "description": "Example Product",
        "unit_price": "49.99",
        "quantity": 1
      }]
    }]
  }'
```

--------------------------------

### GET /v1/listCards and POST /v1/deleteCard

Source: https://docs.prava.space/api-reference/errors

Error codes and recovery steps for card management endpoints.

```APIDOC
## GET /v1/listCards · POST /v1/deleteCard

### Error Responses
| Status | Code | Cause | Recovery |
| --- | --- | --- | --- |
| 404 | CUSTOMER_NOT_FOUND | No customer for the given identifier | Verify customer_id (the user_id you used at session creation) |
| 404 | NOT_FOUND | Card not found (delete) | Verify card_id via List Cards |
| 502 | NETWORK_DELETE_FAILED | Card-network deletion failed (delete) | Retry |
```

--------------------------------

### Create a Payment Session

Source: https://docs.prava.space/guides/rest-checkout-walkthrough

Initiate a payment session by sending a POST request to the sessions endpoint. Ensure the session is created only when the cardholder is ready, as it expires after 15 minutes.

```bash
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",
    "integration_type": "full_checkout",
    "callback_url": "https://yourapp.com/payment-done",
    "purchase_context": [{
      "merchant_details": {
        "name": "Example Store",
        "url": "https://examplestore.com",
        "country_code_iso2": "US"
      },
      "product_details": [{
        "description": "Wireless Headphones",
        "unit_price": "49.99",
        "quantity": 1
      }]
    }]
  }'
```

```json
{
  "session_id": "ses_abc123",
  "session_token": "eyJhbGciOi…",
  "iframe_url": "https://sandbox.collect.prava.space?session=…",
  "order_id": "ord_xyz789",
  "expires_at": "2026-01-01T00:15:00Z"
}
```

--------------------------------

### GET /v1/sessions/{sessionId}/payment-result

Source: https://docs.prava.space/api-reference/errors

Error codes and recovery steps for the Payment Result endpoint.

```APIDOC
## GET /v1/sessions/{sessionId}/payment-result

### Error Responses
| Status | Code | Cause | Recovery |
| --- | --- | --- | --- |
| 404 | NOT_FOUND | Session not found, or it belongs to another merchant | Verify the session ID and which key created it |
```

--------------------------------

### GET /v1/sessions/{sessionId}/payment-result

Source: https://docs.prava.space/api-reference/get-payment-result

Retrieves the payment result and transaction details for a specific session.

```APIDOC
## GET /v1/sessions/{sessionId}/payment-result

### Description
Retrieve payment credentials and transaction status for a session. This is a polling endpoint used after the cardholder completes card entry and passkey approval.

### Method
GET

### Endpoint
/v1/sessions/{sessionId}/payment-result

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The session id from Create Session.

### Response
#### Success Response (200)
- **session_id** (string)
- **order_id** (string | null)
- **status** (string) - Overall session status: pending, awaiting_result, completed, or failed.
- **transactions** (object[]) - List of transaction objects containing txn_id, status, line_items, and error details.
```

--------------------------------

### Initialize PravaSDK

Source: https://docs.prava.space/sdk/overview

Initialize the SDK using your publishable key. This key is safe to use in browser-side code.

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

const prava = new PravaSDK({
  publishableKey: 'pk_test_xxx', // from the Prava Dashboard (sandbox key)
});
```

--------------------------------

### GET /v1/mandates/{id}

Source: https://docs.prava.space/api-reference/mandate-get

Retrieve one mandate with its derived balance and full charge history.

```APIDOC
## GET /v1/mandates/{id}

### Description
Retrieve one mandate with its derived balance and full charge history.

### Method
GET

### Endpoint
/v1/mandates/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The mandate id.

### Response
#### Success Response (200)
- **id** (string) - Mandate ID
- **status** (string) - Mandate status
- **approvedAmount** (string) - Approved amount
- **currency** (string) - Currency code
- **spent** (string) - Cumulative amount charged
- **chargeCount** (integer) - Total number of charges
- **charges** (object[]) - List of charge objects

#### Response Example
{
  "id": "mdt_123",
  "status": "active",
  "approvedAmount": "40.00",
  "currency": "USD",
  "spent": "40.00",
  "chargeCount": 1,
  "charges": [
    { "transactionId": "txn_9", "amount": "40.00", "currency": "USD", "status": "completed", "reference": "invoice_2026_07", "createdAt": "2026-07-26T00:00:00Z" }
  ]
}
```

--------------------------------

### List Cards API Responses

Source: https://docs.prava.space/api-reference/list-cards

Example JSON responses for successful requests and common error scenarios.

```json
{
  "cards": [
    {
      "card_id": "card_1",
      "card_last4": "4242",
      "card_brand": "visa",
      "card_exp_month": 12,
      "card_exp_year": 2030,
      "is_default": true,
      "status": "active",
      "created_at": "2026-05-01T10:00:00Z"
    }
  ],
  "count": 1
}
```

```json
{
  "error": { "code": "INVALID_REQUEST", "message": "Missing customer_id" }
}
```

```json
{
  "error": { "code": "CUSTOMER_NOT_FOUND", "message": "No customer for the given customer_id" }
}
```

--------------------------------

### List Cards API Requests

Source: https://docs.prava.space/api-reference/list-cards

Examples of how to call the listCards endpoint using cURL, Python, and JavaScript.

```bash
curl "https://sandbox.api.prava.space/v1/listCards?customer_id=user_123&status=active" \
  -H "Authorization: Bearer sk_test_..."
```

```python
import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/listCards",
    headers={"Authorization": "Bearer sk_test_..."},
    params={"customer_id": "user_123", "status": "active"},
)
```

```javascript
const resp = await fetch(
  "https://sandbox.api.prava.space/v1/listCards?customer_id=user_123&status=active",
  {
    headers: {
      Authorization: "Bearer sk_test_...",
    },
  }
);
```

--------------------------------

### Configure MCP Server Settings

Source: https://docs.prava.space/ai

Add this configuration to your AI client's MCP settings to enable the Prava documentation server.

```json
{
  "mcpServers": {
    "prava-docs": {
      "url": "https://docs.prava.space/mcp"
    }
  }
}
```

--------------------------------

### Implement Hosted Mode

Source: https://docs.prava.space/sdk/integration-modes

Uses the default integration mode by providing a callback URL and redirecting the user to the hosted checkout page.

```typescript
// 1. Backend: create the session (hosted is the default)
const session = await createSession({
  /* user_id, user_email, total_amount, currency, purchase_context … */
  callback_url: 'https://yourapp.com/checkout/complete', // must be https
});

// 2. Frontend: send the user to the hosted page.
// iframe_url already contains ?session=<session_id> — use it verbatim.
window.location.href = session.iframe_url; // or window.open(session.iframe_url, '_blank')
```

--------------------------------

### GET /v1/sessions/{session_id}/payment-result

Source: https://docs.prava.space/api-reference/get-payment-result

Retrieves the payment result and transaction details for a given session ID.

```APIDOC
## GET /v1/sessions/{session_id}/payment-result

### Description
Retrieves the current status and transaction details for a specific payment session, including virtual card credentials.

### Method
GET

### Endpoint
https://sandbox.api.prava.space/v1/sessions/{session_id}/payment-result

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
- **session_id** (string) - The session identifier.
- **order_id** (string) - The order identifier.
- **status** (string) - The current status of the session.
- **transactions** (array) - List of transactions associated with the session.

#### Response Example
{
  "session_id": "sess_123",
  "order_id": "ord_4a1b",
  "status": "awaiting_result",
  "transactions": [
    {
      "txn_id": "txn_1",
      "status": "awaiting_result",
      "line_items": [
        {
          "txn_ref_id": "tli_1",
          "merchant_name": "Acme Store",
          "total_amount": "49.99",
          "status": "awaiting_result",
          "token": "4111111111111111",
          "dynamic_cvv": "123",
          "expiry_month": "12",
          "expiry_year": "2030",
          "products": []
        }
      ]
    }
  ]
}
```

--------------------------------

### Complete checkout

Source: https://docs.prava.space/prava-pay/quickstart

Finalize the purchase using the tokenized card credentials.

```bash
prava shop checkout \
  --checkout-session-id ches_xxx \
  --token 4323126882557932 \
  --cryptogram 957 \
  --expiry-month 12 --expiry-year 2028 \
  --yes
```

--------------------------------

### Create Session on Backend

Source: https://docs.prava.space/sdk/overview

Create a session on your server using your secret key to obtain a session token and iframe URL.

```typescript
// Server-side (never expose your secret key to the browser)
const session = await fetch('https://sandbox.api.prava.space/v1/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_id: 'user_123',
    user_email: 'user@example.com',
    total_amount: '49.99',
    currency: 'USD',
    purchase_context: [{
      merchant_details: { name: 'Amazon', url: 'https://amazon.com', country_code_iso2: 'US' },
      product_details: [{ description: 'Wireless Headphones', unit_price: '49.99', quantity: 1 }],
    }],
  }),
}).then((r) => r.json());
// → { session_id, session_token, iframe_url, expires_at, order_id }
```

--------------------------------

### Create a Mandate

Source: https://docs.prava.space/prava-pay/mandates

Initializes a mandate for a specific merchant. Requires passkey approval from the owner via the generated URL.

```bash
prava mandate create \
  --merchant-name "Nike" \
  --merchant-url "https://nike.com" \
  --merchant-country US \
  --amount 120.00 \
  --currency USD \
  --frequency one_time \
  --scope listed \
  -y
```

--------------------------------

### Product JSON structure

Source: https://docs.prava.space/prava-pay/sessions

Defines the required JSON format for individual product line items passed to the session creation command.

```json
{ "description": "Latte", "unit_price": "5.00", "quantity": 1 }
```

--------------------------------

### Revoke a payment session

Source: https://docs.prava.space/api-reference/revoke-session

Examples of how to perform a POST request to the revoke session endpoint using various programming languages.

```bash
curl -X POST https://sandbox.api.prava.space/v1/sessions/sess_123/revoke \
  -H "Authorization: Bearer sk_test_..."
```

```python
import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/sessions/sess_123/revoke",
    headers={"Authorization": "Bearer sk_test_..."},
)
```

```javascript
const resp = await fetch("https://sandbox.api.prava.space/v1/sessions/sess_123/revoke", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
  },
});
```

--------------------------------

### GET /v1/listCards

Source: https://docs.prava.space/api-reference/list-cards

Retrieve a list of enrolled cards for a customer. Cards are scoped by the merchant_id associated with your secret key and the provided customer_id.

```APIDOC
## GET /v1/listCards

### Description
Retrieve a customer's enrolled cards. Only non-sensitive card metadata is returned — full PANs are never exposed.

### Method
GET

### Endpoint
/v1/listCards

### Parameters
#### Query Parameters
- **customer_id** (string) - Required - The customer to list cards for.
- **status** (string) - Optional (default: active) - `active` or `all` (include previously deleted cards).
- **include_card_art** (string) - Optional (default: false) - `true` to include `card_art_url` and display `metadata`.

### Response
#### Success Response (200)
- **cards** (object[]) - List of card objects.
- **count** (number) - Number of cards returned.

#### Response Example
{
  "cards": [
    {
      "card_id": "card_1",
      "card_last4": "4242",
      "card_brand": "visa",
      "card_exp_month": 12,
      "card_exp_year": 2030,
      "is_default": true,
      "status": "active",
      "created_at": "2026-05-01T10:00:00Z"
    }
  ],
  "count": 1
}
```