> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create payment order

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](/get-started/payments/overview) for the end-to-end flow and [Payment lifecycle](/get-started/payments/lifecycle) for the full state machine.

## The `idempotencyKey` field

<Warning>
  **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.
</Warning>

| 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](/get-started/concepts/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](/get-started/payments/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`     |