Este guia descreve como criar um pedido com QR Code PIX utilizando a API de Order, informando o método de pagamento diretamente no objeto charges.
QR Code é de uso único
O QR Code gerado pode ser utilizado para apenas um pagamento. Após a confirmação bem-sucedida da transação, o mesmo QR Code não poderá ser reutilizado para receber novos pagamentos.
Requisitos
Antes de iniciar a integração, verifique se sua conta PagBank possui pelo menos uma chave PIX de endereçamento ativa associada:
- Se houver apenas uma chave PIX cadastrada, ela será utilizada na geração do QR Code.
- Caso existam múltiplas chaves PIX ativas, será dada prioridade à utilização de uma chave de endereçamento aleatória.
Criando um pedido com QR Code PIX
Para criar um pedido com QR Code PIX, utilize o endpoint Criar pedido. Durante a criação do pedido, as informações do pagamento devem ser enviadas dentro do objeto charges. Para que a cobrança seja criada como PIX, é necessário informar o método de pagamento PIX por meio do objeto payment_method.
O campo charges.payment_method.pix.expiration_date define a validade do QR Code.
Após a criação do pedido com QR Code PIX, o parâmetro charges.status assumirá um dos seguintes valores:
WAITING: indica que o sistema aguarda a confirmação do pagamento pelo comprador.DECLINED: indica que a transação foi negada pelo PagBank.
Análise de Risco
Todos os QR Code PIX passam por análise de risco.
Exemplos
Abaixo, você encontra exemplos de requisição e respostas para a criação de um pedido com QR Code PIX utilizando o endpoint Criar pedido.
curl --request POST \
--url https://sandbox.api.pagseguro.com/orders \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '
{
"customer": {
"name": "Jose Silva",
"email": "[email protected]",
"tax_id": "12345678909",
"phones": [
{
"country": "55",
"area": "19",
"number": "981389324",
"type": "MOBILE"
}
]
},
"items": [
{
"reference_id": "referencia do item",
"name": "nome do item",
"quantity": 1,
"unit_amount": 102
}
],
"shipping": {
"address": {
"street": "Avenida Brigadeiro Faria Lima",
"number": "1384",
"complement": "apto 12",
"locality": "Pinheiros",
"city": "São Paulo",
"region_code": "SP",
"country": "BRA",
"postal_code": "01452002"
}
},
"charges": [
{
"reference_id": "referencia da cobranca",
"description": "descricao da cobranca",
"amount": {
"value": 20534,
"currency": "BRL"
},
"payment_method": {
"type": "PIX",
"pix": {
"expiration_date": "2026-08-06T20:14:00Z"
}
}
}
],
"notification_urls": [
"https://meusite.com/notificacoes"
]
}
'
{
"id": "ORDE_3D560F48-E086-4F3C-A5A1-B7AB7BEACC2C",
"created_at": "2026-07-13T17:37:53.568-03:00",
"customer": {
"name": "Jose Silva",
"email": "[email protected]",
"tax_id": "12345678909",
"phones": [
{
"type": "MOBILE",
"country": "55",
"area": "19",
"number": "981389324"
}
]
},
"items": [
{
"reference_id": "referencia do item",
"name": "nome do item",
"quantity": 1,
"unit_amount": 102
}
],
"shipping": {
"address": {
"street": "Avenida Brigadeiro Faria Lima",
"number": "1384",
"complement": "apto 12",
"locality": "Pinheiros",
"city": "São Paulo",
"region_code": "SP",
"country": "BRA",
"postal_code": "01452002"
}
},
"charges": [
{
"id": "CHAR_114DB991-F5EA-496A-8D2C-4497F53CED22",
"reference_id": "referencia da cobranca",
"status": "WAITING",
"created_at": "2026-07-13T17:37:54.091-03:00",
"description": "descricao da cobranca",
"amount": {
"value": 20534,
"currency": "BRL",
"summary": {
"total": 20534,
"paid": 0,
"refunded": 0
}
},
"payment_response": {
"code": "20000",
"message": "SUCESSO"
},
"payment_method": {
"type": "PIX",
"pix": {
"expiration_date": "2026-08-06T20:14:00Z"
}
},
"metadata": {
"ps_order_id": "ORDE_3D560F48-E086-4F3C-A5A1-B7AB7BEACC2C"
},
"links": [
{
"rel": "SELF",
"href": "https://sandbox.api.pagseguro.com/charges/CHAR_114DB991-F5EA-496A-8D2C-4497F53CED22",
"media": "application/json",
"type": "GET"
},
{
"rel": "QRCODE.PNG",
"href": "https://sandbox.api.pagseguro.com/qrcode/QRCO_0F63EB5F-61B8-4466-A4C9-7F824193C234/png",
"media": "image/png",
"type": "GET"
},
{
"rel": "QRCODE.BASE64",
"href": "https://sandbox.api.pagseguro.com/qrcode/QRCO_0F63EB5F-61B8-4466-A4C9-7F824193C234/base64",
"media": "text/plain",
"type": "GET"
}
],
"qr_code": {
"id": "QRCO_0F63EB5F-61B8-4466-A4C9-7F824193C234",
"text": "00020101021226850014br.gov.bcb.pix2563api-h.pagseguro.com/pix/v2/0F63EB5F-61B8-4466-A4C9-7F824193C2345204899953039865802BR5921Pagseguro Internet SA6009SAO PAULO62070503***63045677"
}
}
],
"notification_urls": [
"https://meusite.com/notificacoes"
],
"links": [
{
"rel": "SELF",
"href": "https://sandbox.api.pagseguro.com/orders/ORDE_3D560F48-E086-4F3C-A5A1-B7AB7BEACC2C",
"media": "application/json",
"type": "GET"
},
{
"rel": "PAY",
"href": "https://sandbox.api.pagseguro.com/orders/ORDE_3D560F48-E086-4F3C-A5A1-B7AB7BEACC2C/pay",
"media": "application/json",
"type": "POST"
}
]
}
{
"id": "ORDE_7207C317-E6A5-4965-82EB-D8B2DEB970F5",
"created_at": "2026-07-13T17:35:07.290-03:00",
"customer": {
"name": "Jose Silva",
"email": "[email protected]",
"tax_id": "12345678909",
"phones": [
{
"type": "MOBILE",
"country": "55",
"area": "19",
"number": "981389324"
}
]
},
"items": [
{
"reference_id": "referencia do item",
"name": "nome do item",
"quantity": 1,
"unit_amount": 102
}
],
"shipping": {
"address": {
"street": "Avenida Brigadeiro Faria Lima",
"number": "1384",
"complement": "apto 12",
"locality": "Pinheiros",
"city": "São Paulo",
"region_code": "SP",
"country": "BRA",
"postal_code": "01452002"
}
},
"charges": [
{
"id": "CHAR_1563A40F-E026-48A8-8A2F-87BDCFB79565",
"reference_id": "referencia da cobranca",
"status": "DECLINED",
"created_at": "2026-07-13T17:35:07.813-03:00",
"description": "descricao da cobranca",
"amount": {
"value": 30534,
"currency": "BRL",
"summary": {
"total": 30534,
"paid": 0,
"refunded": 0
}
},
"payment_response": {
"code": "10000",
"message": "NAO AUTORIZADO PELO PAGSEGURO"
},
"payment_method": {
"type": "PIX",
"pix": {
"expiration_date": "2026-08-06T20:14:00Z"
}
},
"metadata": {
"ps_order_id": "ORDE_7207C317-E6A5-4965-82EB-D8B2DEB970F5"
},
"links": [
{
"rel": "SELF",
"href": "https://sandbox.api.pagseguro.com/charges/CHAR_1563A40F-E026-48A8-8A2F-87BDCFB79565",
"media": "application/json",
"type": "GET"
}
]
}
],
"notification_urls": [
"https://meusite.com/notificacoes"
],
"links": [
{
"rel": "SELF",
"href": "https://sandbox.api.pagseguro.com/orders/ORDE_7207C317-E6A5-4965-82EB-D8B2DEB970F5",
"media": "application/json",
"type": "GET"
},
{
"rel": "PAY",
"href": "https://sandbox.api.pagseguro.com/orders/ORDE_7207C317-E6A5-4965-82EB-D8B2DEB970F5/pay",
"media": "application/json",
"type": "POST"
}
]
}
{
"id": "ORDE_3B3C39C2-9125-4923-918C-4876FBA97269",
"reference_id": "ex-00001",
"created_at": "2026-08-04T17:27:24.526-03:00",
"customer": {
"name": "Jose da Silva",
"email": "[email protected]",
"tax_id": "12345678909",
"phones": [
{
"type": "MOBILE",
"country": "55",
"area": "11",
"number": "999999999"
}
]
},
"items": [
{
"reference_id": "referencia do item",
"name": "nome do item",
"quantity": 1,
"unit_amount": 500
}
],
"shipping": {
"address": {
"street": "Avenida Brigadeiro Faria Lima",
"number": "1384",
"complement": "apto 12",
"locality": "Pinheiros",
"city": "São Paulo",
"region_code": "SP",
"country": "BRA",
"postal_code": "01452002"
}
},
"charges": [
{
"id": "CHAR_3DED16B7-BD4C-4187-945D-26D165719B86",
"reference_id": "referencia da cobranca",
"status": "PAID",
"created_at": "2026-08-04T17:27:25.124-03:00",
"paid_at": "2026-08-04T17:32:26.846-03:00",
"description": "descricao da cobranca",
"amount": {
"value": 10534,
"currency": "BRL",
"summary": {
"total": 10534,
"paid": 10534,
"refunded": 0,
"incremented": 0
}
},
"payment_response": {
"code": "20000",
"message": "SUCESSO"
},
"payment_method": {
"type": "PIX",
"pix": {
"expiration_date": "2026-08-05T17:27:00.000-03:00",
"end_to_end_id": "b3f3a9f643d94bc699076f547fdec740",
"holder": {
"name": "API-PIX Payer Mock",
"tax_id": "***931180**"
}
}
},
"links": [
{
"rel": "SELF",
"href": "https://sandbox.api.pagseguro.com/charges/CHAR_3DED16B7-BD4C-4187-945D-26D165719B86",
"media": "application/json",
"type": "GET"
},
{
"rel": "QRCODE.PNG",
"href": "https://sandbox.api.pagseguro.com/qrcode/QRCO_6B445A9B-E003-40DC-A16D-B86B1AE4F768/png",
"media": "image/png",
"type": "GET"
},
{
"rel": "QRCODE.BASE64",
"href": "https://sandbox.api.pagseguro.com/qrcode/QRCO_6B445A9B-E003-40DC-A16D-B86B1AE4F768/base64",
"media": "text/plain",
"type": "GET"
},
{
"rel": "CHARGE.CANCEL",
"href": "https://sandbox.api.pagseguro.com/charges/CHAR_3DED16B7-BD4C-4187-945D-26D165719B86/cancel",
"media": "application/json",
"type": "POST"
}
],
"metadata": {
"ps_order_id": "ORDE_3B3C39C2-9125-4923-918C-4876FBA97269"
},
"qr_code": {
"id": "QRCO_6B445A9B-E003-40DC-A16D-B86B1AE4F768",
"text": "00020101021226850014br.gov.bcb.pix2563api-h.pagseguro.com/pix/v2/6B445A9B-E003-40DC-A16D-B86B1AE4F7685204899953039865802BR5921PagSeguro Internet SA6009Sao Paulo62070503***6304FD25"
}
}
],
"notification_urls": [
"https://meusite.com/notificacoes"
],
"links": [
{
"rel": "SELF",
"href": "https://sandbox.api.pagseguro.com/orders/ORDE_3B3C39C2-9125-4923-918C-4876FBA97269",
"media": "application/json",
"type": "GET"
},
{
"rel": "PAY",
"href": "https://sandbox.api.pagseguro.com/orders/ORDE_3B3C39C2-9125-4923-918C-4876FBA97269/pay",
"media": "application/json",
"type": "POST"
}
]
}
Obtendo o QR Code para pagamento
Ao criar um pedido que contenha uma cobrança com QR Code Pix, o PagBank disponibiliza duas formas para que o pagador realize o pagamento:
- Código PIX Copia e Cola
- Imagem do QR Code
Essas informações são retornadas na resposta do endpoint Criar pedido: o identificador e o texto do QR Code no objeto charges.qr_code, e as URLs de acesso no parâmetro charges.links.
Código Pix Copia e Cola
O campo rel = QRCODE.BASE64 fornece a URL do código de texto correspondente ao QR Code, que pode ser utilizado pelo pagador para copiar e colar o código PIX em um aplicativo compatível. Esse código também é retornado diretamente no campo charges.qr_code.text.
Imagem do QR Code
O campo rel = QRCODE.PNG fornece a URL da imagem do QR Code, permitindo sua exibição para leitura por aplicativos bancários e demais instituições que suportam pagamentos via PIX.
Realizando o pagamento
Após a criação do pedido, o comprador poderá efetuar o pagamento utilizando:
- Aplicativo do PagBank.
- Aplicativos de bancos e instituições financeiras que suportem pagamentos PIX.
Quando o pagamento é confirmado, o status da cobrança é atualizado para PAID. Para acompanhar essa mudança de status, cadastre uma URL de notificação no parâmetro notification_urls. Saiba mais em Webhooks ou consulte o pedido por meio do endpoint Consultar pedido.