Skip to main content

Using these docs with an AI assistant

These docs are built to be pasted into AI assistants (Claude, ChatGPT, and friends). Every guide page is available as clean Markdown, there is a machine-readable index, and the full API is published as an OpenAPI 3 spec.

Machine-readable entry points​

  • https://docs.netvalve.com/llms.txt: an llmstxt.org index of every guide with a one-line description and a direct link to its Markdown. Good first thing to hand an assistant.
  • https://docs.netvalve.com/llms-full.txt: every guide concatenated into one file. Paste it when you want the assistant to have the whole guide corpus at once. (Generated API reference pages are intentionally excluded; use the OpenAPI spec below for those.)
  • Per-page Markdown: append .md to any guide URL to get the resolved Markdown twin, e.g. https://docs.netvalve.com/guides/integration-methods/checkout-sdk.md.
  • Copy / Open-in-AI buttons: every guide page has Copy page as Markdown, Open in Claude, and Open in ChatGPT at the top, near the title.
  • OpenAPI spec: the complete machine-readable API reference lives at https://docs.netvalve.com/download/openapi.json (OpenAPI 3). Give this to an assistant instead of the rendered API pages.

Facts to pin in every prompt​

An assistant will guess these wrong unless you pin them. They come straight from the guides linked in each template:

  • Server-side auth uses the netvalve-api-key and netvalve-client-id request headers. See API Authentication.
  • Identify the merchant account with either netvalveMidId or siteId, not both. See Environments & Identifiers.
  • Base URLs: Payment API: https://payment-api.uat.sandbox-netvalve.com (Sandbox/UAT) vs https://api.netvalve.com (Production). Hosted Payment Page: https://hpp-api.uat.sandbox-netvalve.com (Sandbox/UAT) vs https://hpp-api.netvalve.com (Production). See Environments & Identifiers.
  • Test cards live at /guides/getting-started/test-cards, never use real card numbers in Sandbox.

Prompt templates​

Copy a block, paste it into your assistant, and fill in the specifics. Each one points the assistant at the relevant Markdown twin and the OpenAPI spec, and pins the facts developers most often get wrong.

Direct API: card sale + 3DS
You are helping me integrate the NetValve Payment Gateway using the Direct API
(server-to-server, I handle the raw card data).

Read these first:
- https://docs.netvalve.com/guides/integration-methods/netvalve.md
- https://docs.netvalve.com/guides/3ds/add-3ds-fields.md
- OpenAPI spec: https://docs.netvalve.com/download/openapi.json

Task: implement a card Sale with 3-D Secure v2.

Pin these facts (do not deviate):
- Authenticate server-side with the request headers `netvalve-api-key` and
  `netvalve-client-id`. There is no bearer token.
- Identify the merchant with either `netvalveMidId` OR `siteId`, never both.
- The Sale is POST {paymentApiUrl}/sale. Base URL is
  https://payment-api.uat.sandbox-netvalve.com in Sandbox/UAT and
  https://api.netvalve.com in Production.
- Direct API means raw PAN passes through my server, so I am in PCI scope.
- For 3DS, carry the authentication result into the Sale request by mapping the
  ECI, CAVV, and dsTransactionId fields as described in the add-3ds-fields guide.
- Use the test cards at
  https://docs.netvalve.com/guides/getting-started/test-cards in Sandbox.
Checkout SDK: embedded checkout
You are helping me integrate the NetValve Checkout SDK (drop-in JavaScript that
renders the whole payment UI in hosted iframes).

Read this first:
- https://docs.netvalve.com/guides/integration-methods/checkout-sdk.md
- OpenAPI spec: https://docs.netvalve.com/download/openapi.json

Task: render the Checkout SDK on my checkout page and complete a payment.

Pin these facts (do not deviate):
- My SERVER calls POST /sdk/initializeSession with the `netvalve-api-key` and
  `netvalve-client-id` headers and gets back a session (paymentToken, jwtToken,
  the SDK script URL `netvalveScriptSrc`, and the payment-page layout).
- The browser loads the script from `session.netvalveScriptSrc`, then calls
  `NetvalveSDK.init(session)`. The SDK draws the fields and drives the payment.
- The SDK encrypts the card fields and makes the `/sdk/sale`, 3DS, and APM calls
  itself. Do NOT build a card form, call the encrypt endpoint, or call the sale
  API from the browser myself, which keeps my PCI footprint minimal.
- Identify the merchant with either `netvalveMidId` OR `siteId`, never both.
- Base URL: https://payment-api.uat.sandbox-netvalve.com (Sandbox/UAT) vs
  https://api.netvalve.com (Production).
Hosted Payment Page (HPP)
You are helping me integrate the NetValve Hosted Payment Page (redirect or
iframe checkout hosted by NetValve).

Read this first:
- https://docs.netvalve.com/guides/integration-methods/netvalve-hpp.md
- OpenAPI spec: https://docs.netvalve.com/download/openapi.json

Task: create an HPP order and send the customer to the hosted checkout.

Pin these facts (do not deviate):
- Create the order with POST {hppApiUrl}/hpp/order using the `netvalve-api-key`
  and `netvalve-client-id` headers. The HPP base URL is DIFFERENT from the
  Payment API: https://hpp-api.uat.sandbox-netvalve.com (Sandbox/UAT) vs
  https://hpp-api.netvalve.com (Production).
- The response returns a `redirectUrl` and a `responseCode`. Check that
  `responseCode` is `GTW_1000` BEFORE redirecting the customer.
- Redirect the customer to `redirectUrl` (full-page) or load it in an iframe
  (slim mode). Append the `paymentOptions` query parameter to control which
  payment methods are shown.
- Identify the merchant with either `netvalveMidId` OR `siteId`, never both.
Token Fields
You are helping me integrate NetValve Token Fields (hosted iframe card fields
that return a payment token; my server never sees the PAN).

Read these first:
- https://docs.netvalve.com/guides/integration-methods/token-fields.md
- https://docs.netvalve.com/guides/integration-methods/token-fields/sale-with-token.md
- OpenAPI spec: https://docs.netvalve.com/download/openapi.json

Task: collect the card with Token Fields and charge it.

Pin these facts (do not deviate):
- Initialize the session server-side with POST {paymentApiUrl}/hpf/initializeSession
  using the `netvalve-api-key` and `netvalve-client-id` headers. The response
  includes a `paymentToken`, the SDK script URL `netvalveScriptSrc`, and a JWT.
- Load the SDK from `netvalveScriptSrc`. When the fields are submitted, the SDK
  invokes the `onSubmitPayment(paymentToken)` callback.
- Use that SAME `paymentToken` in the Sale API (see sale-with-token). Do not try
  to re-tokenize or read the card data yourself.
- Identify the merchant with either `netvalveMidId` OR `siteId`, never both.
- Base URL: https://payment-api.uat.sandbox-netvalve.com (Sandbox/UAT) vs
  https://api.netvalve.com (Production).
Webhook handling
You are helping me implement a handler for NetValve payment webhooks.

Read this first:
- https://docs.netvalve.com/guides/reference/webhook-msg.md
- OpenAPI spec: https://docs.netvalve.com/download/openapi.json

Task: receive NetValve webhook events and process them reliably.

Pin these facts (do not deviate):
- NetValve POSTs the event to my endpoint. I must respond 200 OK, and respond
  promptly; if I do not respond within about 5 seconds NetValve treats it as
  unhandled and retries.
- Delivery is at-least-once: I WILL sometimes receive the same event more than
  once, so my handler must be idempotent (key off the transaction/event id).
- Event names include PURCHASED, PURCHASE_FAILED, REBILLED, REBILL_FAILED,
  REBILL_PENDING, and CHARGEBACK (see the guide for the full list).
- Do not assume a payload signature header exists. Authenticate the source by
  allowlisting NetValve's webhook source IPs (listed in the Environments guide),
  and confirm the authenticity mechanism with NetValve before trusting events.

What still needs human review before production​

An AI assistant can scaffold an integration, but a developer must own these, because each depends on your environment, your risk posture, or credentials the docs deliberately do not contain:

  • CSP configuration: the SDKs load hosted iframes and scripts, so your Content-Security-Policy must allow the NetValve origins; only you know your site's full policy, and a wrong CSP silently breaks the payment fields.
  • Webhook authenticity: the docs describe IP allowlisting but no payload signature, so an assistant that invents a signature check will be wrong; verify how you authenticate webhooks with NetValve before going live.
  • Refund & chargeback flows: these move money in the reverse direction and have real financial and dispute consequences, so the logic and permissions must be reviewed rather than accepted from generated code.
  • PCI scope: Direct API puts raw card data through your servers (in scope) while Checkout SDK, HPP, and Token Fields minimize it; confirm which method matches the PCI scope you are prepared to carry.
  • Go-live credentials: production keys, MIDs, and site IDs are never in these docs; a developer must provision them and keep them out of client-side code and version control.