---
title: "Create Dynamic QR Code"
method: POST
path: "/v1/dynamic-qrcode"
tags: ["PIX QR Codes"]
---

# Create Dynamic QR Code

`POST /v1/dynamic-qrcode`

## Allowed Payers (allowed_tax_ids)
When `allowed_tax_ids` is provided, only payers whose CPF/CNPJ matches one of the listed values will be accepted at payment time.
When omitted or null, payments from any document are accepted.

## Request body

- CreateDynamicBrcodeRequest
  - `accept_change_value` boolean, nullable — Allows payer to change the QR code value when scanning. Defaults to false.
  - `allowed_tax_ids` string[], nullable — Optional allowlist of CPF/CNPJ (with or without formatting) that restricts which payers can use this QR code. Leave this null/omitted unless you specifically need to restrict who can pay. Do not set it from the buyer's document: a Pix payment may legitimately come from another account (for example, a family member) and would then be rejected. When provided, only payers whose document matches one of the listed values are accepted. When omitted or null, payments from any document are accepted.
  - `amount_in_cents` integer, required — Amount in cents (must be greater than 0)
  - `due_date` string, date, nullable — Due date in `YYYY-MM-DD` format. Required for DUE_DATE type.
  - `expiration` integer, nullable — Expiration time in seconds for INSTANT type. Defaults to 86400 (24 hours).
  - `external_reference_id` string, nullable — External unique identifier for client's own tracking. **Must be unique per account if provided.**
  - `payer_data` PayerData
    - `document_number` string, required — Payer CPF or CNPJ (with or without formatting)
    - `document_type` 'cpf' | 'cnpj', required
    - `name` string, required — Payer full name
  - `type` 'INSTANT' | 'DUE_DATE', required

## Response `201`

Dynamic QR code created successfully

- CreateDynamicBrcodeResponse
  - `copy_paste` string, required — PIX copy-paste code (BR Code)
  - `external_reference_id` string, nullable — External reference ID provided by the client (if any)
  - `id` string, uuid, required — Unique QR Code identifier
  - `picture_code_base64` string, required — QR Code image in base64 format

## Other responses

- `400` — Invalid request: malformed JSON, invalid enum values (e.g., 'CPF' instead of 'cpf'), missing required fields, or validation errors. Error codes: INVALID_JSON_BODY, MALFORMED_JSON, INVALID_REQUEST, VALIDATION_ERROR
- `401` — Authentication failed
- `403` — Access denied - missing ManageQRCode permission
- `404` — PIX key not found. Error code: PIX_KEY_NOT_FOUND
- `409` — Conflict: duplicate transaction_id or external_reference_id already exists for this account. Error codes: DUPLICATE_TRANSACTION_ID, DUPLICATE_EXTERNAL_REFERENCE_ID
- `500` — Internal server error

---

[API](https://skmtc.net/kiwify/apis/conta-digital-api.md) · [All operations](https://skmtc.net/kiwify/apis/conta-digital-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kiwify/conta-digital-api/revisions/5e009b25c245/schema)