2026-09-21 Virtual Account independent refund orders

Overview

Effective after 2026-09-21. Merchants should not treat this contract as live before that date.

This release documents independent refund child orders for Pay-in and Payout. The original VA* order stays SUCCESS. Refund lifecycle lives on an RE* child.

Affected resources:

Get VA Order Detail — GET /v1/virtual-account/order/detail

List VA Orders — GET /v1/virtual-account/order/list

Refund VA Order — POST /v1/virtual-account/order/refund

Virtual Account Payment Status webhook

Get Reconciliation Order List By Page

Guides:

VA · Statuses

VA · Payin

VA · Payout

Virtual Account Overview

Field contract

JSON is camelCase. Amounts are decimal strings. currency is a separate ISO 4217 field. Keep the existing BPN OpenAPI envelope (status / message / data / traceId).

Field	Original `VA*`	Refund child `RE*`
`orderId`	`VA*`	`RE*`
`businessType`	`PAY_IN` / `CASH_OUT`	`PAYIN_REFUND` / `PAYOUT_REFUND`
`orderStatus`	stays `SUCCESS` after success	`PROCESSING` / `REFUNDED` / `FAIL`
`refundStatus`	copied from the child, or `null`	`REFUNDING` / `REFUNDED` / `REFUND_FAILED`
`originalOrderId`	`null`	original `VA*`
`refundOrderId`	`RE*` child or `null`	`null`

businessType / orderStatus in older examples are deprecated aliases. Prefer businessType / orderStatus / refundStatus. All three use uppercase enum values.

Refund child states

Stage	`orderStatus`	`refundStatus`
Created / channel not terminal	`PROCESSING`	`REFUNDING`
Funds confirmed and ledger posted	`REFUNDED`	`REFUNDED`
Channel explicitly failed	`FAIL`	`REFUND_FAILED`

Webhook

Stop treating original-order orderStatus=REFUNDED as the refund terminal event. Subscribe to VIRTUAL_ACCOUNT_ORDER_UPDATED on the RE* child. Timeout or missing callback must not be inferred as success.

Example · `RE*` processing

{
  "eventId": "evt_PAYIN_REFUND_10001",
  "eventType": "VIRTUAL_ACCOUNT_ORDER_UPDATED",
  "referenceId": "RE20260826170000000001",
  "status": "PROCESSING",
  "timestamp": 1787304000000,
  "data": {
    "orderId": "RE20260826170000000001",
    "businessType": "PAYIN_REFUND",
    "refundStatus": "REFUNDING",
    "originalOrderId": "VA20260826160000000001",
    "refundOrderId": null,
    "amount": "100.00",
    "currency": "BRL",
    "orderStatus": "PROCESSING"
  }
}

Example · original VA while refund is in flight

{
  "orderId": "VA20260826160000000001",
  "businessType": "PAY_IN",
  "refundStatus": "REFUNDING",
  "originalOrderId": null,
  "refundOrderId": "RE20260826170000000001",
  "amount": "100.00",
  "currency": "BRL",
  "orderStatus": "SUCCESS"
}

List filter

GET /v1/virtual-account/order/list?refundStatus=REFUNDING returns refund child orders only, not original VA* rows.

Dynamic Virtual Account statuses (unchanged)

Status	Meaning
`EXPIRED`	The current VA has expired.
`REJECTED`	The VA payment was rejected and funds were returned to the original payer.

See VA · Statuses · Account VirtualAccountStatus.

2026-09-21 Virtual Account independent refund orders

Overview#

Field contract#

Refund child states#

Webhook#

Example · RE* processing#

Example · original VA while refund is in flight#

List filter#

Dynamic Virtual Account statuses (unchanged)#