Operations

An operation is a unit of work with the client's money: create it, read its state, list the active ones and submit a decision on it.

List active operationsGET/api/v1/operations

listActiveOperationsToken required

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.

Query parameters

Field	Type	Description
`cursor`	string
`limit`	integer (int32)	default 20

Responses

`200`OK`ListActiveOperationsResponse`

Field Type Description

itemsrequired array (object ActiveOperationSummaryResponse)

operationIdrequired string

clientOperationIdrequired string

statusrequired

string

Allowed values: CREATED IN_PROGRESS COMPLETED PARTIALLY_COMPLETED FAILED CANCELLED

phaserequired

string

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

Allowed values: PROCESSING AWAITING_CLIENT_PAYMENTS AWAITING_CLIENT_DECISION FINALIZED

requiredActionrequired

string

Allowed values: NONE PERFORM_PAYMENTS SUBMIT_DECISION

requiredActionSince string (date and time, ISO 8601)

requiredActionPayload

object OperationRequiredActionPayloadResponse

Payload for required action

expectedDecisionVersion integer (int32)

allowedDecisionKinds

array (string)

Allowed values: finalize_as_is adjust compensate_and_finalize

paymentsrequired array (object OperationRequiredActionPaymentResponse)

paymentIdrequired string

methodrequired map (string)

amountrequired

object MoneyAmountResponse

Money amount representation

`currency`required	string
`value`required	string

linksrequired map (string)

clientTransactionId string

status string

interaction

object PaymentInteractionResponse

Payment interaction artifact (payer-facing link)

`type`required	string
`url`required	string
`expiresAt`	string (date and time, ISO 8601)

createdAtrequired string (date and time, ISO 8601)

updatedAtrequired string (date and time, ISO 8601)

deadlineAt string (date and time, ISO 8601)

activeTimeoutEvents array (object ActiveTimeoutEventResponse)

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

nextCursor string

Errors

Error codes are not described in the contract.

Create an operationPOST/api/v1/operations

createOperationToken required

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.

Request bodyrequired`CreateOperationRequest`

Field Type Description

settlementAccountIdrequired

string

Settlement account ID that owns the operation

example: 100500

typerequired

string

Allowed values: EXTERNAL_DECISION STANDARD

controls object CreateOperationControlsRequest

timeoutPolicy object CreateTimeoutPolicyRequest

thresholds object CreateTimeoutPolicyThresholdsRequest

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

actions object CreateTimeoutPolicyActionsRequest

onProcessingStuck object TimeoutPolicyActionRequest

`type`required	string	Allowed values: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`

onAwaitingDecisionTooLong object TimeoutPolicyActionRequest

`type`required	string	Allowed values: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`

onAwaitingPaymentTooLong object TimeoutPolicyActionRequest

`type`required	string	Allowed values: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`

onTerminalTimeout object TimeoutPolicyActionRequest

`type`required	string	Allowed values: `NOTIFY` `FINALIZE_AS_IS` `COMPENSATE_AND_FINALIZE`

closurePolicy object CreateClosurePolicyRequest

`onUnrecoverableExecution`	string	Allowed values: `KEEP_OPEN_UNTIL_TIMEOUT` `FINALIZE_AS_IS`

compensationPolicy object CreateCompensationPolicyRequest

`refundMode`	string	Allowed values: `REFUND_ONLY` `ALLOW_PAYOUT`

webhookPolicy object CreateWebhookPolicyRequest

`onCriticalDeliveryExhausted`	string

moneyrequired array (One of)

One of — The variant is selected by the kind field value

MoneyAwaitDecisionIntentRequestkind: await_decision

Await decision intent (business gate, ADR-0100)

`kind`required	string	value await_decision
`description`	string

MoneyPaymentIntentRequestkind: payment

Payment intent

kindrequired

string

value payment

amountrequired

object MoneyAmountRequest

Money amount representation

`currency`required	string
`value`required	string

methodrequired One of

One of — The variant is selected by the kind field value

B2bSbpPaymentMethodRequestkind: sbp_b2b

B2B SBP payment method (ADR-0125)

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

MirCardPaymentMethodRequestkind: mir_card

MIR card payment method

`kind`required	string	value mir_card
`token`required	string

SbpPaymentMethodRequestkind: sbp_c2b

C2B SBP payment method

`kind`required	string	value sbp_c2b
`payerPhone`required	string

capture boolean

metadata map (string)

businessRef

object BusinessRefRequest

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

`kind`required	string
`id`required	string

clientTransactionId

string

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

MoneyPayoutIntentRequestkind: payout

Payout intent (ADR-0114)

kindrequired

string

value payout

amountrequired

object MoneyAmountRequest

Money amount representation

`currency`required	string
`value`required	string

destinationrequired One of

One of — The variant is selected by the kind field value

SbpPayoutDestinationRequestkind: sbp

SBP payout destination

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

metadata map (string)

businessRef

object BusinessRefRequest

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

`kind`required	string
`id`required	string

clientTransactionId

string

contextrequired

object CreateOperationContextRequest

Operation context

idempotencyKeyrequired string

clientOperationIdrequired string

sourcerequired string

businessRef

object BusinessRefRequest

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

`kind`required	string
`id`required	string

Responses

`201`Created`CreateOperationResponse`

Field Type Description

operationIdrequired string

typerequired

string

Allowed values: EXTERNAL_DECISION STANDARD

statusrequired

string

Allowed values: CREATED IN_PROGRESS COMPLETED PARTIALLY_COMPLETED FAILED CANCELLED

phaserequired

string

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

Allowed values: PROCESSING AWAITING_CLIENT_PAYMENTS AWAITING_CLIENT_DECISION FINALIZED

message string

requiredAction

string

Allowed values: NONE PERFORM_PAYMENTS SUBMIT_DECISION

requiredActionSince string (date and time, ISO 8601)

requiredActionPayload

object OperationRequiredActionPayloadResponse

Payload for required action

expectedDecisionVersion integer (int32)

allowedDecisionKinds

array (string)

Allowed values: finalize_as_is adjust compensate_and_finalize

paymentsrequired array (object OperationRequiredActionPaymentResponse)

paymentIdrequired string

methodrequired map (string)

amountrequired

object MoneyAmountResponse

Money amount representation

`currency`required	string
`value`required	string

linksrequired map (string)

clientTransactionId string

status string

interaction

object PaymentInteractionResponse

Payment interaction artifact (payer-facing link)

`type`required	string
`url`required	string
`expiresAt`	string (date and time, ISO 8601)

linksrequired array (object LinkResponse)

`rel`required	string
`href`required	string
`type`	string
`method`	string

Errors

Error codes are not described in the contract.

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

getOperationToken required

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.

Path parameters

Field	Type	Description
`operationId`required	string

Responses

`200`OK`OperationViewResponse`

Field Type Description

operationIdrequired string

statusrequired

string

Allowed values: CREATED IN_PROGRESS COMPLETED PARTIALLY_COMPLETED FAILED CANCELLED

typerequired

string

Allowed values: EXTERNAL_DECISION STANDARD

phaserequired

string

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

Allowed values: PROCESSING AWAITING_CLIENT_PAYMENTS AWAITING_CLIENT_DECISION FINALIZED

createdAt string (date and time, ISO 8601)

finalizedAt string (date and time, ISO 8601)

deadlineAt string (date and time, ISO 8601)

finalizationReason

string

Allowed values: TERMINAL_TIMEOUT EXECUTION_STUCK AWAITING_PAYMENT_TOO_LONG AWAITING_DECISION_TOO_LONG CLIENT_COMPENSATED_AND_FINALIZED WEBHOOK_DELIVERY_EXHAUSTED

finalizationMode

string

Allowed values: FINALIZE_AS_IS COMPENSATE_AND_FINALIZE

requiredAction

string

Allowed values: NONE PERFORM_PAYMENTS SUBMIT_DECISION

requiredActionSince string (date and time, ISO 8601)

requiredActionPayload

object OperationRequiredActionPayloadResponse

Payload for required action

expectedDecisionVersion integer (int32)

allowedDecisionKinds

array (string)

Allowed values: finalize_as_is adjust compensate_and_finalize

paymentsrequired array (object OperationRequiredActionPaymentResponse)

paymentIdrequired string

methodrequired map (string)

amountrequired

object MoneyAmountResponse

Money amount representation

`currency`required	string
`value`required	string

linksrequired map (string)

clientTransactionId string

status string

interaction

object PaymentInteractionResponse

Payment interaction artifact (payer-facing link)

`type`required	string
`url`required	string
`expiresAt`	string (date and time, ISO 8601)

links array (object LinkResponse)

`rel`required	string
`href`required	string
`type`	string
`method`	string

activeTimeoutEvents array (object ActiveTimeoutEventResponse)

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

payments array (object OperationPaymentResponse)

paymentIdrequired string

clientTransactionIdrequired string

statusrequired string

amountrequired

object MoneyAmountResponse

Money amount representation

`currency`required	string
`value`required	string

methodrequired string

interaction

object PaymentInteractionResponse

Payment interaction artifact (payer-facing link)

`type`required	string
`url`required	string
`expiresAt`	string (date and time, ISO 8601)

paymentsRevision integer (int64)

Errors

Error codes are not described in the contract.

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

submitOperationDecisionToken required

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.

Path parameters

Field	Type	Description
`operationId`required	string

Request bodyrequired`SubmitDecisionRequest`

Field Type Description

decisionVersionrequired integer (int32)

decisionrequired One of

One of — The variant is selected by the kind field value

AdjustDecisionRequestkind: adjust

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

kindrequired

string

value adjust

note string

moneyrequired array (One of)

One of — The variant is selected by the kind field value

MoneyDecisionPaymentIntentRequestkind: payment

Payment intent (ADR-0111 ADJUST)

kindrequired

string

value payment

amountrequired

object MoneyAmountRequest

Money amount representation

`currency`required	string
`value`required	string

methodrequired One of

One of — The variant is selected by the kind field value

B2bSbpPaymentMethodRequestkind: sbp_b2b

B2B SBP payment method (ADR-0125)

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

MirCardPaymentMethodRequestkind: mir_card

MIR card payment method

`kind`required	string	value mir_card
`token`required	string

SbpPaymentMethodRequestkind: sbp_c2b

C2B SBP payment method

`kind`required	string	value sbp_c2b
`payerPhone`required	string

clientTransactionId

string

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

businessRef

object BusinessRefRequest

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

`kind`required	string
`id`required	string

metadata map (string)

MoneyDecisionPayoutIntentRequestkind: payout

Payout intent (ADR-0114 ADJUST)

kindrequired

string

value payout

amountrequired

object MoneyAmountRequest

Money amount representation

`currency`required	string
`value`required	string

destinationrequired One of

One of — The variant is selected by the kind field value

SbpPayoutDestinationRequestkind: sbp

SBP payout destination

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

clientTransactionId

string

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

businessRef

object BusinessRefRequest

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

`kind`required	string
`id`required	string

metadata map (string)

MoneyRefundIntentRequestkind: refund

Refund intent (ADR-0111 ADJUST)

kindrequired

string

value refund

amountrequired

object MoneyAmountRequest

Money amount representation

`currency`required	string
`value`required	string

sourceClientTransactionId string

clientTransactionId string

metadata map (string)

CompensateAndFinalizeDecisionRequestkind: compensate_and_finalize

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

`kind`required	string	value compensate_and_finalize
`note`	string

FinalizeAsIsDecisionRequestkind: finalize_as_is

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

`kind`required	string	value finalize_as_is
`note`	string

context map (string)

Responses

`202`Accepted`SubmitDecisionResponse`

Field Type Description

operationIdrequired string

statusrequired

string

Allowed values: CREATED IN_PROGRESS COMPLETED PARTIALLY_COMPLETED FAILED CANCELLED

phaserequired

string

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

Allowed values: PROCESSING AWAITING_CLIENT_PAYMENTS AWAITING_CLIENT_DECISION FINALIZED

decisionrequired

object DecisionStatusResponse

Decision status in response

`status`required	string
`decisionVersion`required	integer (int32)
`receivedAt`	string (date and time, ISO 8601)

linksrequired array (object LinkResponse)

`rel`required	string
`href`required	string
`type`	string
`method`	string

Errors

Error codes are not described in the contract.

Operations

List active operationsGET/api/v1/operations

Query parameters

Responses

200OKListActiveOperationsResponse

Errors

Create an operationPOST/api/v1/operations

Request bodyrequiredCreateOperationRequest

Responses

201CreatedCreateOperationResponse

Errors

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

Path parameters

Responses

200OKOperationViewResponse

Errors

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

Path parameters

Request bodyrequiredSubmitDecisionRequest

Responses

202AcceptedSubmitDecisionResponse

Errors

`200`OK`ListActiveOperationsResponse`

Request bodyrequired`CreateOperationRequest`

`201`Created`CreateOperationResponse`

`200`OK`OperationViewResponse`

Request bodyrequired`SubmitDecisionRequest`

`202`Accepted`SubmitDecisionResponse`