Create a static PIX QR code

curl --request POST \
  --url https://api.example.com/v1/qrcodes/static \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "key": "recipient@bank.com",
  "description": "Invoice 42",
  "ispb": "12345678",
  "txId": "TX-001"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 10050,\n  \"key\": \"recipient@bank.com\",\n  \"description\": \"Invoice 42\",\n  \"ispb\": \"12345678\",\n  \"txId\": \"TX-001\"\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',
    description: 'Invoice 42',
    ispb: '12345678',
    txId: 'TX-001'
  })
};

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

import requests

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

payload = {
    "accountId": "acc-123",
    "amount": 10050,
    "key": "recipient@bank.com",
    "description": "Invoice 42",
    "ispb": "12345678",
    "txId": "TX-001"
}
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": "<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"
  }
}

Create a static PIX QR code

Generates a static PIX QR code into the recipient’s key. The recipient name and city are sourced from the CRM alias, never the request body. An amount of 0 produces an any-amount static QR.

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.

POST

qrcodes

static

Create a static PIX QR code

curl --request POST \
  --url https://api.example.com/v1/qrcodes/static \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "key": "recipient@bank.com",
  "description": "Invoice 42",
  "ispb": "12345678",
  "txId": "TX-001"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 10050,\n  \"key\": \"recipient@bank.com\",\n  \"description\": \"Invoice 42\",\n  \"ispb\": \"12345678\",\n  \"txId\": \"TX-001\"\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',
    description: 'Invoice 42',
    ispb: '12345678',
    txId: 'TX-001'
  })
};

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

import requests

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

payload = {
    "accountId": "acc-123",
    "amount": 10050,
    "key": "recipient@bank.com",
    "description": "Invoice 42",
    "ispb": "12345678",
    "txId": "TX-001"
}
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": "<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.

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; 0 = any-amount static QR).

Example:

10050

key

string

required

The recipient PIX key the static QR pays into.

Example:

"recipient@bank.com"

description

string

Free-text additional data (dadosAdicionais).

Example:

"Invoice 42"

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. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.

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

Example:

"12345678"

txId

string

Conciliation id (idConciliacaoRecebedor); §8.3.1 caps it at 25 characters and states no charset (default "***").

Example:

"TX-001"

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"

Direct participant APIs

Indirect participant APIs

Create a static PIX QR code

Authorizations

Body

Response