Errors

# Любой /api/v1/* endpoint при неуспехе отдаёт конверт ошибки.
# Пример: недостаточно средств под sell → 402.
curl -i -X POST https://fin-os.io/api/v1/customers/$UUID/payments/sell \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_usdt": 999999, "bank_id": "sber", "phone": "+79001234567"}'

# HTTP/1.1 402 Payment Required
# {
#   "error": {
#     "code": "insufficient_funds",
#     "message": "Недостаточно средств для операции.",
#     "request_id": "req_7Kp2Rt9Wx4Yz1Qb6Nm3Vc8L"
#   }
# }

# Невалидное тело → 422 с объектом fields:
curl -i -X POST https://fin-os.io/api/v1/customers/$UUID/payments/buy \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_rub": 5}'
# HTTP/1.1 422 Unprocessable Entity
# { "error": { "code": "invalid_request", "request_id": "req_...",
#   "fields": { "amount_rub": ["..."], "bank_id": ["..."] } } }

// Единый разбор конверта ошибки для всех вызовов /api/v1/*
async function apiCall(path, opts = {}) {
  const res = await fetch(`https://fin-os.io/api/v1${path}`, {
    ...opts,
    headers: {
      'Authorization': `Bearer ${process.env.FINOS_SECRET_KEY}`, // sk_test_ или sk_live_
      'Content-Type': 'application/json',
      ...(opts.headers || {}),
    },
  });

  const body = await res.json();

  if (!res.ok) {
    const { code, message, request_id, fields } = body.error;
    switch (code) {
      case 'invalid_request':
        console.error('Validation failed:', fields);
        break;
      case 'unauthorized':
        console.error('Проверьте API-ключ (Bearer sk_...)');
        break;
      case 'insufficient_funds':
        console.error('Пополните баланс клиента');
        break;
      case 'rate_limited':
      case 'service_unavailable':
        // повторить с экспоненциальной задержкой (backoff)
        break;
    }
    // request_id - для обращения в поддержку
    throw Object.assign(new Error(message), { code, request_id, fields });
  }

  return body.data;
}

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

$response = Http::withToken($secretKey) // sk_test_ или sk_live_
    ->acceptJson()
    ->post("https://fin-os.io/api/v1/customers/{$uuid}/payments/sell", [
        'amount_usdt' => '10',
        'bank_id'     => 'sber',
        'phone'       => '+79001234567',
    ]);

if ($response->failed()) {
    $err = $response->json('error'); // ['code','message','request_id','fields'?]

    match ($err['code']) {
        'invalid_request'     => report_fields($err['fields'] ?? []),
        'insufficient_funds'  => notify_top_up($uuid),
        'rate_limited',
        'service_unavailable' => retry_later(),          // backoff + retry
        default               => Log::warning('B2B error', $err),
    };

    throw new \RuntimeException(
        "{$err['code']}: {$err['message']} (request_id: {$err['request_id']})"
    );
}

$data = $response->json('data');

import os, requests

FINOS = 'https://fin-os.io/api/v1'
KEY   = os.environ['FINOS_SECRET_KEY']  # sk_test_ или sk_live_
H     = {'Authorization': f'Bearer {KEY}', 'Content-Type': 'application/json'}

def api_call(method, path, **kwargs):
    resp = requests.request(method, f'{FINOS}{path}', headers=H, **kwargs)
    if not resp.ok:
        err = resp.json()['error']
        code = err['code']
        if code == 'invalid_request':
            print('Validation failed:', err.get('fields'))
        elif code == 'unauthorized':
            print('Проверьте API-ключ (Bearer sk_...)')
        elif code == 'insufficient_funds':
            print('Пополните баланс клиента')
        elif code in ('rate_limited', 'service_unavailable'):
            pass  # повторить с экспоненциальной задержкой (backoff)
        # request_id - указать при обращении в поддержку
        raise RuntimeError(
            f"{code}: {err['message']} (request_id: {err['request_id']})"
        )
    return resp.json()['data']