BlooBank API Documentation

Creates a payment order in the given wallet. The direction field determines the workflow:

Direction	Workflow	Initial status
`IN`	One-step. Submitted to the provider immediately.	`PENDING`
`OUT`	Two-step. Requires explicit `approve` before submission.	`AWAITING_APPROVAL`

See Payments overview for the end-to-end flow and Payment lifecycle for the full state machine.

The `idempotencyKey` field

Always supply idempotencyKey for payment-order creates. It makes the request safe to retry on network failures — the (wallet, idempotencyKey) tuple is globally unique. Without it, every retry creates a duplicate payment.

Scenario	Result
First request with this `(wallet, idempotencyKey)`	New order created. `201 Created`.
Retry with identical body	The original order is returned. `201 Created`.
Retry with divergent body	`IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS` (HTTP 422).

See Idempotency for the persistence pattern.

The `instrument` field

instrument is a discriminated union by type — five PIX variants today. The five variants and when to use each are documented in Instrument types.

`type`	Direction
`PIX_CASH_IN_EMV_STATIC`	`IN`
`PIX_CASH_IN_EMV_DYNAMIC`	`IN`
`PIX_CASH_OUT_KEY`	`OUT`
`PIX_CASH_OUT_EMV`	`OUT`
`PIX_CASH_OUT_ACCOUNT`	`OUT`

Introduction

Conventions

Wallets

Payment Orders

Create payment order

The `idempotencyKey` field

The `instrument` field

​The idempotencyKey field

​The instrument field

The `idempotencyKey` field

The `instrument` field