VA · Payin (fiat inbound)

Parent: Overview · Updated: 2026-08-27

Flow

Steps

Create or query a Sub VA (sub/create / sub/get / sub/list)

Watch VIRTUAL_ACCOUNT_UPDATED for account availability changes

Show the collection details to the payer and wait for the bank credit

Receive VIRTUAL_ACCOUNT_ORDER_UPDATED; you may receive VIRTUAL_ACCOUNT_UPDATED again

If SUB_VIRTUAL_ACCOUNT_RFI_REQUIRED arrives asynchronously, follow RFI — remediation is decoupled from the main payin flow

Reconcile the final state and balance with order/detail / primary/get-balance

Refund (payin refund)

Once a payin order orderStatus is SUCCESS, the merchant can request a refund. BPN creates a separate RE* child (businessType=PAYIN_REFUND). The original VA* order stays SUCCESS.

RE `orderStatus`	`refundStatus`	Meaning
`PROCESSING`	`REFUNDING`	Refund created; channel not terminal
`REFUNDED`	`REFUNDED`	Funds confirmed and ledger posted
`FAIL`	`REFUND_FAILED`	Channel explicitly failed

The original payin, while a refund is in flight:

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

Webhook terminal refund notification is on the RE* child, not on the original order as REFUNDED. Timeout or missing callback must not be treated as success — poll GET /v1/virtual-account/order/detail with the RE* orderId.

Endpoint: POST /v1/virtual-account/order/refund. State machine: statuses.md.

Reconciliation keys

Key	Use
VA `orderId` (`VA*`)	Original payin
RE `orderId` (`RE*`)	Refund child
`refundOrderId` / `originalOrderId`	1:1 link
Webhook `eventId`	Callback idempotency
Webhook `referenceId`	Linked business object

Order statuses: statuses.md.

VA · Payin

VA · Payin (fiat inbound)#

Flow#

Steps#

Refund (payin refund)#

Reconciliation keys#

Related statuses#

VA · Payin (fiat inbound)

Flow

Steps

Refund (payin refund)

Reconciliation keys

Related statuses