Wallet Adapter

Debit reversal

Reverse a prior debit when compensation is required.

Debit reversal

Reverse prior debit when compensation is required.

Path

POST /debit-reversal

When used

wallet was debited
OpenPoly business flow failed after debit
user funds must be returned

Request body

{
  "external_user_id": "operator-user-123",
  "amount_minor": 10000,
  "currency_code": "IDR",
  "idempotency_key": "mini_app_order:1:debit_reversal",
  "reason": "mini_app_buy_compensation",
  "metadata": {
    "orderId": 1,
    "marketId": 51,
    "resolveDeadlineTs": "2026-06-30T12:00:00.000Z",
    "balanceOperationId": 10
  }
}

There is no direction field in the REST v1 JSON body. The path POST /debit-reversal is the direction.

idempotency_key identifies the reversal operation, not the original debit.

Request field	Type	Requirement	Notes
`external_user_id`	string	Required	Same wallet user as the original debit.
`amount_minor`	integer	Required	Amount to return in minor units.
`currency_code`	string	Required	Current REST v1 value: `IDR`.
`idempotency_key`	string	Required	New key for the reversal operation.
`reason`	string	Required	Buy compensation uses `mini_app_buy_compensation`.
`metadata`	object	Required	Always present, possibly empty; fields are additive.

Buy-compensation metadata:

Metadata field	Type	Requirement
`orderId`	positive integer	Required
`marketId`	positive integer	Required
`balanceOperationId`	positive integer	Optional additive evidence
`resolveDeadlineTs`	ISO-8601 string or `null`	Optional additive context

Current reversal requests include the related market's resolution deadline when configured, otherwise null.

Response body

Same response shape as debit:

{
  "external_user_id": "operator-user-123",
  "status": "succeeded",
  "currency_code": "IDR",
  "amount_minor": 10000,
  "idempotency_key": "mini_app_order:1:debit_reversal",
  "remote_reference": "wallet-op-789",
  "balance_minor": 100000
}

Status values

Response field requirements:

Response field	Type	Requirement	OpenPoly behavior
`status`	string	Required	Must be `succeeded`, `failed`, or `pending`.
`external_user_id`	string	Optional	Falls back to the request value. Full-contract tests reject a mismatch.
`idempotency_key`	string	Optional	Falls back to the request key.
`remote_reference`	string	Optional	Preserved when non-empty.
`balance_minor`	integer	Optional	Post-operation balance, preserved for reconciliation.
`failure_reason`	string	Optional	Recommended when `status = failed`.
`amount_minor`, `currency_code`	mixed	Optional echoes	Not consumed from the response; OpenPoly keeps the request values.

succeeded
failed
pending

Rules

reversal must be idempotent
remote reference for reversal should be distinct from original debit
response should echo external_user_id when available
if the remote state is unclear, return pending; OpenPoly preserves it for reconciliation
compensation may be retried only with the original idempotency key

Edit this pageorReport an issue

Credit

Credit contract for sell and redemption payouts.

Idempotency

Idempotency key formats and replay expectations for wallet operations.