Interaction Scenarios for Conducting Payouts

Complete description of end-to-end scenarios for working with the payouts system, including sequence diagrams and step-by-step instructions.

Scenarios Overview

The payouts system supports two main interaction methods depending on user needs:

  • Interface payouts - working through the personal dashboard web interface
  • API payouts - integration with external systems through REST API

Each method supports both bank card payouts and SBP (Fast Payment System) payouts.

Interface Payouts

Working with the system through the personal dashboard web interface. Supports both mass payouts via files and single payouts via forms.

1.1. File-based payouts (Cards/SBP)

Process for mass payouts via file upload. Supported directions: bank cards and SBP.

Process Description

  1. User uploads file with recipient data or fills single payout form
  2. System validates recipient data (card number, amount, full name)
  3. User confirms payout creation
  4. System creates payout records in database
  5. Background processes handle payouts through banking API
  6. User tracks status through interface
  7. Receives notifications about results

Sequence Diagram

sequenceDiagram participant U as User participant UI as Personal Dashboard participant SYS as Payouts System participant BANK as Bank processing activate U U->>UI: Uploads file (Cards/SBP) activate UI UI->>SYS: Send file for validation activate SYS SYS->>SYS: Save file (draft) SYS-->>UI: Preview (validated data) deactivate SYS UI-->>U: Show preview deactivate UI deactivate U activate U U->>UI: Confirms payout creation activate UI UI->>SYS: Create payouts command activate SYS SYS->>SYS: Create payout records SYS-->>UI: Successful creation deactivate SYS UI->>U: Display results deactivate UI loop Payout processing (async) activate SYS SYS->>SYS: Get tasks SYS->>BANK: Execute payout activate BANK BANK-->>SYS: Operation result deactivate BANK SYS->>SYS: Update status deactivate SYS end U->>UI: Checks payout status activate UI UI->>SYS: Request statuses activate SYS SYS->>SYS: Get data SYS-->>UI: Payout data deactivate SYS UI-->>U: Display results deactivate UI deactivate U

1.2. Manual single payout

Creating a single payout via form in the interface: bank card or SBP.

Process Description

  1. User opens the single payout form
  2. Enters recipient data (card or SBP: phone, bank, full name) and amount
  3. System validates data in real time
  4. User confirms creation
  5. System creates payout record and starts processing
  6. Status updates asynchronously; notifications are available

Sequence Diagram

sequenceDiagram participant U as User participant UI as Personal Dashboard participant SYS as Payouts System participant BANK as Bank processing activate U U->>UI: Opens single payout form activate UI UI-->>U: Opens single payout form deactivate UI U->>UI: Enters details (card/SBP) and amount activate UI UI->>SYS: Online validation activate SYS SYS-->>UI: Validation result deactivate SYS UI-->>U: Shows validation result deactivate UI U->>UI: Confirms creation activate UI UI->>SYS: Create payout activate SYS SYS->>SYS: Save payout SYS-->>UI: Creation accepted deactivate SYS UI-->>U: Shows creation result deactivate UI Note over SYS,BANK: Asynchronous processing activate SYS SYS->>BANK: Send payout activate BANK BANK-->>SYS: Operation result deactivate BANK SYS->>SYS: Update status deactivate SYS U->>UI: Checks payout status activate UI UI->>SYS: Request statuses activate SYS SYS->>SYS: Get data SYS-->>UI: Payout data deactivate SYS UI-->>U: Display results deactivate UI deactivate U

API Payouts

Integration with external systems through REST API. Supports two work modes: creating application with redirect to system page or full execution through API.

2.1. Creating Application via createPayout

External system creates payout application, user redirects to system page for confirmation.

Process Description

  1. External system obtains Bearer token for authorization
  2. Creates payout application via createPayout API
  3. System validates data and creates application
  4. Returns URL for user redirect
  5. User follows link and confirms payout
  6. System executes payout through banking API
  7. External system can request status via getPayoutStatus

Sequence Diagram

sequenceDiagram participant ES as External System participant API as Payouts API participant U as User participant UI as Confirmation Page participant SYS as Payouts System participant BANK as Bank processing activate ES ES->>API: POST /api/v1/createPayout
(Bearer token, payout data) activate API API->>SYS: Data validation activate SYS SYS-->>API: Application created deactivate SYS API-->>ES: 200 OK (URL для подтверждения) deactivate API ES->>U: Redirect to URL deactivate ES activate U U->>UI: Opens confirmation page activate UI UI->>SYS: Get application data activate SYS SYS-->>UI: Application data deactivate SYS UI-->>U: Shows confirmation data deactivate UI U->>UI: Confirms payout activate UI UI->>SYS: Execute payout activate SYS par Обработка и отображение результата SYS-->>UI: Notification about acceptance and redirect to result page deactivate SYS UI-->>U: Redirect to result page deactivate UI U->>UI: Opens result page activate UI SYS->>BANK: Send to bank activate SYS activate BANK BANK-->>SYS: Operation result deactivate BANK end loop Payout processing UI->>SYS: Request status SYS-->>UI: Execution status deactivate SYS UI-->>U: Operation result deactivate UI deactivate U end activate ES ES->>API: GET /api/v1/getPayoutStatus
(application ID) activate API API->>SYS: Request status activate SYS SYS-->>API: Current status deactivate SYS API-->>ES: 200 OK (status and details) deactivate API deactivate ES

2.2. Full Execution via performPayout

External system creates payout application via API, system executes payout asynchronously in background.

Process Description

  1. External system obtains Bearer token for authorization
  2. Creates payout application via performPayout API
  3. System validates data, creates application and immediately returns response
  4. Background processes asynchronously execute payout through banking API
  5. External system can request status via getPayoutStatus

Sequence Diagram

sequenceDiagram participant ES as External System participant API as Payouts API participant SYS as Payouts System participant BANK as Bank processing activate ES ES->>API: POST /api/v1/performPayout
(Bearer token, payout data) activate API API->>SYS: Data validation activate SYS SYS->>SYS: Create application SYS-->>API: Application accepted deactivate SYS API-->>ES: 200 OK (application created) deactivate API deactivate ES Note over SYS,BANK: Asynchronous processing in background loop Payout processing SYS->>SYS: Get tasks activate SYS SYS->>BANK: Execute payout BANK-->>SYS: Operation result SYS->>SYS: Update status deactivate SYS end activate ES ES->>API: GET /api/v1/getPayoutStatus
(application ID) activate API API->>SYS: Request status activate SYS SYS->>SYS: Get data SYS-->>API: Application status deactivate SYS API-->>ES: 200 OK (status and details) deactivate API deactivate ES

2.3. Card Payouts via API

Specifics of working with bank cards through API.

Features

  • Requires card number encryption with public key
  • Idempotency support through orderNumber
  • Automatic access token and public key retrieval
  • Integration with VTB banking API

2.4. SBP Payouts via API

Specifics of working with SBP through API.

Features

  • Requires recipient phone in 79XXXXXXXXX format
  • Mandatory recipient bank and full name specification
  • Two-stage process: CHECK → CONFIRM
  • Automatic SBP status processing

Error Handling and Exception Scenarios

Standard error handling scenarios for all payout types.

Error Types

  • Validation errors - incorrect recipient data
  • Authorization errors - invalid token or insufficient permissions
  • Banking API errors - payment processing issues
  • System errors - service unavailability
  • Limit errors - exceeding established restrictions

Error Handling Scenario

sequenceDiagram participant U as User/System participant API as System API participant VAL as Validator participant BANK as Bank processing participant LOG as Logger participant RETRY as Retry System U->>API: Payout request API->>VAL: Data validation alt Validation error VAL-->>API: Validation error API->>LOG: Error logging API-->>U: 400 Bad Request else Data correct API->>BANK: Execute payout alt Bank error BANK-->>API: Operation error API->>LOG: Error logging API->>RETRY: Schedule retry API-->>U: 502 Bad Gateway else Successful operation BANK-->>API: Success API-->>U: 200 OK end end

Monitoring and Notifications

System monitoring and user notification system.

Notification Channels

  • Web Interface - notifications in personal dashboard
  • Telegram - push notifications in bot
  • Email - messages to registered address
  • API - webhook notifications for external systems

Notification System Diagram

sequenceDiagram participant PROC as Payout Processor participant NOTIF as Notification System participant TG as Telegram Bot participant EMAIL as Email Service participant WEB as Web Interface participant WH as Webhook PROC->>PROC: Update payout status PROC->>NOTIF: Trigger notification par User notifications NOTIF->>WEB: Interface update NOTIF->>TG: Push notification NOTIF->>EMAIL: Email notification and System notifications NOTIF->>WH: Webhook notification end

Recommendations and Best Practices

For Developers

  • Always use idempotency keys to prevent duplication
  • Implement retry logic with exponential backoff
  • Validate data on client side before sending
  • Use webhook notifications for status tracking
  • Log all operations for debugging and auditing

For Users

  • Check recipient data before creating payouts
  • Use test payouts to verify settings
  • Configure Telegram notifications for operational control
  • Regularly check reports and statistics
  • Monitor system limits and quotas