Payments

Settings

Read current runtime settings and update the exchange-rate adjustment percentage.

Flow Summary

The current settings flow is:

Step 1. Read current settings
GET /api/v2/settings

Step 2. Update exchange-rate adjustment percentage
PATCH /api/v2/settings/exchange-rate-adjustment-percentage

Both routes should be treated as protected and require Authorization.

Important Access Note

  • treat both routes as protected
  • use them only in authenticated agent or operator flows

1. Get Current Settings

GET /api/v2/settings

Returns the singleton settings row as an array with exactly one object.

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": [
    {
      "is_topup_enabled": false,
      "is_static_wallet_enabled": true,
      "is_auto_approve_kyc": false,
      "is_auto_approve_card_request": false,
      "wallet_address": "T...",
      "is_withdrawal_enabled": true,
      "withdrawal_fee_rate": "1.5",
      "exchange_rate_adjustment_percentage": "3.5",
      "hold_withdrawal_card_id": 12,
      "hold_withdrawal_card_uuid": "d4c7..."
    }
  ]
}

Important backend behavior

  • the response currently wraps the settings object in an array with one item
  • withdrawal_fee_rate and exchange_rate_adjustment_percentage are returned as decimal values ready for display
  • hold_withdrawal_card_uuid may be empty when no hold card is configured

Error behavior

  • if no settings record is configured, the request fails

2. Update Exchange Rate Adjustment Percentage

PATCH /api/v2/settings/exchange-rate-adjustment-percentage

Updates the exchange-rate adjustment percentage using a string payload.

Request body

{
  "exchange_rate_adjustment_percentage": "3.5"
}

Validation rules

  • the field is parsed as a decimal string
  • empty values are rejected
  • valid range is 0 to 99.99
  • more than two decimal places are rejected
  • the value is scaled by 100 before storage

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "exchange_rate_adjustment_percentage": "3.5"
  }
}

Important backend behavior

  • this endpoint updates only exchange_rate_adjustment_percentage
  • the response echoes the original request string, not the normalized stored value

Security caveat

  • this route updates a global runtime setting
  • expose it only in trusted operator tools

Integration Notes

  1. Treat GET /api/v2/settings as an authenticated bootstrap read for runtime flags.
  2. Do not assume data is an object; it is currently an array with one item.
  3. If you expose the patch route in any client tool, keep it limited to trusted operator users.
Copyright © 2026