API BaaSPix

Register a new Pix key

Registers a new PIX key on the account. Key ownership for e-mail and phone keys is validated by the settlement bank; the response reflects the registration status.

Authentication

AuthorizationBearer

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

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringRequired>=8 characters

Client-generated idempotency token.

Request

This endpoint expects an object.
keyTypeenumRequired

Type of PIX key to be registered:

  • cpf - Account holder’s CPF
  • cnpj - Account holder’s CNPJ
  • phone - Phone with area code (+5511999999999). Starts OTP; confirm with /pix/keys/verify.
  • email - Email address. Starts OTP; confirm with /pix/keys/verify.
  • random - Random key (EVP) - system generates automatically

email and phone return 202 pending_verification. The facade sends the OTP (SES / Twilio). The key is created on the partner only after a correct code.

pixKeystringOptional

Value of the PIX key to be registered. Required for all types except random. For random, omit this field and the system will generate a UUID.

Response

Pix key registered (cpf, cnpj, random).

keyTypestring
keyTypeIdinteger
pixKeystring
createddatetime

Errors

400
Bad Request Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error