> ## Documentation Index > Fetch the complete documentation index at: https://www.niftipay.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Fiat Integrations > Create and manage fiat payment integrations, including return URLs, webhook URLs, and contact URLs for fraud protection. # Fiat Integrations A **fiat integration** is the configuration that connects your application to Niftipay's card payment system. Each integration defines: * **Return URL** — where to redirect the customer after payment * **Failure URL** — where to redirect after a failed or cancelled payment (optional) * **Merchant Webhook URL** — where Niftipay sends payment status updates (optional, can also use the global webhook system) * **Contact URL** — a link to your contact form, shown to customers on the [fraud block page](/api/chargebacks#block-page--contact-url) (optional) You reference your integration's `id` as `integrationId` when [creating fiat orders](/api/fiat-orders). *** ## Base URL All examples use: * `https://www.niftipay.com` *** ## Authentication All endpoints require API key (`x-api-key` header) or session authentication. *** # List Integrations ## Endpoint `GET /api/fiat/integrations` Returns all fiat integrations for the authenticated user. ### Query parameters | Name | Type | Notes | | ------ | ------ | ------------------------------------- | | `name` | string | Optional. Filter by integration name. | ### Example request ```bash theme={null} curl -X GET "https://www.niftipay.com/api/fiat/integrations" \ -H "x-api-key: YOUR_API_KEY" \ -H "Accept: application/json" ``` ### Example response ```json theme={null} { "integrations": [ { "id": "fi_abc123", "userId": "u_xyz789", "name": "My Shop", "psp": "nopayn", "pspProjectId": null, "returnUrl": "https://myshop.com/return", "failureUrl": "https://myshop.com/payment-failed", "merchantWebhookUrl": "https://myshop.com/niftipay/webhook", "contactUrl": "https://myshop.com/contact", "createdAt": "2026-03-15T10:00:00.000Z", "updatedAt": "2026-04-10T08:30:00.000Z" } ] } ``` ### Response fields | Field | Type | Description | | -------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Integration ID. Use this as `integrationId` when creating orders. | | `userId` | string | Your user ID. | | `name` | string | Integration name (e.g. your shop name). | | `psp` | string | Payment service provider (default: `"nopayn"`). | | `pspProjectId` | string \| null | PSP project identifier (if applicable). | | `returnUrl` | string | URL to redirect customers after successful payment. | | `failureUrl` | string \| null | URL to redirect after failed/cancelled payment. | | `merchantWebhookUrl` | string \| null | Per-integration webhook URL for payment status updates. | | `contactUrl` | string \| null | URL to your contact form. Shown on the [block page](/api/chargebacks#block-page--contact-url) when a customer is blocked by fraud protection. | | `createdAt` | string | ISO 8601 timestamp. | | `updatedAt` | string \| null | ISO 8601 timestamp of last update. | *** # Create Integration ## Endpoint `POST /api/fiat/integrations` Creates a new fiat integration. ### Request body ```json theme={null} { "name": "My Shop", "returnUrl": "https://myshop.com/return", "failureUrl": "https://myshop.com/payment-failed", "merchantWebhookUrl": "https://myshop.com/niftipay/webhook", "contactUrl": "https://myshop.com/contact" } ``` | Field | Type | Required | Notes | | -------------------- | ------ | -------- | --------------------------------------------------------------------- | | `name` | string | Yes | A name for this integration. | | `returnUrl` | string | Yes | Must be a valid `http` or `https` URL. | | `failureUrl` | string | No | Must be a valid `http` or `https` URL. | | `merchantWebhookUrl` | string | No | Must be a valid `http` or `https` URL. | | `contactUrl` | string | No | Must be a valid `http` or `https` URL. Shown on the fraud block page. | | `psp` | string | No | Defaults to `"nopayn"`. | | `pspProjectId` | string | No | PSP project ID if applicable. | ### Example request ```bash theme={null} curl -X POST "https://www.niftipay.com/api/fiat/integrations" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "My Shop", "returnUrl": "https://myshop.com/return", "contactUrl": "https://myshop.com/contact" }' ``` ### Example response ```json theme={null} { "integration": { "id": "fi_abc123", "userId": "u_xyz789", "name": "My Shop", "psp": "nopayn", "pspProjectId": null, "returnUrl": "https://myshop.com/return", "failureUrl": null, "merchantWebhookUrl": null, "contactUrl": "https://myshop.com/contact", "createdAt": "2026-04-14T12:00:00.000Z", "updatedAt": null } } ``` *** # Update Integration ## Endpoint `PATCH /api/fiat/integrations/:id` Updates an existing fiat integration. Only include the fields you want to change. Set a field to `null` to clear it. ### Path parameters | Name | Type | Notes | | ---- | ------ | ------------------- | | `id` | string | The integration ID. | ### Request body All fields are optional. Only included fields are updated. ```json theme={null} { "contactUrl": "https://myshop.com/contact" } ``` | Field | Type | Notes | | -------------------- | -------------- | --------------------------------------------------------------- | | `name` | string | Cannot be empty. | | `returnUrl` | string | Cannot be null. Must be a valid URL. | | `failureUrl` | string \| null | Set to `null` to remove. | | `merchantWebhookUrl` | string \| null | Set to `null` to remove. | | `contactUrl` | string \| null | Set to `null` to remove the contact button from the block page. | | `psp` | string | Cannot be empty. | | `pspProjectId` | string \| null | Set to `null` to remove. | ### Example: add a contact URL ```bash theme={null} curl -X PATCH "https://www.niftipay.com/api/fiat/integrations/fi_abc123" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"contactUrl": "https://myshop.com/contact"}' ``` ### Example: remove a contact URL ```bash theme={null} curl -X PATCH "https://www.niftipay.com/api/fiat/integrations/fi_abc123" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"contactUrl": null}' ``` ### Example response ```json theme={null} { "integration": { "id": "fi_abc123", "userId": "u_xyz789", "name": "My Shop", "psp": "nopayn", "pspProjectId": null, "returnUrl": "https://myshop.com/return", "failureUrl": null, "merchantWebhookUrl": null, "contactUrl": "https://myshop.com/contact", "createdAt": "2026-03-15T10:00:00.000Z", "updatedAt": "2026-04-14T12:00:00.000Z" } } ``` *** # Delete Integration ## Endpoint `DELETE /api/fiat/integrations/:id` Deletes an integration. Any fiat orders linked to this integration will have their `integrationId` set to `null`. ### Path parameters | Name | Type | Notes | | ---- | ------ | ------------------- | | `id` | string | The integration ID. | ### Example request ```bash theme={null} curl -X DELETE "https://www.niftipay.com/api/fiat/integrations/fi_abc123" \ -H "x-api-key: YOUR_API_KEY" ``` ### Example response ```json theme={null} { "ok": true } ``` *** # Error Responses ## Invalid URL (400) Returned when a URL field is not a valid `http` or `https` URL. ```json theme={null} { "ok": false, "error": "Invalid URL" } ``` ## Missing required field (400) ```json theme={null} { "ok": false, "error": "name is required" } ``` ## Not found (404) Returned when the integration ID does not exist or does not belong to your account. ```json theme={null} { "ok": false, "error": "Not found" } ```