Skip to main content
POST
/
v1
/
dynamic-qrcode
Create Dynamic QR Code
curl --request POST \
  --url https://conta-public-api.kiwify.com/v1/dynamic-qrcode \
  --header 'Content-Type: application/json' \
  --header 'X-PoP-Challenge: <api-key>' \
  --header 'X-PoP-Format: <api-key>' \
  --header 'X-PoP-Signature: <api-key>' \
  --header 'x-access-id: <api-key>' \
  --data '
{
  "amount_in_cents": 4000,
  "type": "INSTANT",
  "accept_change_value": false,
  "allowed_tax_ids": [
    "012.345.678-90",
    "45.059.493/0001-73"
  ],
  "due_date": "2026-12-31",
  "expiration": 86400,
  "external_reference_id": "external-ref-123",
  "payer_data": {
    "document_number": "012.345.678-90",
    "document_type": "cpf",
    "name": "João Silva"
  }
}
'
{
  "copy_paste": "00020126...",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "picture_code_base64": "<string>",
  "external_reference_id": "order-12345"
}

Authorizations

​
x-access-id
string
header
required

UUID of the service account (e.g., 550e8400-e29b-41d4-a716-446655440000)

​
X-PoP-Challenge
string
header
required

Unix timestamp in milliseconds (e.g., 1704636800000). Must be within 5 minutes of server time.

​
X-PoP-Format
string
header
required

Must be 'service-account' for service account authentication

​
X-PoP-Signature
string
header
required

EdDSA signature of the request in base64 format. Signs: uri:method:body:timestamp

Body

application/json
​
amount_in_cents
integer<int64>
required

Amount in cents (must be greater than 0)

Example:

4000

​
type
enum<string>
required

QR Code type: INSTANT or DUE_DATE

Available options:
INSTANT,
DUE_DATE
​
accept_change_value
boolean | null

Allows payer to change the QR code value when scanning. Defaults to false.

Example:

false

​
allowed_tax_ids
string[] | null

Optional list of CPF/CNPJ (with or without formatting) that restricts which payers can use this QR code. When provided, only payers whose document matches one of the listed values will be accepted. When omitted or null, payments from any document are accepted.

Example:
["012.345.678-90", "45.059.493/0001-73"]
​
due_date
string<date> | null

Due date in YYYY-MM-DD format. Required for DUE_DATE type.

Example:

"2026-12-31"

​
expiration
integer<int32> | null

Expiration time in seconds for INSTANT type. Defaults to 86400 (24 hours).

Required range: x >= 0
Example:

86400

​
external_reference_id
string | null

External unique identifier for client's own tracking. Must be unique per account if provided.

Example:

"external-ref-123"

​
payer_data
object

Payer information. Optional for INSTANT type, required for DUE_DATE type.

Response

Dynamic QR code created successfully

​
copy_paste
string
required

PIX copy-paste code (BR Code)

Example:

"00020126..."

​
id
string<uuid>
required

Unique QR Code identifier

​
picture_code_base64
string
required

QR Code image in base64 format

​
external_reference_id
string | null

External reference ID provided by the client (if any)

Example:

"order-12345"