Initiate a Pix Transfer

curl --request POST \ --url https://plugin-pix-indirect.api.lerian.net/v1/transfers/cashout/initiate \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Account-Id: <x-account-id>' \ --data ' { "initiationType": "KEY", "key": "john.doe@example.com" } '

{ "id": "019c96a0-0c82-7c3d-8dcc-c180868b45c4", "initiationType": "KEY", "emv": "00020126...5802BR5913Fulano...", "endToEndId": "E1234567820240101000001234567890", "qrCodeDetails": {}, "destination": { "key": "john.doe@example.com", "account": { "branch": "0001", "number": "123456789", "participant": "12345678", "type": "CACC" }, "owner": { "document": "12345678901", "name": "John Doe", "tradeName": "John's Business", "type": "NATURAL_PERSON" } }, "expiresAt": "2024-01-15T11:00:00Z", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" }

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Account-Id

string

required

Unique identifier of the Midaz Ledger Account (UUID format).

X-Idempotency

string

Optional idempotency key for safe retries. Reuse the same value only when retrying the same operation after an unknown outcome.

See Retries and idempotency for details.

X-TTL

integer

Time-to-live in seconds for the idempotency key cache. Defines how long the system remembers a processed request.

See Retries and idempotency for details.

Body

application/json

initiationType

enum<string>

required

Type of transfer initiation. Determines which additional field is required: MANUAL requires destination, KEY requires key, and QR_CODE requires emv.

Available options:

MANUAL,

KEY,

QR_CODE

Example:

"MANUAL"

destination

object

Destination account information (required for MANUAL).

Show child attributes

key

string

Pix key value (required for KEY type). Can be a CPF, CNPJ, email, phone, or EVP.

Example:

"john.doe@example.com"

emv

string

QR code EMV payload (required for QR_CODE type).

Example:

"00020126...5802BR5913Fulano..."

endToEndId

string

Optional custom end-to-end ID (32-character alphanumeric string, auto-generated if not provided).

Example:

"E1234567820240101000001234567890"

Response

Pix cash-out initiation created successfully.

The response includes the X-Idempotency-Replayed header.

If the value is false, the transaction was just processed. If the value is true, the response is a replay of a previously processed request.

See Retries and idempotency for more details.

string

Unique identifier for this initiation (used as initiationId in process).

Example:

"019c96a0-0c82-7c3d-8dcc-c180868b45c4"

initiationType

enum<string>

Type of initiation.

Available options:

MANUAL,

KEY,

QR_CODE

Example:

"KEY"

emv

string

EMV payload from the QR code (only for QR_CODE type).

Example:

"00020126...5802BR5913Fulano..."

endToEndId

string

End-to-end identifier for this transfer.

Example:

"E1234567820240101000001234567890"

qrCodeDetails

object

Decoded QR code details (only for QR_CODE type). The shape varies by QR type (static, immediate, or due-date collection).

destination

object

Account party (source or destination) information.

Show child attributes

expiresAt

string<date-time>

Date-time when the initiation expires and can no longer be processed.

Example:

"2024-01-15T11:00:00Z"

createdAt

string<date-time>

Example:

"2024-01-15T10:30:00Z"

updatedAt

string<date-time>

Example:

"2024-01-15T10:30:00Z"