Create PIX key

POST

/order/v1/banking/accounts/{accountId}/keys

• Production
• Sandbox

Create a PIX key for the given account. For EMAIL and PHONE keys, this starts a confirmation flow instead of creating the key right away: the response comes back as PENDING and a confirmation code is sent to the informed target. Call POST :accountId/keys/confirm with the returned validationId and the code to finish creating the key. CPF, CNPJ and RANDOM keys are created immediately, without OTP.

Authorizations

• Bearer

Parameters

Path Parameters

accountId

required

string format: uuid

Identifier of the account

Header Parameters

idempotency-key

required

string format: uuid

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body ^required

object

type

required

Type of PIX key to be created. RANDOM creates a random (EVP) key; EVP is accepted as an alias of RANDOM and the created key is returned with type EVP. EMAIL and PHONE start a confirmation flow instead of creating the key right away (see POST …/keys/confirm).

string

Allowed values: CPF CNPJ EMAIL PHONE RANDOM EVP

Example

CPF

key

required

PIX key value (required unless type is RANDOM)

string

Example

122345678900

channel

OTP delivery channel. Only accepted when type is PHONE — SMS is the default when omitted. Ignored/rejected for other types.

string

Allowed values: sms whatsapp

Example

sms

Responses

200

The resource was returned successfully

object

id

required

Identifier of the PIX key

string

Example

a8f2b9c4-1e6a-4c3f-9d7b-2a1e8f9c5d10

type

required

Type of the PIX key

string

Allowed values: CPF CNPJ EMAIL PHONE RANDOM

Example

CPF

key

required

PIX key value

string

Example

122345678900

createdAt

required

Creation date of the PIX key

string

Example

2025-12-18T10:15:30Z

possedAt

required

Date when the key was associated to the account

string

Example

2025-12-18T10:15:30Z

201

Validation started for EMAIL/PHONE keys; call the confirm endpoint next.

object

validationId

required

Identifier of the validation. Must be sent back on the confirm endpoint.

string

Example

a8f2b9c4-1e6a-4c3f-9d7b-2a1e8f9c5d10

status

required

Status of the validation

string

Example

PENDING

expiresAt

required

Expiration date of the confirmation code

string

Example

2025-12-18T10:15:30Z

400

object

error

string

Example

INVALID_REQUEST

message

string

details

Array<object>

object

field

string

issue

string

description

string

Example

[
  {
    "field": "field_name",
    "issue": "INVALID",
    "description": "Field is invalid"
  }
]

401

Unauthorized Request

object

error

string

Example

UNAUTHORIZED

message

string

Example

Unauthorized Request

details

Array<object>

object

field

string

issue

string

description

string

Example

[]

500

object

error

string

Example

INTERNAL_ERROR

message

string

details

Array<object>

object

field

string

issue

string

description

string

Example

[]