Printed Dynamic QRs

A Printed Dynamic QR is a permanent QR code that you print for a physical point of sale. You create it one time and put it at a checkout. It does not change. When you charge a payer, the QR Code Creation endpoint attaches the charge to the printed QR. The payer scans the same printed QR, and the bank application shows the amount to pay.

Each sale (the charge that you create for one payer on a printed checkout) expires after 5 minutes. The expire field of QR Code Creation does not apply to a sale.

How charges work

You do not call a different endpoint to create a sale. You configure the checkouts that use a Printed Dynamic QR as their default. After that, the usual create_dynamic_pix request creates a sale on the checkout:

1. kamiPay finds that the checkout of checkout_id and store_id has a Printed Dynamic QR as its default. If you do not send them, the checkout is checkout 1 of store 1.
2. kamiPay attaches the sale to the printed QR of the checkout. The payer who scans the printed QR sees the amount of the sale.
3. The response has qr_type: "printed_dynamic" and the EMV of the printed QR in printed_dynamic_qr_data.pqr_emv. It also has an emv that is for the checkout, not for the sale (see rule 2 of One pending sale per checkout).
4. When the payer pays, the webhooks identify the sale by its pix_id and kamipay_id.

  Your POS                kamiPay                  Gateway               Payer
      │                      │                         │                   │
      │  POST                │                         │                   │
      │  create_dynamic_pix  │                         │                   │
      │  (checkout_id,       │                         │                   │
      │   store_id, amount)  │                         │                   │
      │─────────────────────►│                         │                   │
      │                      │                         │                   │
      │                      │  Checkout has Printed   │                   │
      │                      │  Dynamic QR             │                   │
      │                      │  → attach charge to QR  │                   │
      │                      │────────────────────────►│                   │
      │                      │◄────────────────────────│                   │
      │                      │                         │                   │
      │◄─────────────────────│                         │                   │
      │  { emv, qr_type,     │                         │                   │
      │    printed_dynamic_  │                         │                   │
      │    qr_data: {        │                         │                   │
      │      pqr_emv, … },   │                         │                   │
      │    operation_id, … } │                         │                   │
      │                      │                         │                   │
      │  Show returned QR    │                         │                   │
      │  (or the payer scans │                         │                   │
      │   the printed one)   │                         │                   │
      │                      │                         │◄──── Scans QR ────│
      │                      │                         │  Payment settled  │
      │                      │◄──────── Webhook ───────│                   │
      │◄──── Notification ───│                         │                   │
      │                      │                         │                   │

One pending sale per checkout

A printed checkout holds one pending sale at a time. Design the flow at your counter for these rules:

1. A new sale replaces the unpaid sale before it. The replaced sale is a displaced sale. This is intentional: with a new sale, a cashier corrects a wrong amount, and does not wait until the first sale expires. kamiPay does not tell you about the displaced sale.
2. Each QR of the checkout charges the newest sale. This applies to the printed QR, and also to the emv that the API returned for an older sale. That emv is for the location of the checkout, not for the sale. With some payment gateways, it is the EMV of the printed QR. With other payment gateways, it is a different EMV, and its text still shows the older amount.
3. kamiPay credits the payment to the newest sale. The QR that the payer scans does not change this. The webhooks have the pix_id and kamipay_id of the newest sale.
4. kamiPay never sends a webhook for a displaced sale. Tx Status continues to return "TX not found" for it. Thus, a displaced sale never closes by itself.
5. But a displaced sale is not final. If the payer paid just before you created the new sale, kamiPay can report that payment for the displaced sale later.
6. If no sale is pending, the payer cannot read the printed QR. The bank application of the payer says that it cannot scan the code. Thus, the cashier must create the sale before the payer scans.

What to do

• Treat a new sale as the cancellation of the unpaid sale before it. Mark the earlier sale as displaced immediately. Show only the QR that the API returned for the newest sale. But still accept a late processing for the displaced sale.
• Create a new sale while a sale is pending only to correct the amount. For the next payer, wait for the processing of the current sale, or until the sale expires.
• Match each webhook by pix_id or kamipay_id, never by the QR on the screen. Then make sure that its amount_brl is the amount of the sale that you expect.

Errors when creating a sale

On a printed checkout, create_dynamic_pix can also return these errors. The API does not create a sale for them.

The 422 detail is the exact text that the API returns, with no space after assigned.. In your code, use the status code, not the text.

Checkout configuration

You configure Printed Dynamic QRs yourself, through the API. A checkout is in printed mode when it has a Printed Dynamic QR and its default_qr configuration is printed_dynamic_qr. There are two procedures:

• In one request: create the Printed Dynamic QR with auto_create_checkout: true. If the checkout does not exist, kamiPay creates it. Then kamiPay creates the printed QR, and only after that sets default_qr. This also works on an existing checkout (see Auto-creating the checkout in one call).
• On an existing checkout, step by step: create the Printed Dynamic QR without auto_create_checkout. The checkout continues to charge usual dynamic QRs, so you can print the QR before you use it. To change the checkout to printed mode, set default_qr to printed_dynamic_qr with Checkout Configs. Create the QR first: a checkout in printed mode with no printed QR rejects each sale with 422.

After this configuration, you do not change your integration. The usual create_dynamic_pix request uses the Printed Dynamic QR. List Checkouts shows the default_qr of the checkout.

Create Printed Dynamic QR

POST /v2/printed_dynamic_qrs

Creates a permanent QR code for a checkout of a store. If the checkout already has a Printed Dynamic QR, the API returns that QR with HTTP 200, not 201. The checks of the request come first, also when the checkout has a QR. For example, a wallet that is not on Polygon gets its 400.

Body Parameters

Example Request

const url = `${baseURL}/v2/printed_dynamic_qrs`;

const body = {
  checkout_id: 1,
  store_id: 1,
};

const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

import requests

url = f"{base_url}/v2/printed_dynamic_qrs"

body = {
    "checkout_id": 1,
    "store_id": 1,
}

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

response = requests.post(url, headers=headers, json=body)

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
)

func main() {
  url := baseURL + "/v2/printed_dynamic_qrs"

  body := map[string]interface{}{
    "checkout_id": 1,
    "store_id":    1,
  }

  requestBody, _ := json.Marshal(body)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(requestBody))
  req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", accessToken))
  req.Header.Add("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    fmt.Println("Error:", err)
    return
  }
  defer resp.Body.Close()
}

Response

{
  "printed_dynamic_qr_id": "pqr_01km0mbfxdf4g87eb8yytas95k",
  "qr_emvcode": "00020101021226930014br.gov.bcb.pix...",
  "qr_location_id": "3f6c1a9e-7b2d-4e8f-a5c4-9d0b2e7f1a63",
  "address": "0x46d52020**********1fbdcc297d",
  "checkout_id": 1,
  "merchant_id": 42,
  "store_id": 1,
  "created_at": 1730455200
}

{
  "printed_dynamic_qr_id": "pqr_01km0mbfxdf4g87eb8yytas95k",
  "qr_emvcode": "00020101021226930014br.gov.bcb.pix...",
  "qr_location_id": "3f6c1a9e-7b2d-4e8f-a5c4-9d0b2e7f1a63",
  "address": "0x46d52020**********1fbdcc297d",
  "checkout_id": 1,
  "merchant_id": 42,
  "store_id": 1,
  "created_at": 1728981000
}

{
  "detail": "send either wallet_id or address, not both"
}

{
  "detail": "Could not validate credentials"
}

{
  "detail": "Checkout not found for this merchant"
}

{
  "detail": "checkout already exists with a different wallet; update it via PATCH /v2/stores/1/checkouts/500"
}

{
  "detail": "Printed dynamic QRs aren't available for this merchant"
}

{
  "detail": "Internal Server Error during printed dynamic QR creation"
}

{
  "detail": "Gateway error during printed dynamic QR creation"
}

{
  "detail": "printed_qr_disabled"
}

Response Fields

Auto-creating the checkout in one call

Send auto_create_checkout: true to do three operations in one request: create the checkout, create the printed QR, and change the checkout to printed mode (default_qr=printed_dynamic_qr). This also works on an existing checkout. kamiPay uses that checkout, and changes it to printed mode when its QR exists, also if you set it to dynamic QRs again before. If the wallet_id or address is not the wallet of the existing checkout, the API still rejects the request with 409.

const response = await fetch(`${baseURL}/v2/printed_dynamic_qrs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    checkout_id: 500,           // the id you want the new checkout to have
    auto_create_checkout: true, // store_id omitted → defaults to 1
  }),
});

If you do not send wallet_id or address, the new checkout gets the wallet of checkout 1 of the same store_id. After this request, each create_dynamic_pix request for that (store_id, checkout_id) uses the Printed Dynamic QR flow.

If the payment gateway fails

• kamiPay creates the checkout before it calls the payment gateway. kamiPay changes the checkout to printed mode only when its printed QR exists.
• The API rejects the request with 502. The checkout stays dynamic, and continues to charge usual dynamic QRs.
• To complete the operation, send the same request again, with auto_create_checkout: true. The request creates the QR and changes the checkout to printed mode.

List Printed Dynamic QRs

GET /v2/printed_dynamic_qrs

Returns the Printed Dynamic QRs of your account, grouped as stores → checkouts → printed_dynamic_qrs. Use it to find the checkouts that already have a printed QR.

Query Parameters

If page or page_size is out of range, the API rejects the request with 422.

Example Request

const url = `${baseURL}/v2/printed_dynamic_qrs?page=1&page_size=100`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});

import requests

url = f"{base_url}/v2/printed_dynamic_qrs"

headers = {"Authorization": f"Bearer {access_token}"}
params = {"page": 1, "page_size": 100}

response = requests.get(url, headers=headers, params=params)

package main

import (
  "fmt"
  "net/http"
)

func main() {
  url := baseURL + "/v2/printed_dynamic_qrs?page=1&page_size=100"

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", accessToken))

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    fmt.Println("Error:", err)
    return
  }
  defer resp.Body.Close()
}

Response

{
  "total": 2,
  "page": 1,
  "page_size": 100,
  "stores": [
    {
      "store_id": 1,
      "store_name": "Main Store",
      "company_name": "Acme Ltda",
      "checkouts": [
        {
          "checkout_id": 4,
          "checkout_desc": "Register 4",
          "printed_dynamic_qrs": [
            {
              "printed_dynamic_qr_id": "pqr_01km0mbfxdf4g87eb8yytas95k",
              "qr_emvcode": "00020101021226930014br.gov.bcb.pix...",
              "address": "0x46d52020**********1fbdcc297d"
            }
          ]
        },
        {
          "checkout_id": 500,
          "checkout_desc": "Auto created via printed dynamic qr for 500",
          "printed_dynamic_qrs": [
            {
              "printed_dynamic_qr_id": "pqr_01km2v7c4hf9t3x8q6wz5n1b2d",
              "qr_emvcode": "00020101021226930014br.gov.bcb.pix...",
              "address": "0x46d52020**********1fbdcc297d"
            }
          ]
        }
      ]
    }
  ]
}

{
  "detail": "Could not validate credentials"
}

{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["query", "page_size"],
      "msg": "Input should be less than or equal to 100",
      "input": "101",
      "ctx": {
        "le": 100
      }
    }
  ]
}

{
  "detail": "Internal Server Error during printed dynamic QR listing"
}

Response Fields