0.1.1 • Published 9 months ago

integracao-front v0.1.1

Weekly downloads
-
License
ISC
Repository
github
Last release
9 months ago

Componente de integração com o PagBank

npm version Build Status Coverage Status

Instalação

Para instalar este pacote no seu projeto, use o npm:

# Usando npm
npm install nome-do-componente

índice

Sobre o componente

Este é um componente que tem por objetivo facilitar a implementação pagamentos via pix, cartão de crédito e boleto em aplicações utilizando como principal integrador os serviços de API do PagBank.

Informações cruciais para o público que irá usar esse componente

É de suma importância que você usuário tenha ciência que deverá modificar os returns no cartão de crédito, boleto e pix, de modo a fazer o front-end da maneira que você preferir.

Primeiros passos

  • Crie sua conta no Portal do Desenvolvedor da PagBank para ter uma visão geral de tudo que está acontecendo relativo a sua aplicação local ou em ambiente de produção.

Sua conta será importante pois será necessário ter acesso ao seu token para prosseguir com o uso do nosso componente.

Como obter sua chave de acesso em Sandbox (Ambiente local)

  • Acesse sua contade de Sandbox;
  • Localize o menu Perfis de Integração;
  • Clique em Vendedor. O token de sandbox estará disponível na seção Credenciais.

Como obter sua chave de acesso em Produção

  • Acesse a sua conta PagSeguro;
  • No menu lateral, selecione Venda online;
  • Vá na opção Integrações;
  • E pressione o botão Gerar Token.

Caso você já tenha gerado o token anteriormente, ele será enviado ao seu e-mail de cadastro por segurança. Nesse caso, basta pressionar Enviar por e-mail. Se preferir, você também pode gerar um novo token, mas importante: nesse caso, o token antigo deixará de funcionar.

Inserindo o token no componente

Para que você consiga usufruir plenamente esse componente, é necessário acessar .env.local na raiz do projeto e inserir seu token.

alt text

Para o uso deste componente recomendamos fortemente o estudo da documentação do PagBank Developer, e em especial, a API Pedidos que usamos extensamente.

Entendendo sobre os componentes pix, cartão crédito e boleto

Cartão de Crédito

O método de pagamento via cartão de crédito é o que envolve mais etapas até a sua finalização.

Para realizar o pagamento com cartão de crédito, é necessário fazer a criptografia de tal cartão.

O PagBank disponibiliza um SDK (src/pages/cartao-de-credito/index.tsx), dessa forma, a criptografia dos dados sensíveis do Cartão de Crédito é feita diretamente no navegador, reduzindo o seu escopo PCI. Tal SDK não requer chamadas ao servidor, ou seja, a criptografia é feita localmente com uma chave pública e o algoritmo RSA.

Legenda

A função que realiza a criptografia fornece uma string que pode ser descriptografada usando a chave privada, a qual apenas o PagBank tem acesso.

Abaixo mostraremos o fluxo e por seguinte explicaremos o mesmo.

alt text

Do componente para obter a chave pública, fazemos uma requisição específica para o PagBank através de src/pages/cartao-de-credito/index.tsx.

alt text

Após recebermos a resposta dessa requisição, temos acesso a chave pública que por sua vez nos permite fazer a criptografia do cartão através do SDK. O response vem no formato a seguir, por exemplo:

{
  "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr+ZqgD892U9/HXsa7XqBZUayPquAfS8CPIzdBOtTQCIwrLn2FxI83Clcg55W8gkFSOS6rWNbG5qFZWMll6yl02HtunalHmUlRUL66YeGXdMDC2PuRcmZbGO5a/2tbVppW6mfSWG3NPRpgwIDAQAB",
  "created_at": 1577836800000
}

Em nosso componente de cartão, a forma como inserimos a chave pública se dá da seguinte maneira em src/pages/cartao-de-credito/index.tsx

alt text

Por fim, com o cartão criptografado, fazemos a criação de ordem através do handleCreateOrder() que se encontra em src/pages/cartao-de-credito/index.tsx. Dentro do handleCreateOrder() temos o requestBody que é utilizado para inserir os dados do pedido.

alt text

RequestBody

No handleCreateOrder(), temos que inserir o requestBody, algo que é obrigatório para as requisições de criação de pedidos. O PagBank tem um padrão para os requests, em nosso componente optamos por criar interfaces para facilitar o uso. Abaixo segue um exemplo de requestBody para os pedidos com pagamento via cartão de crédito:

{
    "reference_id": "ex-00001",
    "customer": {
        "name": "Jose da Silva",
        "email": "email@test.com",
        "tax_id": "12345678909",
        "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": "CREDIT_CARD",
                "installments": 1,
                "capture": true,
                "card": {
                    "encrypted":"V++53ir0qvoK/rUSzNjCqP8Hz9ZTa+HohR779n63CV+NvCeYj4J4lQevL4NKN7Di3BxKQGqfQW5cfS7/4rHw4w8URuOV/j/mGau2GXxkKQ6/szJ6BQr//C4e4XgfCHDwcONQhuPDHMdOB1C+4lzyBbsPJUZ/8TUQrxhMMiMFjwGeg62uf7cUqdFjp+Q5dqJXwhLgH3d1EoX+JKStBLqVzF0lW3gHtFOyfvFhuxxBgB0xrzTKfbTqnL5aSYBoGXRFM0gLodMm6knx7bW+syThxyQffnaigCwj2aNohsu+fuXII+3WnlgrHQxaBx3ChRuWKy+loV2L2USiGulp/bPEcg==",
                    "store": false
                },
                "holder": {
                  "name": "Jose da Silva",
                  "tax_id": "65544332211"
                }
            }
        }
    ]
}

Nessa etapa do requestBody, após entender seu fluxo e como setar cada campo, é sugerido para os usuários que utilizarem este componente que insiram sua lógica para que preencham tais requestBody, é importante frizar da importância de fazer uma requisição por item.

Caso existam muitos pedidos, sugerimos que criem uma fila desses pedidos e processem um por vez.

ResponseBody

Segundo a documentação do PagBank, existem dois tipos de respostas para cartões:

  • Autorização bem-sucedida. Retorna status AUTHORIZED ou PAID.
  • Autorização negada. Retorna status DECLINED.

Essas respostas você pode acessar através da váriavel data no componente de cartão de crédito.

Aqui está um exemplo: 

{
    "id": "ORDE_1E38BD2E-F2CC-4D9C-9727-787CDFBCA7CE",
    "reference_id": "ex-00001",
    "created_at": "2023-02-08T15:15:11.408-03:00",
    "customer": {
        "name": "Jose da Silva",
        "email": "email@test.com",
        "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_67FC568B-00D8-431D-B2E7-755E3E6C66A0",
            "reference_id": "referencia da cobranca",
            "status": "PAID",
            "created_at": "2023-02-08T15:15:11.881-03:00",
            "paid_at": "2023-02-08T15:15:12.000-03:00",
            "description": "descricao da cobranca",
            "amount": {
                "value": 500,
                "currency": "BRL",
                "summary": {
                    "total": 500,
                    "paid": 500,
                    "refunded": 0
                }
            },
            "payment_response": {
                "code": "20000",
                "message": "SUCESSO",
                "reference": "032416400102"
            },
            "payment_method": {
                "type": "CREDIT_CARD",
                "installments": 1,
                "capture": true,
                "card": {
                    "brand": "visa",
                    "first_digits": "411111",
                    "last_digits": "1111",
                    "exp_month": "12",
                    "exp_year": "2026",
                    "holder": {
                        "name": "Joãozinho da Silva",
                      	"tax_id": "65544332211"
                    },
                    "store": false
                },
                "soft_descriptor": "IntegracaoPagsegu"
            },
            "links": [
                {
                    "rel": "SELF",
                    "href": "https://sandbox.api.pagseguro.com/charges/CHAR_67FC568B-00D8-431D-B2E7-755E3E6C66A0",
                    "media": "application/json",
                    "type": "GET"
                },
                {
                    "rel": "CHARGE.CANCEL",
                    "href": "https://sandbox.api.pagseguro.com/charges/CHAR_67FC568B-00D8-431D-B2E7-755E3E6C66A0/cancel",
                    "media": "application/json",
                    "type": "POST"
                }
            ]
        }
    ],
    "notification_urls": [
        "https://meusite.com/notificacoes"
    ],
    "links": [
        {
            "rel": "SELF",
            "href": "https://sandbox.api.pagseguro.com/orders/ORDE_1E38BD2E-F2CC-4D9C-9727-787CDFBCA7CE",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "PAY",
            "href": "https://sandbox.api.pagseguro.com/orders/ORDE_1E38BD2E-F2CC-4D9C-9727-787CDFBCA7CE/pay",
            "media": "application/json",
            "type": "POST"
        }
    ]
}

Cartões de teste

Para finalidades de testes, o PagBank fornece alguns cartões de teste, com bandeiras e respostas já definidas Cartões de Teste.

Caso de uso

Em nosso componente, por padrão, disponibilizamos um caso de uso que pode ser visto no return do componente cartão de crédito.

alt text

Pix

Para o pix, é muito mais simples, basta certirficar-se que o token está inserido de maneira adequada no .env.local e colocar de forma correta o requestBody.

alt text

RequestBody

{
  "reference_id": "ex-00001",
  "customer": {
    "name": "Jose da Silva",
    "email": "email@test.com",
    "tax_id": "12345678909",
    "phones": [
      {
        "country": "55",
        "area": "11",
        "number": "999999999",
        "type": "MOBILE"
      }
    ]
  },
  "items": [
    {
      "name": "nome do item",
      "quantity": 1,
      "unit_amount": 500
    }
  ],
  "qr_codes": [
    {
      "amount": {
        "value": 500
      },
      "expiration_date": "2021-08-29T20:15:59-03:00"
    }
  ],
  "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"
  ]
}

ResponseBody

{
  "id": "ORDE_9BBD677F-863E-4D46-BAAF-2EECEE49FF31",
  "reference_id": "ex-00001",
  "created_at": "2021-01-19T09:30:12.197-03:00",
  "customer": {
    "name": "José da Silva",
    "email": "jose@email.com",
    "tax_id": "12345678901",
    "phones": [
      {
        "country": "55",
        "area": "11",
        "number": "999999999",
        "type": "MOBILE"
      }
    ]
  },
  "items": [
    {
      "reference_id": "referencia do item",
      "name": "nome do item",
      "quantity": "1",
      "unit_amount": "100"
    }
  ],
  "amount": {
    "currency": "BRL",
    "additional": 100,
    "discount": 100
  },
  "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"
    }
  },
  "qr_codes": [
    {
      "id": "QRCO_9E13BFE1-35C3-4DFD-B499-9B110AC0E1BA",
      "expiration_date": "2021-08-29T20:15:59-03:00",
      "amount": {
        "value": 100
      },
      "text": "00020101021226830014br.gov.bcb.pix2561api.pagseguro.com/pix/v2/9E13BFE1-35C3-4DFD-B499-9B110AC0E1BA27600016BR.COM.PAGSEGURO01369E13BFE1-35C3-4DFD-B499-9B110AC0E1BA52045697530398654041.005802BR5925Leticia Oliveira Porto La6007Barueri62070503***6304658F",
      "links": [
        {
          "rel": "QRCODE.PNG",
          "href": "https://api.pagseguro.com/qrcode/QRCO_9E13BFE1-35C3-4DFD-B499-9B110AC0E1BA/png",
          "media": "image/png",
          "type": "GET"
        },
        {
          "rel": "QRCODE.BASE64",
          "href": "https://api.pagseguro.com/qrcode/QRCO_9E13BFE1-35C3-4DFD-B499-9B110AC0E1BA/base64",
          "media": "text/plain",
          "type": "GET"
        }
      ]
    }
  ],
  "charges": [],
  "links": [
    {
      "rel": "SELF",
      "href": "https://api.pagseguro.com/orders/ORDE_9BBD677F-863E-4D46-BAAF-2EECEE49FF31",
      "media": "application/json",
      "type": "GET"
    },
    {
      "rel": "PAY",
      "href": "https://api.pagseguro.com/orders/ORDE_9BBD677F-863E-4D46-BAAF-2EECEE49FF31/pay",
      "media": "application/json",
      "type": "POST"
    }
  ]
}

Caso de uso

Análogamente ao cartão de crédito, segue um exemplo de caso de uso no return do componente pix, para a criação e pagamento de um pedido fictício.

alt text

Boleto

De forma bem similar ao pix, no boleto devemos atentar apenas em preencher o requestBody da maneira adequada, assim como implementar a lógica de fila caso existam muitos pedidos nessa modalidade de pagamento, segue a estrutura:

alt text

RequestBody

Alguns parâmetros são obrigatórios quando criando um pedido utilizando Boleto. Uma lista é apresentada na tabela a seguir:

alt text

Aqui está um exemplo de request:

{
  "reference_id": "ex-00001",
  "customer": {
    "name": "Jose da Silva",
    "email": "email@test.com",
    "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": "jose@email.com",
            "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"
            }
          }
        }
      }
    }
  ]
}

ResponseBody

{
  "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@test.com",
    "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": "jose@email.com",
            "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"
    }
  ]
}

Caso de uso

Em nosso componente padrão de boleto, você poderá encontrar no return nosso caso de uso padrão.

alttext

pagbank
@emotion/react@emotion/styled@mui/materialintegracao-frontnextreactreact-domreact-toastify
package-pagbankintegracao-front
0.1.1

9 months ago

0.1.0

9 months ago