payouts/README.md

# Payouts Service

## API Endpoints

### User Management

#### Register User
- **Path**: `/api/v1/user/register`
- **Method**: POST
- **Request Parameters**:
  ```json
  {
    "tin": "string",
    "phone": "string",
    "password": "string",
    "password_cfm": "string"
  }
  ```
- **Response Parameters**:
  ```json
  {
    "status": "string"
  }
  ```
- **Curl Example**:
  ```bash
  curl -X POST http://localhost:8080/api/v1/user/register \
    -H "Content-Type: application/json" \
    -d '{"tin":"1234567890","phone":"+79991234567","password":"password123","password_cfm":"password123"}'
  ```

#### User Login
- **Path**: `/api/v1/user/login`
- **Method**: POST
- **Request Parameters**:
  ```json
  {
    "phone": "string",
    "password": "string"
  }
  ```
- **Response Parameters**:
  ```json
  {
    "token": "string",
    "token_ttl": "integer"
  }
  ```
- **Curl Example**:
  ```bash
  curl -X POST http://localhost:8080/api/v1/user/login \
    -H "Content-Type: application/json" \
    -d '{"phone":"+79991234567","password":"password123"}'
  ```

### Payout Operations

#### Get SBP Banks
- **Path**: `/api/v1/payout/sbp/banks`
- **Method**: GET
- **Request Parameters**: None
- **Response Parameters**:
  ```json
  [
      {
        "bank_id": "string",
        "name": "string",
        "bic": "string"
      }
  ]
  ```
- **Curl Example**:
  ```bash
  curl -X GET http://localhost:8080/api/v1/payout/sbp/banks
  ```

#### Create Payout
- **Path**: `/api/v1/payout/create`
- **Method**: POST
- **Request Parameters: SBP**:
  ```json
  {
    "payout_type": "spb",
    "bank_id": "string",
    "amount": "float"
  }
  ```
> **_NOTE:_**
> Phone number for SBP payout comes from user's profile

- **Request Parameters: YooMoney**:
  ```json
  {
    "payout_type": "yoo_money",
    "account_number": "string",
    "amount": "float"
  }
  ```
- **Response Parameters**:
  ```json
  {
    "payout_id": "string",
    "payout_status": "string"
  }
  ```
- **Curl Example**:
  ```bash
  curl -X POST http://localhost:8080/api/v1/payout/create \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <session_token>" \
    -d '{"payout_type":"spb","bank_id":"123456","amount":10.00}'
  ```

#### Payout Callback
- **Path**: `/api/v1/payout/callback`
- **Method**: POST
- **Request Parameters**: YooKassa webhook data (JSON)
- **Response Parameters**: None
- **Curl Example**:
  ```bash
  curl -X POST http://localhost:8080/api/v1/payout/callback \
    -H "Content-Type: application/json" \
    -d '{"id":"payout_123456","status":"succeeded","amount":{"value":"10.00","currency":"RUB"}}'
  ```

## Service Configuration

### Server Configuration
| Property | Description | Default Value |
|----------|-------------|---------------|
| Server.Tls.Enabled | Enable TLS for the server | false |
| Server.Tls.CertFile | Path to TLS certificate file | (empty) |
| Server.Tls.KeyFile | Path to TLS key file | (empty) |
| Server.Port | Server port | :8080 |
| Server.WriteTimeout | Write timeout for requests | 35s |
| Server.ReadTimeout | Read timeout for requests | 35s |
| Server.EnablePProfEndpoints | Enable pprof debug endpoints | false |

### Database Configuration
| Property | Description | Default Value |
|----------|-------------|---------------|
| Database.Type | Database type (sqlite, postgres) |  (empty) |
| Database.Connection | Database connection string |  (empty)  |
| Database.LogLevel | Database logging level | Info |
| Database.TraceRequests | Enable request tracing | false |

### YooKassa Configuration
| Property | Description | Default Value |
|----------|-------------|---------------|
| YooKassa.Test | Enable test mode | false |
| YooKassa.ApiBaseKey | YooKassa base API key | (empty) |
| YooKassa.ApiBaseSecret | YooKassa base API secret | (empty) |
| YooKassa.ApiPaymentKey | YooKassa payment API key | (empty) |
| YooKassa.ApiPaymentSecret | YooKassa payment API secret | (empty) |
| YooKassa.BaseUrl | YooKassa API base URL | https://api.yookassa.ru/v3 |
| YooKassa.Timeout | Request timeout | 2s |
| YooKassa.CheckAllowedCallbackAddress | Check callback IP addresses | true |
| YooKassa.AllowedCallbackSubnets | Allowed callback IP subnets | (list of allowed subnets) |
| YooKassa.CallbackProcessTimeout | Delay to process YooKassa allback | 1s |
| YooKassa.Retry.Enabled | Enable request retries | false |
| YooKassa.Retry.Count | Number of retry attempts | 3 |
| YooKassa.Retry.WaitTime | Initial wait time between retries | 200ms |
| YooKassa.Retry.MaxWaitTime | Maximum wait time between retries | 5s |

### Cache Configuration
| Property | Description | Default Value |
|----------|-------------|---------------|
| Cache.TTL | Session TTL | 24h |

### Logging Configuration
| Property | Description | Default Value |
|----------|-------------|---------------|
| Log.Level | Log level | DEBUG |
| Log.FilePath | | ./logs/payouts.log
| Log.TextOutput | | false
| Log.StdoutEnabled | | true
| Log.FileEnabled | | false