Операции

Операция — единица работы с деньгами клиента: создание, чтение состояния, список активных и передача решения по операции.

List active operationsGET/api/v1/operations

listActiveOperationsНужен токен

Returns the caller's operations that have not reached a final status (COMPLETED, PARTIALLY_COMPLETED, FAILED, CANCELLED) with their current phase, the action expected from the client and open timeout events. Pages are cursor-based: pass nextCursor from the previous page as cursor.

Параметры запроса

Поле	Тип	Описание
`cursor`	string
`limit`	integer (int32)	по умолчанию 20

Ответы

`200`OK`ListActiveOperationsResponse`

Поле Тип Описание

itemsобязательно массив (объект ActiveOperationSummaryResponse)

operationIdобязательно string

clientOperationIdобязательно string

statusобязательно

string

Допустимые значения: CREATED IN_PROGRESS COMPLETED PARTIALLY_COMPLETED FAILED CANCELLED

phaseобязательно

string

Client-facing operational phase (ADR-0052). Distinct from status (lifecycle) and from internal log phase (logging-only).

Допустимые значения: PROCESSING AWAITING_CLIENT_PAYMENTS AWAITING_CLIENT_DECISION FINALIZED

requiredActionобязательно

string

Допустимые значения: NONE PERFORM_PAYMENTS SUBMIT_DECISION

requiredActionSince string (дата и время, ISO 8601)

requiredActionPayload

объект OperationRequiredActionPayloadResponse

Payload for required action

expectedDecisionVersion integer (int32)

allowedDecisionKinds

массив (string)

Допустимые значения: finalize_as_is adjust compensate_and_finalize

paymentsобязательно массив (объект OperationRequiredActionPaymentResponse)

paymentIdобязательно string

methodобязательно словарь (string)

amountобязательно

объект MoneyAmountResponse

Money amount representation

`currency`обязательно	string
`value`обязательно	string

linksобязательно словарь (string)

clientTransactionId string

status string

interaction

объект PaymentInteractionResponse

Payment interaction artifact (payer-facing link)

`type`обязательно	string
`url`обязательно	string
`expiresAt`	string (дата и время, ISO 8601)

createdAtобязательно string (дата и время, ISO 8601)

updatedAtобязательно string (дата и время, ISO 8601)

deadlineAt string (дата и время, ISO 8601)

activeTimeoutEvents массив (объект ActiveTimeoutEventResponse)

`eventType`обязательно	string	Тип события: EXECUTION_STUCK / AWAITING_PAYMENT_TOO_LONG / AWAITING_DECISION_TOO_LONG / TERMINAL_TIMEOUT (ADR-0097) Допустимые значения: `EXECUTION_STUCK` `AWAITING_PAYMENT_TOO_LONG` `AWAITING_DECISION_TOO_LONG` `TERMINAL_TIMEOUT`
`phase`	string	Фаза операции на момент detection. null для terminal timeout. Допустимые значения: `PROCESSING` `AWAITING_CLIENT_PAYMENTS` `AWAITING_CLIENT_DECISION` `FINALIZED`
`actionType`обязательно	string	Configured action для этого timeout-policy слота Допустимые значения: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`
`result`	string	Результат обработки. null — action ещё не применён. Допустимые значения: `NOTIFIED` `FINALIZED` `COMPENSATION_STARTED` `SKIPPED_ALREADY_HANDLED` `SKIPPED_NO_LONGER_APPLIES` `FAILED_TO_HANDLE`
`detectedAt`обязательно	string (дата и время, ISO 8601)	Когда событие было обнаружено
`handledAt`	string (дата и время, ISO 8601)	Когда action был применён. null — ещё не обработано.
`thresholdSeconds`	integer (int64)	Threshold, который вызвал событие
`deadlineAt`	string (дата и время, ISO 8601)	Дедлайн операции на момент detection

nextCursor string

Ошибки

Коды ошибок в контракте не описаны.

Create an operationPOST/api/v1/operations

createOperationНужен токен

Accepts a business operation — a sequence of money actions (payment, payout, refund) with execution policies — and starts executing it. The request is accepted as a whole and frozen at acceptance: later changes to settings do not affect it. Retrying with the same context.idempotencyKey and identical content returns the same operation; the same key with different content is rejected. The response carries operationId, the current status and phase, and the action expected from the client, if any.

Тело запросаобязательно`CreateOperationRequest`

Поле Тип Описание

settlementAccountIdобязательно

string

Settlement account ID that owns the operation

пример: 100500

typeобязательно

string

Допустимые значения: EXTERNAL_DECISION STANDARD

controls объект CreateOperationControlsRequest

timeoutPolicy объект CreateTimeoutPolicyRequest

thresholds объект CreateTimeoutPolicyThresholdsRequest

`terminalTimeoutSeconds`	integer (int64)
`processingStuckAfterSeconds`	integer (int64)
`awaitingDecisionAfterSeconds`	integer (int64)
`awaitingPaymentAfterSeconds`	integer (int64)

actions объект CreateTimeoutPolicyActionsRequest

onProcessingStuck объект TimeoutPolicyActionRequest

`type`обязательно	string	Допустимые значения: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`

onAwaitingDecisionTooLong объект TimeoutPolicyActionRequest

`type`обязательно	string	Допустимые значения: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`

onAwaitingPaymentTooLong объект TimeoutPolicyActionRequest

`type`обязательно	string	Допустимые значения: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`

onTerminalTimeout объект TimeoutPolicyActionRequest

`type`обязательно	string	Допустимые значения: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`

closurePolicy объект CreateClosurePolicyRequest

`onUnrecoverableExecution`	string	Допустимые значения: `KEEP_OPEN_UNTIL_TIMEOUT` `FINALIZE_AS_IS`

compensationPolicy объект CreateCompensationPolicyRequest

`refundMode`	string	Допустимые значения: `REFUND_ONLY` `ALLOW_PAYOUT`

webhookPolicy объект CreateWebhookPolicyRequest

`onCriticalDeliveryExhausted`	string

moneyобязательно массив (Один из вариантов)

Один из вариантов — Вариант выбирается значением поля kind

MoneyAwaitDecisionIntentRequestkind: await_decision

Await decision intent (business gate, ADR-0100)

`kind`обязательно	string	значение await_decision
`description`	string

MoneyPaymentIntentRequestkind: payment

Payment intent

kindобязательно

string

значение payment

amountобязательно

объект MoneyAmountRequest

Money amount representation

`currency`обязательно	string
`value`обязательно	string

methodобязательно Один из вариантов

Один из вариантов — Вариант выбирается значением поля kind

B2bSbpPaymentMethodRequestkind: sbp_b2b

B2B SBP payment method (ADR-0125)

`kind`обязательно	string	значение sbp_b2b
`paymentPurpose`обязательно	string	не длиннее 140
`sourceName`обязательно	string	не длиннее 50
`takeTax`обязательно	boolean
`totalTaxAmount`	integer (int64)	Сумма налога в копейках; обязательна при takeTax=true.

MirCardPaymentMethodRequestkind: mir_card

MIR card payment method

`kind`обязательно	string	значение mir_card
`token`обязательно	string

SbpPaymentMethodRequestkind: sbp_c2b

C2B SBP payment method

`kind`обязательно	string	значение sbp_c2b
`payerPhone`обязательно	string

capture boolean

metadata словарь (string)

businessRef

объект BusinessRefRequest

Опциональный business/audit label платежа (ADR-0110). Non-authoritative, не является ключом адресации.

`kind`обязательно	string
`id`обязательно	string

clientTransactionId

string

Client-facing идентификатор денежного действия (ADR-0110). Optional: если не передан, SettleOps заполняет его сам. После acceptance всегда присутствует.

MoneyPayoutIntentRequestkind: payout

Payout intent (ADR-0114)

kindобязательно

string

значение payout

amountобязательно

объект MoneyAmountRequest

Money amount representation

`currency`обязательно	string
`value`обязательно	string

destinationобязательно Один из вариантов

Один из вариантов — Вариант выбирается значением поля kind

SbpPayoutDestinationRequestkind: sbp

SBP payout destination

`kind`обязательно	string	значение sbp
`recipientPhone`обязательно	string
`recipientBankId`обязательно	string	Идентификатор банка получателя в справочнике СБП, ровно 12 цифр

metadata словарь (string)

businessRef

объект BusinessRefRequest

Опциональный business/audit label выплаты (ADR-0110). Non-authoritative, не является ключом адресации.

`kind`обязательно	string
`id`обязательно	string

clientTransactionId

string

contextобязательно

объект CreateOperationContextRequest

Operation context

idempotencyKeyобязательно string

clientOperationIdобязательно string

sourceобязательно string

businessRef

объект BusinessRefRequest

Опциональный business/audit label всей операции (ADR-0110). Не является machine-key и не влияет на исполнение.

`kind`обязательно	string
`id`обязательно	string

Ответы

`201`Created`CreateOperationResponse`

Поле Тип Описание

operationIdобязательно string

typeобязательно

string

Допустимые значения: EXTERNAL_DECISION STANDARD

statusобязательно

string

Допустимые значения: CREATED IN_PROGRESS COMPLETED PARTIALLY_COMPLETED FAILED CANCELLED

phaseобязательно

string

Client-facing operational phase (ADR-0052). Distinct from status (lifecycle) and from internal log phase (logging-only).

Допустимые значения: PROCESSING AWAITING_CLIENT_PAYMENTS AWAITING_CLIENT_DECISION FINALIZED

message string

requiredAction

string

Допустимые значения: NONE PERFORM_PAYMENTS SUBMIT_DECISION

requiredActionSince string (дата и время, ISO 8601)

requiredActionPayload

объект OperationRequiredActionPayloadResponse

Payload for required action

expectedDecisionVersion integer (int32)

allowedDecisionKinds

массив (string)

Допустимые значения: finalize_as_is adjust compensate_and_finalize

paymentsобязательно массив (объект OperationRequiredActionPaymentResponse)

paymentIdобязательно string

methodобязательно словарь (string)

amountобязательно

объект MoneyAmountResponse

Money amount representation

`currency`обязательно	string
`value`обязательно	string

linksобязательно словарь (string)

clientTransactionId string

status string

interaction

объект PaymentInteractionResponse

Payment interaction artifact (payer-facing link)

`type`обязательно	string
`url`обязательно	string
`expiresAt`	string (дата и время, ISO 8601)

linksобязательно массив (объект LinkResponse)

`rel`обязательно	string
`href`обязательно	string
`type`	string
`method`	string

Ошибки

Коды ошибок в контракте не описаны.

Get an operationGET/api/v1/operations/{operationId}

getOperationНужен токен

Returns the current state of an operation: status, phase, the action expected from the client with its payload (payments to perform or the decision to submit), the money actions with their outcomes, and open timeout events.

Параметры пути

Поле	Тип	Описание
`operationId`обязательно	string

Ответы

`200`OK`OperationViewResponse`

Поле Тип Описание

operationIdобязательно string

statusобязательно

string

Допустимые значения: CREATED IN_PROGRESS COMPLETED PARTIALLY_COMPLETED FAILED CANCELLED

typeобязательно

string

Допустимые значения: EXTERNAL_DECISION STANDARD

phaseобязательно

string

Client-facing operational phase (ADR-0052). Distinct from status (lifecycle) and from internal log phase (logging-only).

Допустимые значения: PROCESSING AWAITING_CLIENT_PAYMENTS AWAITING_CLIENT_DECISION FINALIZED

createdAt string (дата и время, ISO 8601)

finalizedAt string (дата и время, ISO 8601)

deadlineAt string (дата и время, ISO 8601)

finalizationReason

string

Допустимые значения: TERMINAL_TIMEOUT EXECUTION_STUCK AWAITING_PAYMENT_TOO_LONG AWAITING_DECISION_TOO_LONG CLIENT_COMPENSATED_AND_FINALIZED WEBHOOK_DELIVERY_EXHAUSTED

finalizationMode

string

Допустимые значения: FINALIZE_AS_IS COMPENSATE_AND_FINALIZE

requiredAction

string

Допустимые значения: NONE PERFORM_PAYMENTS SUBMIT_DECISION

requiredActionSince string (дата и время, ISO 8601)

requiredActionPayload

объект OperationRequiredActionPayloadResponse

Payload for required action

expectedDecisionVersion integer (int32)

allowedDecisionKinds

массив (string)

Допустимые значения: finalize_as_is adjust compensate_and_finalize

paymentsобязательно массив (объект OperationRequiredActionPaymentResponse)

paymentIdобязательно string

methodобязательно словарь (string)

amountобязательно

объект MoneyAmountResponse

Money amount representation

`currency`обязательно	string
`value`обязательно	string

linksобязательно словарь (string)

clientTransactionId string

status string

interaction

объект PaymentInteractionResponse

Payment interaction artifact (payer-facing link)

`type`обязательно	string
`url`обязательно	string
`expiresAt`	string (дата и время, ISO 8601)

links массив (объект LinkResponse)

`rel`обязательно	string
`href`обязательно	string
`type`	string
`method`	string

activeTimeoutEvents массив (объект ActiveTimeoutEventResponse)

`eventType`обязательно	string	Тип события: EXECUTION_STUCK / AWAITING_PAYMENT_TOO_LONG / AWAITING_DECISION_TOO_LONG / TERMINAL_TIMEOUT (ADR-0097) Допустимые значения: `EXECUTION_STUCK` `AWAITING_PAYMENT_TOO_LONG` `AWAITING_DECISION_TOO_LONG` `TERMINAL_TIMEOUT`
`phase`	string	Фаза операции на момент detection. null для terminal timeout. Допустимые значения: `PROCESSING` `AWAITING_CLIENT_PAYMENTS` `AWAITING_CLIENT_DECISION` `FINALIZED`
`actionType`обязательно	string	Configured action для этого timeout-policy слота Допустимые значения: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`
`result`	string	Результат обработки. null — action ещё не применён. Допустимые значения: `NOTIFIED` `FINALIZED` `COMPENSATION_STARTED` `SKIPPED_ALREADY_HANDLED` `SKIPPED_NO_LONGER_APPLIES` `FAILED_TO_HANDLE`
`detectedAt`обязательно	string (дата и время, ISO 8601)	Когда событие было обнаружено
`handledAt`	string (дата и время, ISO 8601)	Когда action был применён. null — ещё не обработано.
`thresholdSeconds`	integer (int64)	Threshold, который вызвал событие
`deadlineAt`	string (дата и время, ISO 8601)	Дедлайн операции на момент detection

payments массив (объект OperationPaymentResponse)

paymentIdобязательно string

clientTransactionIdобязательно string

statusобязательно string

amountобязательно

объект MoneyAmountResponse

Money amount representation

`currency`обязательно	string
`value`обязательно	string

methodобязательно string

interaction

объект PaymentInteractionResponse

Payment interaction artifact (payer-facing link)

`type`обязательно	string
`url`обязательно	string
`expiresAt`	string (дата и время, ISO 8601)

paymentsRevision integer (int64)

Ошибки

Коды ошибок в контракте не описаны.

Submit a decision on an operationPOST/api/v1/operations/{operationId}/decisions

submitOperationDecisionНужен токен

Submits the client's decision for an operation of type EXTERNAL_DECISION that is waiting for it (requiredAction = SUBMIT_DECISION): FINALIZE_AS_IS, ADJUST or COMPENSATE_AND_FINALIZE. decisionVersion must equal expectedDecisionVersion from the required-action payload; a repeated submission with the same version and content is idempotent. Responds with 202: the decision is accepted and executed asynchronously — follow the operation state or webhooks for the outcome. An operation that is not waiting for a decision rejects the request with OPERATION_NOT_WAITING_FOR_DECISION.

Параметры пути

Поле	Тип	Описание
`operationId`обязательно	string

Тело запросаобязательно`SubmitDecisionRequest`

Поле Тип Описание

decisionVersionобязательно integer (int32)

decisionобязательно Один из вариантов

Один из вариантов — Вариант выбирается значением поля kind

AdjustDecisionRequestkind: adjust

Денежная корректировка решения (ADR-0111)

kindобязательно

string

значение adjust

note string

moneyобязательно массив (Один из вариантов)

Один из вариантов — Вариант выбирается значением поля kind

MoneyDecisionPaymentIntentRequestkind: payment

Payment intent (ADR-0111 ADJUST)

kindобязательно

string

значение payment

amountобязательно

объект MoneyAmountRequest

Money amount representation

`currency`обязательно	string
`value`обязательно	string

methodобязательно Один из вариантов

Один из вариантов — Вариант выбирается значением поля kind

B2bSbpPaymentMethodRequestkind: sbp_b2b

B2B SBP payment method (ADR-0125)

`kind`обязательно	string	значение sbp_b2b
`paymentPurpose`обязательно	string	не длиннее 140
`sourceName`обязательно	string	не длиннее 50
`takeTax`обязательно	boolean
`totalTaxAmount`	integer (int64)	Сумма налога в копейках; обязательна при takeTax=true.

MirCardPaymentMethodRequestkind: mir_card

MIR card payment method

`kind`обязательно	string	значение mir_card
`token`обязательно	string

SbpPaymentMethodRequestkind: sbp_c2b

C2B SBP payment method

`kind`обязательно	string	значение sbp_c2b
`payerPhone`обязательно	string

clientTransactionId

string

Client-facing идентификатор нового платежа (ADR-0110). Optional: если не передан, SettleOps заполняет его сам при построении плана.

businessRef

объект BusinessRefRequest

Опциональный business/audit label (ADR-0110). Non-authoritative, не ключ адресации.

`kind`обязательно	string
`id`обязательно	string

metadata словарь (string)

MoneyDecisionPayoutIntentRequestkind: payout

Payout intent (ADR-0114 ADJUST)

kindобязательно

string

значение payout

amountобязательно

объект MoneyAmountRequest

Money amount representation

`currency`обязательно	string
`value`обязательно	string

destinationобязательно Один из вариантов

Один из вариантов — Вариант выбирается значением поля kind

SbpPayoutDestinationRequestkind: sbp

SBP payout destination

`kind`обязательно	string	значение sbp
`recipientPhone`обязательно	string
`recipientBankId`обязательно	string	Идентификатор банка получателя в справочнике СБП, ровно 12 цифр

clientTransactionId

string

Client-facing идентификатор новой выплаты (ADR-0110). Optional: если не передан, SettleOps заполняет его сам при построении плана.

businessRef

объект BusinessRefRequest

Опциональный business/audit label (ADR-0110). Non-authoritative, не ключ адресации.

`kind`обязательно	string
`id`обязательно	string

metadata словарь (string)

MoneyRefundIntentRequestkind: refund

Refund intent (ADR-0111 ADJUST)

kindобязательно

string

значение refund

amountобязательно

объект MoneyAmountRequest

Money amount representation

`currency`обязательно	string
`value`обязательно	string

sourceClientTransactionId string

clientTransactionId string

metadata словарь (string)

CompensateAndFinalizeDecisionRequestkind: compensate_and_finalize

Компенсировать исполненные денежные действия и финализировать операцию (ADR-0111)

`kind`обязательно	string	значение compensate_and_finalize
`note`	string

FinalizeAsIsDecisionRequestkind: finalize_as_is

Закрыть операцию в текущем финансовом состоянии (ADR-0111)

`kind`обязательно	string	значение finalize_as_is
`note`	string

context словарь (string)

Ответы

`202`Accepted`SubmitDecisionResponse`

Поле Тип Описание

operationIdобязательно string

statusобязательно

string

Допустимые значения: CREATED IN_PROGRESS COMPLETED PARTIALLY_COMPLETED FAILED CANCELLED

phaseобязательно

string

Client-facing operational phase (ADR-0052). Distinct from status (lifecycle) and from internal log phase (logging-only).

Допустимые значения: PROCESSING AWAITING_CLIENT_PAYMENTS AWAITING_CLIENT_DECISION FINALIZED

decisionобязательно

объект DecisionStatusResponse

Decision status in response

`status`обязательно	string
`decisionVersion`обязательно	integer (int32)
`receivedAt`	string (дата и время, ISO 8601)

linksобязательно массив (объект LinkResponse)

`rel`обязательно	string
`href`обязательно	string
`type`	string
`method`	string

Ошибки

Коды ошибок в контракте не описаны.

Операции

List active operationsGET/api/v1/operations

Параметры запроса

Ответы

200OKListActiveOperationsResponse

Ошибки

Create an operationPOST/api/v1/operations

Тело запросаобязательноCreateOperationRequest

Ответы

201CreatedCreateOperationResponse

Ошибки

Get an operationGET/api/v1/operations/{operationId}

Параметры пути

Ответы

200OKOperationViewResponse

Ошибки

Submit a decision on an operationPOST/api/v1/operations/{operationId}/decisions

Параметры пути

Тело запросаобязательноSubmitDecisionRequest

Ответы

202AcceptedSubmitDecisionResponse

Ошибки

`200`OK`ListActiveOperationsResponse`

Тело запросаобязательно`CreateOperationRequest`

`201`Created`CreateOperationResponse`

`200`OK`OperationViewResponse`

Тело запросаобязательно`SubmitDecisionRequest`

`202`Accepted`SubmitDecisionResponse`