Configure the tenant's Pix receiver

Sets the Pix key of the tenant and the address of the receiver, the Pix receiver of the tenant’s hybrid boletos (type: HYBRID on POST /v1/boletos), which carry a Pix QR code. The whole configuration is replaced: both members are required and there is no partial update.

• The key must be a key of the tenant’s collection account, in one of the Pix key formats. A key outside them, a CPF or CNPJ key with invalid check digits, a state outside the list or a zip code that is not 8 digits is refused with 400 PBP-0001, naming the member.
• A CPF or CNPJ key must be the document of the holder of the collection account, who is the Pix receiver: another document is refused with 422 PBP-0120, naming pixKey, and nothing is written. When the holder’s document cannot be read, the key is written and the check is left to the issuance of a boleto that carries a Pix QR code.
• A random, e-mail or phone key is not looked up in the Pix directory and its ownership is not verified: confirm that it is a key of the tenant’s collection account before configuring it.
• The address is stored encrypted. It is returned by GET /v1/admin/pix-config and not by this operation.
• A tenant with no provider credential is refused with 422 PBP-0017: connect the provider first with POST /v1/admin/providers/connect.
• The write records who made it and when (updatedBy, updatedAt).
• A write that changes the key, the tenant’s first key included, records the change in the Pix key history, read with GET /v1/admin/pix-config/history, and announces it with the PIX_KEY_CHANGED notice to the webhook configurations that enable it. A write that keeps the key and changes only the address records and announces nothing.

POST /v1/admin/pix-config

Configure the tenant's Pix receiver

cURL

curl --request POST \
  --url https://api.example.com/v1/admin/pix-config \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "pixKey": "f34f8ec2-a4b7-41b4-8200-b53a07e00bac",
  "receiverAddress": {
    "city": "SAO PAULO",
    "state": "SP",
    "street": "Avenida Paulista 1000",
    "zipCode": "01310100"
  }
}
'

200

{
  "complete": true,
  "pixKey": "f34f8ec2-a4b7-41b4-8200-b53a07e00bac",
  "updatedAt": "2026-10-13T15:04:05Z",
  "updatedBy": "<string>"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Organization-Id · string

Tenant organization ID. Optional. The organization context is determined by the credentials you authenticate with; this header does not select or change it.

Idempotency-Key · string · required

Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012.

Body

application/json

pixKey · string · required

Pix key of the tenant's collection account, the receiver of the Pix payment of the tenant's boletos that carry a Pix QR code. Accepted formats: random key (lowercase UUID), CPF (11 digits), CNPJ (14 digits), e-mail (lowercase, at most 77 characters) and phone (+, country code and number). A CPF or CNPJ key with invalid check digits is refused with 400 PBP-0001, and so is a CNPJ key in the alphanumeric format. A CPF or CNPJ key must be the document of the holder of the collection account, who is the Pix receiver: another document is refused with 422 PBP-0120, and nothing is written. When the holder's document cannot be read, the key is written and the check is left to the issuance of a boleto that carries a Pix QR code. A random, e-mail or phone key is not verified.

Maximum string length: 77

Pattern: ^([0-9]{11}|[0-9]{14}|[+][1-9][0-9][0-9]{1,14}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[a-z0-9.!#$&'*+/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:[.][a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*)$

Example:

"f34f8ec2-a4b7-41b4-8200-b53a07e00bac"

receiverAddress · object · required

Address of the holder of the account the key belongs to, the receiver of the Pix payment. A boleto that carries a Pix QR code requires it, and the account record does not provide it.

Show child attributes

Response

200

application/json

OK

complete · boolean · required

Whether the configuration has every member a boleto that carries a Pix QR code needs from it; always true after a write, which requires them all. As on the read, it does not guarantee that an issuance is accepted.

pixKey · string · required

The configured Pix key.

Example:

"f34f8ec2-a4b7-41b4-8200-b53a07e00bac"

updatedAt · string<date-time> · required

When this write was recorded, in UTC.

Example:

"2026-10-13T15:04:05Z"

updatedBy · string · required

Identifier of the authenticated principal that made this write: the subject of its access token.