Payments
Settings
Read current runtime settings and update the exchange-rate adjustment percentage.
Flow Summary
The current settings flow is:
Step 1. Read current settingsGET /api/v2/settings
Step 2. Update exchange-rate adjustment percentagePATCH /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_rateandexchange_rate_adjustment_percentageare returned as decimal values ready for displayhold_withdrawal_card_uuidmay 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
0to99.99 - more than two decimal places are rejected
- the value is scaled by
100before 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
- Treat
GET /api/v2/settingsas an authenticated bootstrap read for runtime flags. - Do not assume
datais an object; it is currently an array with one item. - If you expose the patch route in any client tool, keep it limited to trusted operator users.