> ## 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 Payment Settings

> Read and update your default fiat service-fee payer (customer vs merchant) for card payments.

# Fiat Payment Settings

These endpoints let you **read and update your default service-fee payer** for fiat (card) payments.

This setting is used as the default for fiat checkout flows when `serviceFeePayer` is not explicitly provided per order.

You can represent the same setting in two UI-friendly ways:

* `serviceFeePayerDefault`: `"customer"` or `"merchant"`
* `customerPaysServiceFee`: `true` or `false`

***

## Endpoints

* `GET /api/fiat/settings`
* `PATCH /api/fiat/settings`

> These endpoints are protected. You must be authenticated.

***

## Base URL

All examples use:

* `https://www.niftipay.com`

***

## Authentication

These endpoints support **two authentication methods**:

### 1) API Key (recommended for integrations)

Send your API key in the `x-api-key` header.

```bash theme={null}
curl -X GET "https://www.niftipay.com/api/fiat/settings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"
```

### 2) Session cookie (browser / dashboard usage)

If you are authenticated via the dashboard.

***

# Get Fiat Settings

## Endpoint

`GET /api/fiat/settings`

Returns your current fiat settings.

### Response fields

| Field                    | Type    | Notes                                                          |
| ------------------------ | ------- | -------------------------------------------------------------- |
| `serviceFeePayerDefault` | string  | `"customer"` or `"merchant"`.                                  |
| `customerPaysServiceFee` | boolean | Convenience boolean for UI toggle. `true` means customer pays. |

### Example request

```bash theme={null}
curl -X GET "https://www.niftipay.com/api/fiat/settings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Example response (customer pays by default)

```json theme={null}
{
  "serviceFeePayerDefault": "customer",
  "customerPaysServiceFee": true
}
```

### Example response (merchant pays by default)

```json theme={null}
{
  "serviceFeePayerDefault": "merchant",
  "customerPaysServiceFee": false
}
```

***

# Update Fiat Settings

## Endpoint

`PATCH /api/fiat/settings`

Updates your default fiat service-fee payer.

### You can send either payload format

#### Option A — explicit enum

```json theme={null}
{ "serviceFeePayerDefault": "customer" }
```

or

```json theme={null}
{ "serviceFeePayerDefault": "merchant" }
```

#### Option B — boolean toggle (UI friendly)

```json theme={null}
{ "customerPaysServiceFee": true }
```

or

```json theme={null}
{ "customerPaysServiceFee": false }
```

> `true` maps to `"customer"` and `false` maps to `"merchant"`.

***

## Example: set default to customer pays

```bash theme={null}
curl -X PATCH "https://www.niftipay.com/api/fiat/settings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "serviceFeePayerDefault": "customer" }'
```

### Example response

```json theme={null}
{
  "ok": true,
  "serviceFeePayerDefault": "customer",
  "customerPaysServiceFee": true
}
```

***

## Example: set default to merchant pays (using boolean)

```bash theme={null}
curl -X PATCH "https://www.niftipay.com/api/fiat/settings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "customerPaysServiceFee": false }'
```

### Example response

```json theme={null}
{
  "ok": true,
  "serviceFeePayerDefault": "merchant",
  "customerPaysServiceFee": false
}
```

***

# Error responses

## Invalid JSON (400)

If the request body is not valid JSON:

```json theme={null}
{ "error": "Invalid JSON" }
```

## Invalid payload (400)

If you don’t provide a valid payer using one of the supported formats:

```json theme={null}
{
  "error": "Provide either \"serviceFeePayerDefault\" (\"customer\"|\"merchant\") or \"customerPaysServiceFee\" (boolean)."
}
```

Examples that will fail:

* `{ "serviceFeePayerDefault": "user" }`
* `{ "customerPaysServiceFee": "sometimes" }`
* `{}`

## Missing migration/table (500)

This route requires the fiat settings table to exist for writes.

If the `userFiatSetting` table is missing, PATCH returns:

```json theme={null}
{
  "error": "Missing table \"userFiatSetting\". Apply the SQL migration first."
}
```

## Generic write failure (500)

If a database write fails, you’ll get:

```json theme={null}
{ "error": "Failed to save settings" }
```

(or a more specific database error message).