Criar e pagar pedido com Boleto

Esse guia descreve como criar e pagar um pedido utilizando Boleto como meio de pagamento. Esse método de pagamento impõe um valor mínimo de R$0,20 para cada transação.

Para a criação e pagamento do pedido utilizando Boleto, você irá utilizar o endpoint Criar pedido. Alguns parâmetros são obrigatórios quando criando um pedido utilizando Boleto. Uma lista é apresentada na tabela a seguir:

Parâmetro	Descrição
`charges.payment_method.type`	Define o tipo do método de pagamento como Boleto. Você deve, obrigatóriamente, atribuir o valor `BOLETO`.
`charges.payment_method.boleto.due_date`	Data de expiração do Boleto.
`charges.payment_method.boleto.instruction_lines.line_1`	Instruções para o processamento do Boleto.
`charges.payment_method.boleto.instruction_lines.line_2`	Instruções para o processamento do Boleto.
`charges.payment_method.boleto.holder.name`	Nome do cliente realizando o pedido.
`charges.payment_method.boleto.holder.tax_id`	Documento do cliente.
`charges.payment_method.boleto.holder.email`	E-mail do cliente.
`charges.payment_method.boleto.holder.address`	Objeto com os dados do endereço do cliente.

Abaixo você encontra um exemplo de requisição e reposta feitas ao o endpoint Criar pedido utilizando Boleto como meio de pagamento.

curl --location --request POST 'https: //sandbox.api.pagseguro.com/orders' \
--header 'Authorization: Bearer {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference_id": "ex-00001",
  "customer": {
    "name": "Jose da Silva",
    "email": "[email protected]",
    "tax_id": "12345679891",
    "phones": [
      {
        "country": "55",
        "area": "11",
        "number": "999999999",
        "type": "MOBILE"
      }
    ]
  },
  "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"
    }
  },
  "notification_urls": [
    "https://meusite.com/notificacoes"
  ],
  "charges": [
    {
      "reference_id": "referencia da cobranca",
      "description": "descricao da cobranca",
      "amount": {
        "value": 500,
        "currency": "BRL"
      },
      "payment_method": {
        "type": "BOLETO",
        "boleto": {
          "due_date": "2023-06-20",
          "instruction_lines": {
            "line_1": "Pagamento processado para DESC Fatura",
            "line_2": "Via PagSeguro"
          },
          "holder": {
            "name": "Jose da Silva",
            "tax_id": "12345679891",
            "email": "[email protected]",
            "address": {
              "country": "Brasil",
              "region": "São Paulo",
              "region_code": "SP",
              "city": "Sao Paulo",
              "postal_code": "01452002",
              "street": "Avenida Brigadeiro Faria Lima",
              "number": "1384",
              "locality": "Pinheiros"
            }
          }
        }
      }
    }
  ]
}'

{
  "id": "ORDE_E8A44EB1-89BC-4261-9004-739A09B53A8C",
  "reference_id": "ex-00001",
  "created_at": "2023-02-08T15:10:15.763-03:00",
  "customer": {
    "name": "Jose da Silva",
    "email": "[email protected]",
    "tax_id": "12345679891",
    "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_BF10AE3B-68D2-430D-AED6-0D5E2C7E180E",
      "reference_id": "referencia da cobranca",
      "status": "WAITING",
      "created_at": "2023-02-08T15:10:15.901-03:00",
      "description": "descricao da cobranca",
      "amount": {
        "value": 500,
        "currency": "BRL",
        "summary": {
          "total": 500,
          "paid": 0,
          "refunded": 0
        }
      },
      "payment_response": {
        "code": "20000",
        "message": "SUCESSO"
      },
      "payment_method": {
        "type": "BOLETO",
        "boleto": {
          "id": "0E243EE1-736A-45EF-B153-CC9B9F0A838F",
          "barcode": "03399853012970000024227020901016278150000015630",
          "formatted_barcode": "03399.85301 29700.000242 27020.901016 2 78150000015630",
          "due_date": "2023-06-20",
          "instruction_lines": {
            "line_1": "Pagamento processado para DESC Fatura",
            "line_2": "Via PagSeguro"
          },
          "holder": {
            "name": "Jose da Silva",
            "tax_id": "12345679891",
            "email": "[email protected]",
            "address": {
              "region": "São Paulo",
              "city": "Sao Paulo",
              "postal_code": "01452002",
              "street": "Avenida Brigadeiro Faria Lima",
              "number": "1384",
              "locality": "Pinheiros",
              "country": "Brasil",
              "region_code": "SP"
            }
          }
        }
      },
      "links": [
        {
          "rel": "SELF",
          "href": "https://boleto.sandbox.pagseguro.com.br/0e243ee1-736a-45ef-b153-cc9b9f0a838f.pdf",
          "media": "application/pdf",
          "type": "GET"
        },
        {
          "rel": "SELF",
          "href": "https://boleto.sandbox.pagseguro.com.br/0e243ee1-736a-45ef-b153-cc9b9f0a838f.png",
          "media": "image/png",
          "type": "GET"
        },
        {
          "rel": "SELF",
          "href": "https://sandbox.api.pagseguro.com/charges/CHAR_BF10AE3B-68D2-430D-AED6-0D5E2C7E180E",
          "media": "application/json",
          "type": "GET"
        }
      ]
    }
  ],
  "notification_urls": [
    "https://meusite.com/notificacoes"
  ],
  "links": [
    {
      "rel": "SELF",
      "href": "https://sandbox.api.pagseguro.com/orders/ORDE_E8A44EB1-89BC-4261-9004-739A09B53A8C",
      "media": "application/json",
      "type": "GET"
    },
    {
      "rel": "PAY",
      "href": "https://sandbox.api.pagseguro.com/orders/ORDE_E8A44EB1-89BC-4261-9004-739A09B53A8C/pay",
      "media": "application/json",
      "type": "POST"
    }
  ]
}

Ao emitir um Boleto com o PagBank serão disponibilizadas duas formas para que o usuário possa consumi-lo, através de linha digitável e link com Boleto para impressão. Essas informações estão presentes na resposta do endpoint Criar pedido. Os números do código de barres podem ser acessados através de um dos parâmetro charges.payment_method.boleto.barcode ou charges.payment_method.boleto.formatted_barcode. Já a versão para impressão pode ser acessadas através do parâmetro charges.links que disponibiliza um array de objetos contendo a versão em formato PDF, imagem e o objeto JSON.

É importante destacar que ao criar o pedido com Boleto, o estatus disponível através do parâmetro charges.status assumirá o valor WAITING, indicando que aguarda o pagamento pelo usuário.

Orientação para teste no ambiente sandbox

Ao criar um pagamento com Boleto no ambiente sandbox, é possível simular dois status distintos. O primeiro é relacionado com o cenário onde o Boleto é pago já no segundo, o Boleto não é pago e acaba expirando. Essas duas situações são cobertas pelo Simulador.