Update an immediate dynamic PIX QR code

curl --request PUT \
  --url https://api.example.com/v1/qrcodes/dynamic/{documentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "key": "recipient@bank.com",
  "recipientConciliationId": "JDPI2020010300000000000000000000001",
  "status": 0,
  "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/{documentId}"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 10050,\n  \"key\": \"recipient@bank.com\",\n  \"recipientConciliationId\": \"JDPI2020010300000000000000000000001\",\n  \"status\": 0,\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("PUT", 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: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    amount: 10050,
    key: 'recipient@bank.com',
    recipientConciliationId: 'JDPI2020010300000000000000000000001',
    status: 0,
    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/{documentId}', 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/{documentId}"

payload = {
    "accountId": "acc-123",
    "amount": 10050,
    "key": "recipient@bank.com",
    "recipientConciliationId": "JDPI2020010300000000000000000000001",
    "status": 0,
    "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.put(url, json=payload, headers=headers)

print(response.text)

{
  "qrCode": "00020126...",
  "revision": 2,
  "payloadJws": "eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjJ9.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"
  }
}

Update an immediate dynamic PIX QR code

Updates an existing immediate dynamic PIX QR code (JDPI §8.3.5): the charge amount, conciliation, expiration, optional payer, and the charge status (0=Active, 1=Concluded, 2=Removed by recipient, 3=Removed by PSP). The recipient name + city are CRM-sourced (never the body). The plugin re-hosts the updated signed JWS so the QR stays end-to-end resolvable; the response carries the JDPI revision and the resolvable payload URL.

It is also the RECOVERY path for an indirect-hosted payloadJws whose create response never reached the caller: the update re-signs the charge under whichever certificate the request names and returns the fresh payloadJws, so supply the SAME indirectId the charge was created with (omitting it re-signs under the DIRECT participant and moves the location onto the direct FQDN). Every update — recovery or not — mints a new payloadUrl and a regenerated EMV payload, so the previously advertised location is superseded.

THE PLUGIN STORES NO INDIRECT ASSOCIATION FOR A CHARGE, so this request’s indirectId — not the create’s — decides who signs and where the location points, on every update. Omitting it on a charge created for an institution that hosts its own certificate is not a no-op: it MOVES the charge onto the direct participant’s certificate and domain, and the institution’s own domain stops serving the current location. The same rules as on create apply here: the value is silently ignored while this tenant’s indirect-participants feature is off, and it is refused with 404 PIX-0095 (unknown or malformed id), 422 PIX-0100 (not ACTIVE), 422 PIX-0113 (registered host a payer’s app cannot resolve) or 422 PIX-0112 (composed payload URL over the 77-character BACEN cap) — all before JDPI is called, so a refused update changes nothing.

PUT

qrcodes

dynamic

{documentId}

Update an immediate dynamic PIX QR code

curl --request PUT \
  --url https://api.example.com/v1/qrcodes/dynamic/{documentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "key": "recipient@bank.com",
  "recipientConciliationId": "JDPI2020010300000000000000000000001",
  "status": 0,
  "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/{documentId}"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 10050,\n  \"key\": \"recipient@bank.com\",\n  \"recipientConciliationId\": \"JDPI2020010300000000000000000000001\",\n  \"status\": 0,\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("PUT", 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: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    amount: 10050,
    key: 'recipient@bank.com',
    recipientConciliationId: 'JDPI2020010300000000000000000000001',
    status: 0,
    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/{documentId}', 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/{documentId}"

payload = {
    "accountId": "acc-123",
    "amount": 10050,
    "key": "recipient@bank.com",
    "recipientConciliationId": "JDPI2020010300000000000000000000001",
    "status": 0,
    "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.put(url, json=payload, headers=headers)

print(response.text)

{
  "qrCode": "00020126...",
  "revision": 2,
  "payloadJws": "eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjJ9.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.

Path Parameters

documentId

string

required

The existing charge GUID to update (JDPI idDocumento).

Example:

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

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.5 mandatory; 26..35 alphanumeric ([a-zA-Z0-9]).

Example:

"JDPI2020010300000000000000000000001"

status

integer<int64>

required

Charge status: 0=Active, 1=Concluded, 2=Removed by recipient, 3=Removed by PSP.

Example:

0

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, mirroring the create body. Supply the SAME institution the charge was generated for: the plugin stores no indirect association for a QR, so an omitted value re-signs the charge under the DIRECT participant's certificate and moves its location onto the direct participant's domain. 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

qrCode

string

required

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

Example:

"00020126..."

revision

integer<int64>

required

The JDPI-computed charge revision (revisao).

Example:

2

payloadJws

string

The re-signed JWS payload, returned ONLY when the update ran under an indirect participant's own certificate. Absent on the direct path.

Example:

"eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjJ9.sig"

payloadUrl

string

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

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

Update an immediate dynamic PIX QR code

Authorizations

Path Parameters

Body

Response