API docs by Redocly

Fintechini Merchant API (sha-aca782e)

Download OpenAPI specification:Download

Payment

Платежи: создание заказов, состояние и сверка.

Создать входящий платёж

В ответе приходит redirect_url — адрес платёжной страницы, на которую нужно отправить плательщика.

Запрос идемпотентен по order_id: повтор с теми же суммой и валютой вернёт тот же платёж, а не создаст второй. Повтор с другой суммой — отказ DUPLICATE_ORDER.

Подписывается сырое тело запроса байт в байт. Не пересобирайте JSON перед подписью: порядок полей и пробелы влияют на результат.

header Parameters
x-api-key
required
string
x-signature
required
string
Request Body schema:
order_id
required
string
customer_account_id
integer or null <int64>

Идентификатор плательщика в системе мерчанта. Используется антифродом, чтобы связывать попытки одного и того же клиента.

amount
required
number

Сумма платежа в валюте currency. Больше нуля.

currency
required
string

Валюта платежа, ISO 4217 alpha-3, например RUB.

method
required
string

Способ оплаты, например SberPay. Допустимые значения возвращает GET /v2/merchant/methods.

country
required
string

Страна плательщика, ISO 3166-1 alpha-2 в нижнем регистре, например ru. Допустимые значения возвращает GET /v2/merchant/methods.

callback_url
required
string

Адрес, куда платформа пришлёт уведомление об изменении состояния.

success_url
string or null

Куда вернуть плательщика после успешной оплаты.

fail_url
string or null

Куда вернуть плательщика после неуспешной оплаты.

object (CustomerField)

Responses

Request samples

Content type
{
  • "order_id": "string",
  • "customer_account_id": 0,
  • "amount": 0,
  • "currency": "string",
  • "method": "string",
  • "country": "string",
  • "callback_url": "string",
  • "success_url": "string",
  • "fail_url": "string",
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "transaction_id": "string",
  • "redirect_url": "string"
}

Создать исходящий платёж

Идемпотентен по order_id так же, как приём. Подписывается сырое тело запроса байт в байт.

header Parameters
x-api-key
required
string
x-signature
required
string
Request Body schema:
order_id
required
string
customer_account_id
integer or null <int64>

Идентификатор получателя в системе мерчанта.

amount
required
number

Сумма выплаты в валюте currency. Больше нуля.

currency
required
string

Валюта выплаты, ISO 4217 alpha-3.

method
required
string

Способ выплаты. Допустимые значения возвращает GET /v2/merchant/methods.

country
required
string

Страна получателя, ISO 3166-1 alpha-2 в нижнем регистре.

callback_url
required
string

Адрес для уведомлений об изменении статуса.

account_number
required
string

Реквизит получателя: номер карты или телефон.

object (CustomerField)

Responses

Request samples

Content type
{
  • "order_id": "string",
  • "customer_account_id": 0,
  • "amount": 0,
  • "currency": "string",
  • "method": "string",
  • "country": "string",
  • "callback_url": "string",
  • "account_number": "string",
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "transaction_id": "string"
}

Узнать состояние заказа

Ищет и среди входящих, и среди исходящих платежей — помнить, чем был заказ, не нужно. Отдаются только заказы вызывающего мерчанта.

Тела у запроса нет, поэтому подписывается строка {unix_timestamp}.{path}. Для метки 1756123456 и заказа order-1001 это 1756123456./v2/payments/status/order-1001.

path Parameters
orderId
required
string

Идентификатор заказа, присвоенный мерчантом при создании.

header Parameters
x-api-key
required
string

Идентификатор мерчанта.

x-signature
required
string

HMAC-SHA256 от строки {unix_timestamp}.{path}.

x-timestamp
required
string

Время запроса в секундах Unix.

Responses

Response samples

Content type
application/json
{
  • "order_id": "string",
  • "transaction_id": "string",
  • "type": "DEPOSIT",
  • "status": "PENDING",
  • "failure_reason": "string",
  • "amount": 0,
  • "currency": "string",
  • "method": "string",
  • "country": "string",
  • "account_number": "string",
  • "destination_account_number": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}

Список входящих платежей

Для сверки в конце дня. Все поля фильтра необязательны: пустое тело {} вернёт последние заказы. Элементы списка — тот же объект, что отдаёт запрос состояния, так что разбор нужен один.

Подписывается сырое тело запроса, даже если это {}.

header Parameters
x-api-key
required
string
x-signature
required
string
Request Body schema:
limit
integer or null <int32>

Сколько записей вернуть. От 1 до 500, по умолчанию 50.

offset
integer or null <int32>

Сколько записей пропустить. По умолчанию 0.

order_id
string or null

Точный номер заказа мерчанта. Если задан, остальные фильтры не нужны.

status
string or null
Enum: "PENDING" "SUCCESS" "FAILED"

Оставить только заказы в этом состоянии.

created_from
string or null <date-time>

Нижняя граница времени создания, UTC, включительно.

created_to
string or null <date-time>

Верхняя граница времени создания, UTC, исключительно. Граница не включается намеренно: при посуточной выгрузке соседние сутки не пересекаются и записи не задваиваются.

Responses

Request samples

Content type
{
  • "limit": 0,
  • "offset": 0,
  • "order_id": "string",
  • "status": "PENDING",
  • "created_from": "2019-08-24T14:15:22Z",
  • "created_to": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Список исходящих платежей

Устроен так же, как список входящих.

header Parameters
x-api-key
required
string
x-signature
required
string
Request Body schema:
limit
integer or null <int32>

Сколько записей вернуть. От 1 до 500, по умолчанию 50.

offset
integer or null <int32>

Сколько записей пропустить. По умолчанию 0.

order_id
string or null

Точный номер заказа мерчанта. Если задан, остальные фильтры не нужны.

status
string or null
Enum: "PENDING" "SUCCESS" "FAILED"

Оставить только заказы в этом состоянии.

created_from
string or null <date-time>

Нижняя граница времени создания, UTC, включительно.

created_to
string or null <date-time>

Верхняя граница времени создания, UTC, исключительно. Граница не включается намеренно: при посуточной выгрузке соседние сутки не пересекаются и записи не задваиваются.

Responses

Request samples

Content type
{
  • "limit": 0,
  • "offset": 0,
  • "order_id": "string",
  • "status": "PENDING",
  • "created_from": "2019-08-24T14:15:22Z",
  • "created_to": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Отменить заказ

Одна отмена на оба направления: заказ ищется и среди входящих, и среди исходящих. В версии v1 для этого было два разных эндпоинта, и мерчанту приходилось помнить, чем был заказ.

Отменить можно только незавершённый заказ. По завершённому приходит отказ, а не молчаливый успех.

Тело обязательно, пусть даже {}: подпись считается по нему.

path Parameters
orderId
required
string
header Parameters
x-api-key
required
string
x-signature
required
string
Request Body schema:
reason
string or null

Почему отменяем. Свободный текст, попадает в историю заказа.

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "order_id": "string",
  • "transaction_id": "string",
  • "type": "DEPOSIT",
  • "status": "PENDING",
  • "failure_reason": "string",
  • "amount": 0,
  • "currency": "string",
  • "method": "string",
  • "country": "string",
  • "account_number": "string",
  • "destination_account_number": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}

Чеки по выплате

Подтверждения перевода, приложенные исполнителем. Только для исходящих заказов. Подписывается строка {unix_timestamp}.{path}.

path Parameters
orderId
required
string
header Parameters
x-api-key
required
string
x-signature
required
string
x-timestamp
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Merchant

Учётная запись мерчанта: профиль, остатки и доступные способы оплаты.

Профиль мерчанта

header Parameters
x-api-key
required
string

Идентификатор мерчанта.

x-signature
required
string

HMAC-SHA256 от строки {unix_timestamp}.{path}.

x-timestamp
required
string

Время запроса в секундах Unix.

Responses

Response samples

Content type
application/json
{
  • "merchant_id": "string",
  • "name": "string",
  • "callback_url": "string",
  • "max_active_payments": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Остатки на балансах

settlement — оборотный баланс: на него зачисляется приём и с него уходят выплаты. deposit — обеспечительный.

header Parameters
x-api-key
required
string
x-signature
required
string
x-timestamp
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Доступные способы оплаты и выплаты

С этого эндпоинта начинается интеграция: значения полей method, country и currency подставляются в запрос создания заказа дословно. Комиссия платформы возвращается здесь же.

header Parameters
x-api-key
required
string
x-signature
required
string
x-timestamp
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Disputes

Споры по заказам.

Открыть спор

Подписывается сырое тело запроса байт в байт.

header Parameters
x-api-key
required
string
x-signature
required
string
Request Body schema:
order_id
required
string

Идентификатор заказа, по которому открывается спор.

amount
number or null

Оспариваемая сумма. Если не указана — весь заказ.

comment
string or null

Что произошло, своими словами. Это читает оператор.

receipt_url
string or null

Ссылка на чек или иное подтверждение.

Responses

Request samples

Content type
{
  • "order_id": "string",
  • "amount": 0,
  • "comment": "string",
  • "receipt_url": "string"
}

Response samples

Content type
application/json
{
  • "dispute_id": "string",
  • "order_id": "string",
  • "transaction_id": "string",
  • "status": "OPEN",
  • "amount": 0,
  • "comment": "string",
  • "receipt_url": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Список споров

Все поля фильтра необязательны. Подписывается сырое тело.

header Parameters
x-api-key
required
string
x-signature
required
string
Request Body schema:
limit
integer or null <int32>

Сколько записей вернуть. От 1 до 500, по умолчанию 50.

offset
integer or null <int32>

Сколько записей пропустить. По умолчанию 0.

status
string or null
Enum: "OPEN" "IN_PROGRESS" "ACCEPTED" "REJECTED" "RETURNED"

Оставить только споры в этом состоянии.

Responses

Request samples

Content type
{
  • "limit": 0,
  • "offset": 0,
  • "status": "OPEN"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Состояние спора

Тела у запроса нет, поэтому подписывается строка {unix_timestamp}.{path}, а метка передаётся заголовком x-timestamp.

path Parameters
disputeId
required
string
header Parameters
x-api-key
required
string
x-signature
required
string
x-timestamp
required
string

Responses

Response samples

Content type
application/json
{
  • "dispute_id": "string",
  • "order_id": "string",
  • "transaction_id": "string",
  • "status": "OPEN",
  • "amount": 0,
  • "comment": "string",
  • "receipt_url": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}