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 (optional)

You reference your integration’s id as integrationId when creating 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

curl -X GET "https://www.niftipay.com/api/fiat/integrations" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

Example response

{
  "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 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

{
  "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

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

{
  "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.

{
  "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

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

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

{
  "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

curl -X DELETE "https://www.niftipay.com/api/fiat/integrations/fi_abc123" \
  -H "x-api-key: YOUR_API_KEY"

Example response

{
  "ok": true
}

Error Responses

Invalid URL (400)

Returned when a URL field is not a valid http or https URL.

{
  "ok": false,
  "error": "Invalid URL"
}

Missing required field (400)

{
  "ok": false,
  "error": "name is required"
}

Not found (404)

Returned when the integration ID does not exist or does not belong to your account.

{
  "ok": false,
  "error": "Not found"
}

​Fiat Integrations

​Base URL

​Authentication

​List Integrations

​Endpoint

​Query parameters

​Example request

​Example response

​Response fields

​Create Integration

​Endpoint

​Request body

​Example request

​Example response

​Update Integration

​Endpoint

​Path parameters

​Request body

​Example: add a contact URL

​Example: remove a contact URL

​Example response

​Delete Integration

​Endpoint

​Path parameters

​Example request

​Example response

​Error Responses

​Invalid URL (400)

​Missing required field (400)

​Not found (404)

Fiat Integrations

Base URL

Authentication

List Integrations

Endpoint

Query parameters

Example request

Example response

Response fields

Create Integration

Endpoint

Request body

Example request

Example response

Update Integration

Endpoint

Path parameters

Request body

Example: add a contact URL

Example: remove a contact URL

Example response

Delete Integration

Endpoint

Path parameters

Example request

Example response

Error Responses

Invalid URL (400)

Missing required field (400)

Not found (404)