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",
  "ispb": "12345678",
  "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  \"ispb\": \"12345678\",\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',
    ispb: '12345678',
    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",
    "ispb": "12345678",
    "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": "<string>",
  "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": "<string>",
  "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": "<string>",
  "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, and they apply in this order: while this tenant’s indirect-participants feature is off the value is refused 422 PIX-0111 naming the setting, so none of the refusals below can be reached and nothing is re-signed — an update that silently reverted to the direct participant would move a LIVE charge onto another certificate and domain, and its refreshed QR would stop validating at the payer’s app. With the feature on, the value is validated and 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.

Which of this deployment’s direct participants acts is decided by ispb, by exactly the rule an order’s payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. The published payloadUrl and its JWKS location carry THAT participant’s ISPB, so a QR minted as the wrong participant sends every payer’s PSP to a key set that cannot validate its signature — and by then the QR is already in the wild. An indirect’s QR is minted, signed and published by the participant recorded at that indirect’s registration - the one direct participant it mounts on, which is NOT necessarily this deployment’s default one - so supplying indirectId together with any other ispb, the default one included, is 422 PIX-0102; leaving ispb blank on an indirect request resolves to that same recorded participant rather than to the default.

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",
  "ispb": "12345678",
  "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  \"ispb\": \"12345678\",\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',
    ispb: '12345678',
    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",
    "ispb": "12345678",
    "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": "<string>",
  "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": "<string>",
  "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": "<string>",
  "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. Refused 422 PIX-0111, naming the setting to enable, while this tenant's indirect-participants feature is off: routing you supply is never silently dropped.

Example:

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

ispb

string

The ISPB of the direct participant that mints this QR. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. The published payloadUrl and its JWKS location are built under this participant's ISPB, so a QR minted as the wrong one points every payer's PSP at a key set that cannot validate its signature. When indirectId is supplied this must be blank or the participant recorded at that indirect's registration, which is NOT necessarily this deployment's default one; naming any other is 422 PIX-0102. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.

Pattern: ^[0-9]{8}$

Example:

"12345678"

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"

Direct participant APIs

Indirect participant APIs

Update an immediate dynamic PIX QR code

Authorizations

Path Parameters

Body

Response