API Internet BankingPix

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.

X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

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