When to use FramePay vs the server-side tokenization endpoint
PaymentsAI offers two ways to turn raw card data into a token your server can store. They serve different integration shapes; pick the one that matches yours.
FramePay (recommended for web)
FramePay is a JavaScript SDK that mounts PaymentsAI-hosted iframe fields directly into your payment form. The customer types their card details into the iframe; raw card data never reaches your server.
When to use FramePay:
- You have a web frontend where the customer enters card details.
- You want to keep PCI DSS scope at SAQ A, which requires a self-assessment only and no QSA audit.
- You want Apple Pay, Google Pay, and PayPal to work alongside cards in the same form.
See FramePay for the integration guide.
Server-side tokenization endpoint
The server-side tokenization endpoint accepts raw card data in a POST request body. Your server passes the PAN, CVV, and expiry to PaymentsAI and receives a token in response.
When to use the server-side endpoint:
- You have no browser in the flow, such as a native mobile app talking only to your backend or a server-only integration.
- You cannot mount a JavaScript iframe.
Because the card data flows through your server, this approach puts you in SAQ D PCI scope. This requires a longer self-assessment with stricter controls, and potentially a QSA audit.
Stage vs production endpoints
The server-side tokenization endpoint changes between environments. The flow remains identical, but the URL and authentication headers differ.
| Environment | Endpoint | Auth pattern |
|---|---|---|
| Stage | POST https://staging-api.payments.ai/v1/public-api/organizations/{organizationId}/payment-instruments/tokens | organizationId in the path; Authorization: ApiKey ... header |
| Production | POST https://tokenization.payments.ai/tokens | organizationId in the X-Organization-Id header; Authorization: ApiKey ... header |
The production endpoint is on a dedicated host (tokenization.payments.ai) and is restricted to production environments; it does not respond on stage. For specific URL patterns and headers, see Base URLs.
Decision matrix
| Your integration | Use |
|---|---|
| Web frontend (customer types card on your site) | FramePay |
| Native mobile app with a browser-based payment screen | FramePay (in a WebView) |
| Native mobile app, no browser, talking only to your backend | Server-side endpoint |
| Backend-only integration (no customer-facing form) | Server-side endpoint |
If both options are technically possible, FramePay is the preferred choice because it minimizes PCI scope and is the default path for web.