> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prava.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Payments to Your AI App

> The end-to-end tutorial: from a fresh dashboard account to a completed, reported payment inside your own application.

This is the complete integration, start to finish. When you're done, your AI app can take a purchase
your agent proposes, collect the user's card **without touching it**, receive one-time credentials,
and complete the checkout.

**What you'll build:** one backend endpoint that creates sessions, one frontend surface that collects
the card, and one backend callback that reads the result and reports the outcome.

> [!NOTE]
>
> Prefer zero frontend code? The [REST checkout walkthrough](https://docs.prava.space/guides/rest-checkout-walkthrough.md) does
> the same flow with hosted card entry and nothing but cURL.

## Prerequisites (all self-serve)

1. Sign up at [dashboard.prava.space](https://dashboard.prava.space) and create an API key; you get
   `pk_test_*` + `sk_test_*` instantly ([Quickstart](https://docs.prava.space/quickstart.md) has the details).
2. Install the SDK: `npm install @prava-sdk/core`.

> [!TIP]
>
> Building with an AI coding agent? Install the **prava-sdk-integration skill** and your agent knows
> this whole flow, with ready-made templates:
>
> ```bash theme={null}
> npx --yes skills add https://github.com/Prava-Payments/prava-skills \
>   --skill prava-sdk-integration --global --yes --full-depth
> ```

## Step 1 — Backend: create a session

Your server pins the order and returns the session to your frontend. The secret key never leaves the
server.

```typescript Next.js (app router) theme={null}
// 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: {
        custom: [{
          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 Express theme={null}
// 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: {
        custom: [{
          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);
```

Full request schema: [Create Session](https://docs.prava.space/api-reference/create-session.md). Sessions expire after
**15 minutes**: create them when the user is ready to pay, not earlier.

## Step 2 — Frontend: collect the card

Mount Prava's PCI-compliant iframe in your page. The raw card number never touches your DOM,
JavaScript, or servers.

```tsx React theme={null}
import { useEffect, useRef } from 'react';
import { PravaSDK } from '@prava-sdk/core';

export function PayWithPrava({ order }: { order: OrderInput }) {
  const prava = useRef(new PravaSDK({ publishableKey: 'pk_test_xxx' }));

  useEffect(() => () => prava.current.destroy(), []); // cleanup on unmount

  async function collect() {
    const { sessionId, sessionToken, iframeUrl } = await fetch('/api/prava/session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(order),
    }).then((r) => r.json());

    await prava.current.collectPAN({
      sessionToken,
      iframeUrl,
      container: '#card-form',
      onSuccess: async (card) => {
        // card = { enrollmentId, last4, brand, expMonth, expYear }
        await fetch(`/api/prava/complete?sessionId=${sessionId}`, { method: 'POST' });
      },
      onError: (err) => console.error(err.code, err.message),
    });
  }

  return (
    <>
      <div id="card-form" />
      <button onClick={collect}>Pay securely</button>
    </>
  );
}
```

```html Vanilla JS theme={null}
<div id="card-form"></div>
<button id="pay">Pay securely</button>

<script type="module">
  import { PravaSDK } from 'https://esm.sh/@prava-sdk/core';

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

  document.getElementById('pay').addEventListener('click', async () => {
    const { sessionId, sessionToken, iframeUrl } =
      await fetch('/api/prava/session', { method: 'POST' }).then((r) => r.json());

    await prava.collectPAN({
      sessionToken,
      iframeUrl,
      container: '#card-form',
      onSuccess: () =>
        fetch(`/api/prava/complete?sessionId=${sessionId}`, { method: 'POST' }),
      onError: (err) => console.error(err.code, err.message),
    });
  });
</script>
```

The user enters the card and approves with a **passkey** (Touch ID / Face ID) inside the iframe.
Prava handles the authentication, mandate registration (recording the user's permission to pay),
and tokenization (swapping the real card for one-time credentials);
[none of that is your code](https://docs.prava.space/concepts/payments.md#what-prava-does-for-you-in-the-middle). Every option
and callback: [Collect Card Details](https://docs.prava.space/sdk/cards/collect-pan.md).

## Step 3 — Backend: get the credentials and check out

After collection, poll the payment result. When a line item reaches `awaiting_result` it carries the
one-time credentials.

```typescript theme={null}
// Poll until the credentials are ready (they arrive right after card entry completes)
async function getCredentials(sessionId: string) {
  const r = await fetch(
    `https://sandbox.api.prava.space/v1/sessions/${sessionId}/payment-result`,
    { headers: { Authorization: `Bearer ${process.env.PRAVA_SECRET_KEY}` } },
  );
  const result = await r.json();

  if (result.status !== 'awaiting_result') return null; // keep polling ('pending')

  const transaction = result.transactions[0];
  const li = transaction.line_items[0];
  return {
    cardId: transaction.card_id, // source-of-truth card bound to this transaction
    txnRefId: li.txn_ref_id,
    cardNumber: li.token,        // one-time virtual card number
    cvv: li.dynamic_cvv,         // single-use CVV
    expMonth: li.expiry_month,
    expYear: li.expiry_year,
  };
}
```

Use these exactly like normal card details at the merchant's checkout: your agent fills the payment
form, or your backend calls the merchant's payment API. They're **single-use, merchant-locked, and
amount-scoped**, so use them promptly.

## Step 4 — Backend: report the outcome

Always close the loop, whether the checkout succeeded or failed:

```typescript theme={null}
await fetch(
  `https://sandbox.api.prava.space/v1/sessions/${sessionId}/report-status`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PRAVA_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      txn_ref_id: credentials.txnRefId,
      txn_status: 'APPROVED', // or 'DECLINED' if the checkout failed
    }),
  },
);
```

This updates transaction records and relays the outcome to the card network; the payment result's
`status` becomes `completed`. Details: [Report Status](https://docs.prava.space/api-reference/report-status.md).

## Step 5 — Test it

Run the whole flow in sandbox with a [test card](https://docs.prava.space/api-reference/test-cards.md). See
[Testing in Sandbox](https://docs.prava.space/api-reference/testing.md) for the checklist and what behaves differently.

## Ship it

> [card] [Go-live checklist](https://docs.prava.space/guides/go-live-checklist.md)
>
> Swap to live keys and what needs Prava's sign-off.

> [card] [Errors reference](https://docs.prava.space/api-reference/errors.md)
>
> Every code you might hit along this flow, with recovery steps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.