Skip to main content

​
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: Send your API key in the x-api-key header. 
curl -X GET "https://www.niftipay.com/api/fiat/settings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"
If you are authenticated via the dashboard.

​
Get Fiat Settings

​
Endpoint

GET /api/fiat/settings Returns your current fiat settings.

​
Response fields

FieldTypeNotes
serviceFeePayerDefaultstring"customer" or "merchant".
customerPaysServiceFeebooleanConvenience boolean for UI toggle. true means customer pays.

​
Example request

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)

{
  "serviceFeePayerDefault": "customer",
  "customerPaysServiceFee": true
}

​
Example response (merchant pays by default)

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

{ "serviceFeePayerDefault": "customer" }
or 
{ "serviceFeePayerDefault": "merchant" }

​
Option B — boolean toggle (UI friendly)

{ "customerPaysServiceFee": true }
or 
{ "customerPaysServiceFee": false }
true maps to "customer" and false maps to "merchant".

​
Example: set default to customer pays

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

{
  "ok": true,
  "serviceFeePayerDefault": "customer",
  "customerPaysServiceFee": true
}

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

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

{
  "ok": true,
  "serviceFeePayerDefault": "merchant",
  "customerPaysServiceFee": false
}

​
Error responses

​
Invalid JSON (400)

If the request body is not valid JSON: 
{ "error": "Invalid JSON" }

​
Invalid payload (400)

If you don’t provide a valid payer using one of the supported formats: 
{
  "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: 
{
  "error": "Missing table \"userFiatSetting\". Apply the SQL migration first."
}

​
Generic write failure (500)

If a database write fails, you’ll get: 
{ "error": "Failed to save settings" }
(or a more specific database error message).