Credit
Credit
Credit user wallet for sell or redemption payout.
Path
POST /credit
Request body
{
"external_user_id": "operator-user-123",
"amount_minor": 15000,
"currency_code": "IDR",
"idempotency_key": "mini_app_redemption_item:77:credit",
"reason": "mini_app_redemption",
"metadata": {
"redemptionItemId": 77,
"marketId": 51,
"resolveDeadlineTs": "2026-06-30T12:00:00.000Z"
}
}
Sell payouts use the same shape with reason = "mini_app_sell_order" and metadata such as orderId, marketId, outcome, and resolveDeadlineTs.
There is no direction field in the REST v1 JSON body. The path POST /credit is the direction.
external_user_id is required here just like debit. OpenPoly gets it from the stored operator user linked to the Mini App session or redemption item.
| Request field | Type | Requirement | Notes |
|---|---|---|---|
external_user_id | string | Required | Stable operator-side user ID. |
amount_minor | integer | Required | Exact payout amount in minor units. |
currency_code | string | Required | Current REST v1 value: IDR. |
idempotency_key | string | Required | Credit operation key. |
reason | string | Required | mini_app_sell_order or mini_app_redemption. |
metadata | object | Required | Always present, possibly empty; fields are additive. |
Required credit metadata varies by flow:
| Flow | Reason | Required metadata | Optional additive metadata |
|---|---|---|---|
| Sell | mini_app_sell_order | orderId, marketId | outcome, resolveDeadlineTs |
| Redemption | mini_app_redemption | redemptionItemId, marketId | resolveDeadlineTs |
resolveDeadlineTs is an optional ISO-8601 string-or-null field. Current sell and redemption requests include the related market's resolution deadline when configured, otherwise null. Redemption credit does not include orderId. Do not reject unknown additive metadata fields.
Response body
Same response shape as debit:
{
"external_user_id": "operator-user-123",
"status": "succeeded",
"currency_code": "IDR",
"amount_minor": 15000,
"idempotency_key": "mini_app_redemption_item:77:credit",
"remote_reference": "wallet-op-456",
"balance_minor": 115000
}
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. |
succeededfailedpending
Rules
- payout amount already includes OpenPoly rounding rules
- credit must be idempotent by
idempotency_key - response should echo
external_user_idwhen available - direct mutation responses must not return
unknown;pendingand ambiguous transport/HTTP outcomes require manual review - do not blindly re-credit with a new idempotency key after timeout or manual review