Cascade API Integration Documentation

Introduction

This document describes the process of connecting and integrating your cascade with our platform. This integration allows your service to accept payments initiated by our platform. All communication occurs via JSON format.

---

Cascade Dashboard

A dedicated dashboard will be created for your cascade, allowing you to:

• View transaction history;
• Top-up your balance;
• Withdraw funds;
• Configure settings for your integration.

Getting Started

To successfully integrate and start receiving payments, you must:

1. Specify the URL of your API endpoint in the dashboard, which will receive requests from us.
2. Top-up your balance
   warning

   You must top-up your balance on our platform to start working. Payments will only be accepted if your balance is positive, and the payment amount does not exceed your current balance.

3. Specify an API key, which will be sent in the headers of each request for authentication:

x-api-key: your-api-key

API Implementation

You must implement a single POST endpoint to process events sent by our system.

Request Structure

Each request sent to your server will have the following structure:

{
  "event": "CascadeEvents.CREATE_PAYMENT",
  "data": {
    ...
  }
}

Enums

Events:

enum CascadeEvents {
  CREATE_PAYMENT = 'CREATE_PAYMENT',
  GET_PAYMENT = 'GET_PAYMENT',
  CREATE_APPEAL = 'CREATE_APPEAL',
  CANCEL_APPEAL = 'CANCEL_APPEAL',
  CANCEL_PAYMENT = 'CANCEL_PAYMENT',
  CONFIRM_APPEAL = 'CONFIRM_APPEAL',
}

Payment Statuses:

enum CascadePaymentStatus {
  PENDING = 'pending',
  SUCCESS = 'success',
  FAILED = 'failed',
  APPEAL = 'appeal',
}

Requisite Methods:

enum RequisiteMethod {
  ACCOUNT = 'account',
  SBP = 'sbp',
  CARD = 'card',
}

Event: CREATE_PAYMENT

Example Request

To create a new payment, the following request will be sent:

{
  "event": "CascadeEvents.CREATE_PAYMENT",
  "data": {
    "amount": 3900.00,
    "method": "card",
    "currencyRate": 85.5,
    "currency": "RUB",
    "transactionWindowInMin": 30
  }
}

warning

Important: When transactionWindowInMin is provided, you must ensure the payment remains active and payable during this specified timeframe. The payment should not be canceled during this period.

Request Parameters

Field	Description	Type	Example
amount	Payment amount in the specified currency	number	3900.00
method	Payment method (card, sbp, account)	string	card
currencyRate	Exchange rate for the currency	number	85.5
currency	Payment currency (ISO currency code)	string	RUB
transactionWindowInMin	Time (in minutes) before the transaction expires	number	30

Expected Response

Your server must return a JSON response describing the created transaction:

{
  "id": "your-unique-transaction-id",
  "status": "pending",
  "bank": "Sberbank",
  "owner": "Ivan Ivanov",
  "cardNumber": "5363 5423 1029 7979"
}

Response Parameters

Field	Description	Type	Required for methods
id	Unique transaction identifier in your system	string	✅
status	Transaction status (pending, success, etc.)	enum	✅
bank	Human-readable bank name	string	✅
owner	Owner's full name	string	✅
cardNumber	Card number	string	Only for card
accountNumber	Bank account number	string	Only for account
sbpNumber	Phone number for SBP payments	string	Only for sbp

Error Handling

• If the transaction cannot be created, your server must respond with an appropriate 4xx HTTP status and detailed error description in the response body.
• HTTP status 20x should be returned only for successful transaction creation.

Event: GET_PAYMENT

Periodically, we will request information about the transaction.

Example Request

{
  "event": "CascadeEvents.GET_PAYMENT",
  "data": { "id": "uniq-id" }
}

Expected Response

Your server must respond with the current status of the transaction:

{ "status": "success" }

Event: CANCEL_PAYMENT

Request to cancel an existing transaction, indicating that the transaction is no longer relevant and may be canceled on your side.

Example Request

{
  "event": "CascadeEvents.CANCEL_PAYMENT",
  "data": { "id": "uniq-id" }
}

Expected Response

Your server must respond with HTTP status 200 or 201.

Event: CREATE_APPEAL

This event informs you about an appeal regarding your transaction. id is your unique transaction identifier from transaction creation, and amount is the new transaction amount. This event indicates the customer sent a different amount or, in rare cases, if the transaction was canceled. The amount can match the original transaction amount only if the transaction had a failed status, and the customer reported the payment was made.

Example Request

{
  "event": "CascadeEvents.CREATE_APPEAL",
  "data": { "id": "uniq-id", "amount": 4000, "url": "http://exampel.com/example.pdf" }
}

Expected Response

Your server must respond with HTTP status 200 or 201. Optionally:

{ "appealId": "string" }

Event: CANCEL_APPEAL

This request cancels a previously created appeal. id will be appealId which you return for CascadeEvents.CREATE_APPEAL

Example Request

{
  "event": "CascadeEvents.CANCEL_APPEAL",
  "data": { "id": "appealId" }
}

Expected Response

Your server must respond with HTTP status 200 or 201.

Event: CONFIRM_APPEAL

This request confirms an appeal after agreement with your trading department. The amount specified during appeal creation will be deducted from your balance. id will be appealId which you return for CascadeEvents.CREATE_APPEAL

Example Request

{
  "event": "CascadeEvents.CONFIRM_APPEAL",
  "data": { "id": "appealId" }
}

Expected Response

Your server must respond with HTTP status 200 or 201.

---

Further events will be described in subsequent documentation sections.