Operation IDs and Movements

Two kinds of ID

Every operation on a virtual account can be identified in two different ways. They are not interchangeable, so it is worth knowing which one you are storing or showing to your team.

ID	What it identifies	Format	Example
Operation ID	A payin, payout or refund. It is returned when you create the operation and you use it to retrieve the operation and match its callbacks.	UUID	`3f2c9a1e-7b4d-4e8a-9c21-5d6f0e8b7a14`
Movement ID	One entry on an account's statement: a credit or a debit that changed the balance. It is the `id` returned by List Account Movements and by the movement webhook.	Integer	`7643753`

Each type of operation writes its movement at a different point in its lifecycle. The table in the next section shows when.

Each movement points back to the operation that produced it through its operation object:

{
  "id": "7643810",
  "amount": -5000.0,
  "operation": {
    "type": "PAYOUT",
    "operation_id": "3f2c9a1e-7b4d-4e8a-9c21-5d6f0e8b7a14",
    "product": "PAYOUTS"
  }
}

IDs by operation

Operation	ID you get	Movement	`operation.type`	`operation.operation_id`
Deposit	None. The deposit is the movement itself, so its movement ID is the only Infinia ID.	One credit, written when the deposit is credited.	`CREDIT`	Empty
Payin	Payin `id`	One credit, written only when the payin reaches `COMPLETED`.	`PAYIN`	Payin `id`
Payout	Payout `id`, plus the `originId` you sent	One debit, written only when the payout reaches `COMPLETED`. If the payout is later returned, a second movement credits the funds back.	`PAYOUT`, then `PAYOUT_REFUND` if returned	Payout `id`
Deposit refund	Refund `id`, plus the `idempotency_key` you sent	One debit, written when the refund is created. If the refund fails, a second movement credits the funds back.	`CREDIT_REFUND`, then `CREDIT_REFUND_BOUNCE` if it fails	Refund `id`
Payin refund	Refund `id`, plus the `idempotency_key` you sent	One debit, written when the refund is created. If the refund fails, a second movement credits the funds back.	`PAYIN_REFUND`, then `PAYIN_REFUND_BOUNCE` if it fails	Refund `id`

📘
Fees and taxes charged on an operation are separate movements with their own movement IDs. They do not replace the movement of the operation itself.

Finding the movement of an operation

Deposits. The movement ID is the deposit's ID. You receive it in the movement webhook as soon as the deposit is credited.

Payins and payouts. The payin and payout responses and callbacks do not include a movement ID. Once the operation is COMPLETED, look the movement up by the operation ID:

curl -u "$API_KEY_USER:$API_KEY_PASSWORD" \
  "https://app2test.infiniaweb.com/infinia_api/v1/accounts/movements/?operation_id=3f2c9a1e-7b4d-4e8a-9c21-5d6f0e8b7a14"

You also receive the movement in the movement webhook, where operation.operation_id holds the payin or payout ID.

Refunds. The refund response and callback include the movement IDs directly:

Field	Meaning
`movement_id`	Deposit refunds only. The deposit that was refunded.
`payment_id`	Payin refunds only. The payin that was refunded. This is a payin ID, not a movement ID.
`debit_movement_id`	The debit that took the refunded amount out of the account.
`bounce_movement_id`	The credit that returned the funds after the refund failed. Empty unless the refund failed.

Which ID to show your team

Use the movement ID when you need one reference per line of the account statement, for example to reconcile balances. Every credit and debit has one, whatever the operation.

Use the operation ID when you need to follow an operation through its lifecycle, for example a payout that is still IN_PROGRESS. It exists from the moment the operation is created.

When a single "transaction ID" column has to cover several operation types, keep in mind that deposits only have a movement ID, while payins, payouts and refunds have an operation ID and, once their movement is written, a movement ID. Storing both, and the operation.type, avoids mixing the two kinds of ID.

📘
The rail reference of a transfer, such as the Pix end-to-end ID, is neither of these. It is returned as voucherId on payins and payouts, as voucher_id on refunds, and as third_party.voucher_id on movements. You can filter movements by it with the voucher_id parameter.