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 '
{
  "amount": 10050,
  "key": "recipient@bank.com",
  "recipientConciliationId": "JDPI2020010300000000000000000000001",
  "status": 0,
  "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
  "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  \"amount\": 10050,\n  \"key\": \"recipient@bank.com\",\n  \"recipientConciliationId\": \"JDPI2020010300000000000000000000001\",\n  \"status\": 0,\n  \"accountId\": \"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b\",\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({
    amount: 10050,
    key: 'recipient@bank.com',
    recipientConciliationId: 'JDPI2020010300000000000000000000001',
    status: 0,
    accountId: '019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b',
    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 = {
    "amount": 10050,
    "key": "recipient@bank.com",
    "recipientConciliationId": "JDPI2020010300000000000000000000001",
    "status": 0,
    "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
    "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 come from accountId’s CRM account, or from recipient when an indirect declares its own customer (the same rule as on create). 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.

A CHARGE STAYS WITH THE INDIRECT IT WAS CREATED FOR. Every charge created records which indirect it was created for (none, for the direct participant’s own), and an update naming a different one is refused 404 PIX-0147 — after the indirectId checks below and before JDPI is called, so the charge, its revision and its hosted payload are not changed. That covers naming indirect A on a charge created for indirect B, and naming any indirect on a charge created for the direct participant. A charge created before this record existed counts as the direct participant’s own when a partner is behind the request, calling or relayed; for the direct participant’s own credential it is not checked. An update naming no indirect is not checked. The record decides only WHO MAY update; this request’s indirectId — not the create’s — still 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. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. For an indirect participant: 422 PIX-0141 when the account is not in the ledger the indirect is mounted on, and 409 PIX-0140 when the indirect is mounted on books that are no longer configured for Pix (an operator setting). 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 '
{
  "amount": 10050,
  "key": "recipient@bank.com",
  "recipientConciliationId": "JDPI2020010300000000000000000000001",
  "status": 0,
  "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
  "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  \"amount\": 10050,\n  \"key\": \"recipient@bank.com\",\n  \"recipientConciliationId\": \"JDPI2020010300000000000000000000001\",\n  \"status\": 0,\n  \"accountId\": \"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b\",\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({
    amount: 10050,
    key: 'recipient@bank.com',
    recipientConciliationId: 'JDPI2020010300000000000000000000001',
    status: 0,
    accountId: '019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b',
    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 = {
    "amount": 10050,
    "key": "recipient@bank.com",
    "recipientConciliationId": "JDPI2020010300000000000000000000001",
    "status": 0,
    "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
    "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"
  }
}

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Parâmetros de caminho

documentId

string

obrigatório

The existing charge GUID to update (JDPI idDocumento).

Exemplo:

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

Corpo

application/json

amount

integer<int64>

obrigatório

Amount in centavos (an integer).

Exemplo:

10050

key

string

obrigatório

The recipient PIX key the dynamic QR pays into.

Exemplo:

"recipient@bank.com"

recipientConciliationId

string

obrigatório

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

Exemplo:

"JDPI2020010300000000000000000000001"

status

integer<int64>

obrigatório

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

Exemplo:

0

accountId

string

The Midaz ledger account id of the recipient, a customer of the minting direct participant (sources name + city). REQUIRED on a direct QR (absent or blank is 400 PIX-0061). On a QR carrying indirectId it is DEPRECATED in favour of recipient: an indirect keeps its customers in its own core. accountId is still accepted there, unchanged, when the direct participant's own credential sends the request, and refused 400 PIX-0061 when an Access Manager partner is behind the request. Sending it together with recipient is 400 PIX-0061.

Exemplo:

"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b"

description

object[] | null

Optional additional-data entries (dadosAdicionais).

Show child attributes

expirationTime

integer<int64>

QR expiration in seconds (0 = JDPI default).

Exemplo:

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: a charge records the indirect it was generated for, and naming ANOTHER indirect - or naming one on a charge generated for the direct participant - is refused 404 PIX-0147 before JDPI is called, and the charge is not changed. A charge generated before that record existed counts as the direct participant's own when a partner is behind the request, calling or relayed; for the direct participant's own credential it is not checked. An omitted value is not checked, and 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.

Exemplo:

"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-9A-Z]{8}$

Exemplo:

"12345678"

payer

object

Optional payer block.

Show child attributes

recipient

object

The customer of the indirect participant who receives this QR, as the indirect declares it. Only with indirectId, and required there unless the legacy accountId is sent instead: an indirect keeps its customers in its own core, so this plugin reads no record of them and sends this name and city to JD as the QR's recipient. Refused 400 PIX-0061 on a direct QR, together with accountId, or with a blank name or city.

Show child attributes

zipCode

string

Recipient postal code (cep).

Exemplo:

"01310100"

Resposta

qrCode

string

obrigatório

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

Exemplo:

"00020126..."

revision

integer<int64>

obrigatório

The JDPI-computed charge revision (revisao).

Exemplo:

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.

Exemplo:

"eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjJ9.sig"

payloadUrl

string

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

Exemplo:

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

APIs do participante direto

APIs de participantes indiretos

Update an immediate dynamic PIX QR code

Autorizações

Parâmetros de caminho

Corpo

Resposta