Create an immediate dynamic PIX QR code

curl --request POST \
  --url https://api.example.com/v1/qrcodes/dynamic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "key": "recipient@bank.com",
  "recipientConciliationId": "JDPI2020010300000000000000000000001",
  "description": [
    {
      "name": "order",
      "value": "42"
    }
  ],
  "expirationTime": 3600,
  "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "payer": {
    "document": "12345678909",
    "name": "Jane Doe",
    "validate": false
  },
  "zipCode": "01310100"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/qrcodes/dynamic"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 10050,\n  \"key\": \"recipient@bank.com\",\n  \"recipientConciliationId\": \"JDPI2020010300000000000000000000001\",\n  \"description\": [\n    {\n      \"name\": \"order\",\n      \"value\": \"42\"\n    }\n  ],\n  \"expirationTime\": 3600,\n  \"indirectId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"payer\": {\n    \"document\": \"12345678909\",\n    \"name\": \"Jane Doe\",\n    \"validate\": false\n  },\n  \"zipCode\": \"01310100\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    amount: 10050,
    key: 'recipient@bank.com',
    recipientConciliationId: 'JDPI2020010300000000000000000000001',
    description: [{name: 'order', value: '42'}],
    expirationTime: 3600,
    indirectId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
    payer: {document: '12345678909', name: 'Jane Doe', validate: false},
    zipCode: '01310100'
  })
};

fetch('https://api.example.com/v1/qrcodes/dynamic', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/qrcodes/dynamic"

payload = {
    "accountId": "acc-123",
    "amount": 10050,
    "key": "recipient@bank.com",
    "recipientConciliationId": "JDPI2020010300000000000000000000001",
    "description": [
        {
            "name": "order",
            "value": "42"
        }
    ],
    "expirationTime": 3600,
    "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "payer": {
        "document": "12345678909",
        "name": "Jane Doe",
        "validate": False
    },
    "zipCode": "01310100"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "qrCode": "00020126...",
  "documentId": "52c43361-caa1-4ddb-9152-708426a25db3",
  "payloadJws": "eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjB9.sig",
  "payloadUrl": "pix.example.com/qr/cob/fzqRwuXYSweWofLD1OX2Bw"
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Create an immediate dynamic PIX QR code

Generates an immediate dynamic PIX QR code and persists its conciliation metadata. The plugin sends the JWS host URLs (urlPayloadJson / urlJwk) to JDPI and self-hosts the signed JWS, so the returned QR is end-to-end resolvable; the response carries the resolvable payload URL the EMV embeds. cobv (due-date) and saque/troco variants are not supported.

WHAT indirectId DECIDES HERE IS WHO SERVES THE QR, and it is a decision about hosting rather than about whose charge it is. This participant may serve INDIRECT participants — institutions registered with POST /v1/indirects. Most of them need nothing here: by default a QR raised for one of them is signed with THIS participant’s certificate and its payload is hosted on THIS participant’s domain, which is the ordinary arrangement and the one nearly every institution wants. An institution that has opted into holding its OWN certificate is the exception, and only for it does indirectId change anything: JDPI then signs with that institution’s certificate, the payload URL is built on that institution’s own domain, and the signed document comes back to you to host there. Certificate and domain are ONE decision, never two — the payer’s app validates the signature against the certificate published at the domain that answered, so signing with one party’s certificate while hosting on another’s does not validate.

⚠️ indirectId IS SILENTLY IGNORED WHILE THIS TENANT’S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF: the value is not parsed, not resolved and not refused, and the QR is signed and hosted by the direct participant as if you had sent none. Nothing in the response says the routing was dropped. Naming an id and getting 404 PIX-0095 back is the evidence the feature is on.

Refusals specific to indirectId, all decided before JDPI is called so a refused QR is never generated: 404 PIX-0095 for an id that addresses no institution registered in this tenant (a malformed UUID lands here too — it can address none); 422 PIX-0100 when the institution it names is not ACTIVE; 422 PIX-0113 when that institution’s registered public base URL names a host a payer’s app cannot resolve; 422 PIX-0112 when the composed payload URL exceeds the 77 characters BACEN allows — the path this participant is configured with spends most of that budget, so an institution’s hostname must be chosen against the remaining allowance BEFORE it is registered, not after.

When indirectId names an indirect that hosts its OWN certificate, the signed JWS comes back in payloadJws and the plugin does NOT store it — the indirect hosts it at payloadUrl on its own infrastructure, so THIS RESPONSE IS THE ONLY DELIVERY OF IT. If the response never reaches you (client timeout, connection reset, proxy error) the charge nevertheless exists at JDPI, and re-sending the same recipientConciliationId is refused as a duplicate (PIX-0065). Recover it, do not re-create it: call GET /v1/qrcodes/list with qrCodeType 12 over the registration window, match your own recipientConciliationId to read its documentId, then call PUT /v1/qrcodes/dynamic/ with the SAME indirectId — the update re-signs the charge and returns a fresh payloadJws (JDPI §8.3.5 returns payloadJws on every update). The update mints a NEW payloadUrl and a regenerated EMV payload, so it REPLACES the lost QR rather than reproducing it; host the new payloadJws at the new payloadUrl and distribute the new qrCode.

Hosting the payload is not the whole obligation: an institution serving its own domain must ALSO publish, at that domain, the key set the payer’s app validates the signature against. It cannot produce that key set itself — JDPI holds the certificate and does the signing — so read it with GET /v1/indirects//jwks and serve those bytes verbatim, re-reading whenever the certificate is rotated. A payload served without a matching key set fails validation at the payer, silently: the QR scans, the app fetches the document, and the payment does not go through.

POST

qrcodes

dynamic

Create an immediate dynamic PIX QR code

curl --request POST \
  --url https://api.example.com/v1/qrcodes/dynamic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "key": "recipient@bank.com",
  "recipientConciliationId": "JDPI2020010300000000000000000000001",
  "description": [
    {
      "name": "order",
      "value": "42"
    }
  ],
  "expirationTime": 3600,
  "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "payer": {
    "document": "12345678909",
    "name": "Jane Doe",
    "validate": false
  },
  "zipCode": "01310100"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/qrcodes/dynamic"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 10050,\n  \"key\": \"recipient@bank.com\",\n  \"recipientConciliationId\": \"JDPI2020010300000000000000000000001\",\n  \"description\": [\n    {\n      \"name\": \"order\",\n      \"value\": \"42\"\n    }\n  ],\n  \"expirationTime\": 3600,\n  \"indirectId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"payer\": {\n    \"document\": \"12345678909\",\n    \"name\": \"Jane Doe\",\n    \"validate\": false\n  },\n  \"zipCode\": \"01310100\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    amount: 10050,
    key: 'recipient@bank.com',
    recipientConciliationId: 'JDPI2020010300000000000000000000001',
    description: [{name: 'order', value: '42'}],
    expirationTime: 3600,
    indirectId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
    payer: {document: '12345678909', name: 'Jane Doe', validate: false},
    zipCode: '01310100'
  })
};

fetch('https://api.example.com/v1/qrcodes/dynamic', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/qrcodes/dynamic"

payload = {
    "accountId": "acc-123",
    "amount": 10050,
    "key": "recipient@bank.com",
    "recipientConciliationId": "JDPI2020010300000000000000000000001",
    "description": [
        {
            "name": "order",
            "value": "42"
        }
    ],
    "expirationTime": 3600,
    "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "payer": {
        "document": "12345678909",
        "name": "Jane Doe",
        "validate": False
    },
    "zipCode": "01310100"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "qrCode": "00020126...",
  "documentId": "52c43361-caa1-4ddb-9152-708426a25db3",
  "payloadJws": "eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjB9.sig",
  "payloadUrl": "pix.example.com/qr/cob/fzqRwuXYSweWofLD1OX2Bw"
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Body

application/json

accountId

string

required

The CRM account id of the recipient (sources name + city).

Example:

"acc-123"

amount

integer<int64>

required

Amount in centavos (an integer).

Example:

10050

key

string

required

The recipient PIX key the dynamic QR pays into.

Example:

"recipient@bank.com"

recipientConciliationId

string

required

Conciliation id (idConciliacaoRecebedor); §8.3.2 mandatory; 26..35 alphanumeric ([a-zA-Z0-9]); dedup gate.

Example:

"JDPI2020010300000000000000000000001"

description

object[] | null

Optional additional-data entries (dadosAdicionais).

Show child attributes

expirationTime

integer<int64>

QR expiration in seconds (0 = JDPI default).

Example:

3600

indirectId

string<uuid>

Optional identifier (UUID) of an indirect participant registered here. When that institution hosts its OWN dynamic-QR certificate, JDPI signs with its certificate, payloadUrl is built on its domain, and payloadJws is returned for it to host; otherwise the QR is signed and hosted by the direct participant exactly as if this were omitted. Omit for a direct QR. Validated server-side: unknown or inactive is rejected. IGNORED, without any error, while this tenant's indirect-participants feature is off.

Example:

"3f2504e0-4f89-41d3-9a0c-0305e82c3301"

payer

object

Optional payer block.

Show child attributes

zipCode

string

Recipient postal code (cep).

Example:

"01310100"

Response

Created

qrCode

string

required

The generated EMV QR-code payload (base64-decoded, ready to render).

Example:

"00020126..."

documentId

string

The JDPI charge GUID (idDocumento) addressing the update leg (dynamic only).

Example:

"52c43361-caa1-4ddb-9152-708426a25db3"

payloadJws

string

The signed JWS payload, returned ONLY when the QR was generated under an indirect participant's own certificate — that indirect hosts it at payloadUrl on its own infrastructure. Absent on the direct path, where the plugin self-hosts it. It is returned ONCE and never stored: if this response is lost, do NOT re-create (the same recipientConciliationId is refused as a duplicate) — read the charge's documentId from GET /v1/qrcodes/list and re-sign it via PUT /v1/qrcodes/dynamic/{documentId} with the same indirectId, which returns a fresh payloadJws on a fresh payloadUrl.

Example:

"eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjB9.sig"

payloadUrl

string

The resolvable JWS host URL the dynamic QR embeds (urlPayloadJson; schema-less; dynamic only).

Example:

"pix.example.com/qr/cob/fzqRwuXYSweWofLD1OX2Bw"

Key DICT API

Key Claims API

Banks API

Indirect participants API

Transactions API

Transaction Limits API

QR Codes API

Refunds API

Pix Automático · Authorization requests

Pix Automático · Authorization management

Pix Automático · Composite QR codes

Pix Automático · Authorization events

Pix Automático · Schedule events

Pix Automático · Schedules and payment instructions

Pix Automático · Settlement

MED · Refunds

MED · Fraud markers

MED · Infractions

MED · Value recovery

Webhooks API

Error handling

Events

Create an immediate dynamic PIX QR code

Authorizations

Body

Response