# Conceitos

Conceitos do PIX: cobranças imediatas (cob), com vencimento (cobv), PSPs e fluxo de pagamento.

## Termos utilizados

Abaixo uma lista com alguns termos utilizados e o seu significado:

| Termo | Significado simples |
|---|---|
| PSP | Provedor de Serviço de Pagamento. É o banco ou instituição financeira que processa o Pix (ex: Banco Inter, Itaú, Bradesco). |
| Chave Pix | Identificador cadastrado no banco (CPF, e-mail, celular ou chave aleatória) usado para receber pagamentos. |
| QR Code Dinâmico | QR Code de uso único, gerado para uma cobrança específica, com informações detalhadas do pagamento. |
| QR Code Estático | QR Code que pode ser reutilizado várias vezes, ideal para doações, caixas de loja, etc. |
| Pix Copia e Cola | String de texto que representa o QR Code. O cliente copia e cola no aplicativo do banco para pagar. |
| txid | Código de identificação da cobrança gerado pelo recebedor (26 a 35 caracteres). |
| endToEndId | Identificador único de uma transação Pix, gerado pelo Banco Central quando o pagamento é confirmado. |
| mTLS | Protocolo de segurança que exige um certificado digital para o sistema se comunicar com o banco. |
| OAuth2 / Scope | Mecanismo de permissão. O scope define o que cada token de acesso pode fazer (ler, escrever, cancelar). |
| Pré-Produção | Ambiente de testes, igual homologação, mas utilizado em alguns PSP especificos. Nenhum dinheiro real é movimentado. |
| Sandbox / Homologação  | Ambiente de testes. Nenhum dinheiro real é movimentado. |
| Produção | Ambiente real. Pagamentos e devoluções movimentam dinheiro de verdade. |
| JWT / accessToken | "Senha temporária" que o seu sistema recebe após fazer login e deve usar em todas as chamadas seguintes. |
| COB | Cobrança Imediata. Pix com vencimento "para já". |
| COBV | Cobrança com Vencimento. Pix com data de vencimento futura, juros, multa e desconto. |
| clientId | É a chave pública que identifica a sua conta, é como se fosse o "usuário" para logar. |
| clientSecret | É a chave secreta que apenas o banco e você devem conhecer, é como se fosse a "senha" para logar. |
| certificado | Certificado digital, usado para identificar a empresa/pessoa fisica. |
| .PFX / .P12 | Arquivo de certificado único que contém certificado + chave privada. |
| .KEY | Arquivo de certificado que contém a chave privada. |
| .CRT | Arquivo de certificado que contém o certificado público. |
| Root | Certificado raiz da autoridade certificadora. |

## Quando usar o Pix estático, cobrança imediata e com vencimento?

É possível gerar um QrCode e "Copia e Cola" de três formas e para cada uma tem uma orientação para usar.

### Cobrança Imediata (cob)

**Quando usar**: venda no e-commerce, checkout de loja, cobrança por serviço.

**Características**:
- Tem uma data de expiração (ex: 1 hora, 24 horas), após isto não é possível pagar.
- Pode ser pago apenas uma vez.
- Mostra o valor exato, não há alteração deste valor.
- Mostra informações do devedor.
- Ideal para cobranças pontuais.

**Endpoint**: 
POST /cob

### Cobrança com Vencimento (cobV)

**Quando usar**: substituir boletos, faturas mensais, carnês, parcelamentos.

**Características**:
- Tem uma data de vencimento definida, é possível pagar após vencimento.
- Após o vencimento, pode aplicar juros, multa e descontos por antecipação.
- O valor pode mudar conforme a data de pagamento.
- Mostra informações do devedor.
- Ideal para cobranças que podem ser pagas após expiração/vencimento.

**Endpoint**: 
POST /cobv

### QR Code Estático

**Quando usar**: doações, caixas de loja física, cobranças sem identificação do cliente.

**Características**:
- Pode ser reutilizado infinitas vezes.
- Pode ter valor fixo ou deixar para o cliente digitar o valor.
- O valor não altera conforme data e não tem expiração/vencimento.
- Não gera "txid" nem identifica o pagador automaticamente.
- Não mostra informações do devedor.
- Ideal para cobranças onde não é um valor exato e não há necessidade de controle do pagamento.

**Endpoint**: 
POST /cob/generate-static-qrcode

## Principais campos utilizados

### idAccount - Identificador único da conta (UUID)

Para criar cobranças é necessário ter a conta cadastrada previamente.
Tendo isto em vista, antes de fazer uma requisição para criar uma cobrança ou até mesmo gerar o pix estático, crie uma conta na rota /user/account e utilize o *idAccount* retornado nas requisições.

### tpAmb - Ambiente

Geralmente é disponibilizado o ambiente de produção e homologação (ambiente de teste), mas em alguns PSP pode ser disponibilizado um ambiente de pré-produção, que seria um intermediário entre a homologação e produção.

Para o ambiente de **Produção** utilize o *tpAmb* com o **valor 1**, para Homologação o *tpAmb* com o **valor 0** e Pré-Produção o *tpAmb* com o **valor 2**.

> **Atenção:** Uma única conta não pode ser usado para os ambientes de produção e homologação ao mesmo tempo. Caso precise usar uma conta em produção e homologação, crie um cadastro para cada. No cadastro você define se esta conta é para produção, homologação ou pré-produção.

### resStatus — status oficial da cobrança no Banco Central

|Valor | Significado|
|---|---|
|ATIVA | Cobrança criada e aguardando pagamento.|
|CONCLUIDA | Pagamento confirmado.|
|REMOVIDA_PELO_USUARIO_RECEBEDOR | Você cancelou a cobrança.|
|REMOVIDA_PELO_PSP | O banco cancelou a cobrança.|

### keyTypePIX — tipos de chave Pix

|Valor | Descrição|
|---|---|
|NENHUMA | Sem chave configurada.|
|EMAIL | E-mail, ex: usuario@email.com|
|CPF | CPF (somente números)|
|CNPJ | CNPJ (somente números)|
|PHONE | Celular com DDI/DDD, ex: +5511999999999|
|ALEATORIA | Chave aleatória gerada pelo PSP|


## Scopes (permissões de acesso)

Os scopes definem o que é possível fazer. Quando você cadastra uma conta Pix (POST /user/account), deve informar quais scopes ela tem.
Dependendo dos scopes informados, você poderá ou não criar cobranças, consultar e etc.
Abaixo a lista dos principais scopes:

|Scope | Permissão | Para que serve|
|---|---|---|
|scCobWrite | Escrita | Criar, revisar e cancelar cobranças imediatas (COB).|
|scCobRead | Leitura | Consultar cobranças imediatas (COB).|
|scCobVWrite | Escrita | Criar, revisar e cancelar cobranças com vencimento (COBV).|
|scCobVRead | Leitura | Consultar cobranças com vencimento (COBV).|
|scPixWrite | Escrita | Solicitar devoluções.|
|scPixRead | Leitura | Consultar transações Pix.|
|scPayloadLocationWrite | Escrita | Criar e gerenciar payload locations.|
|scPayloadLocationRead | Leitura | Consultar payload locations.|

> **Dica:** Para a maioria dos casos será usado ["scCobWrite", "scCobRead", "scPixWrite", "scPixRead"], mas pode acontecer de ser orientado não definir scopes ou utilizar outros, portanto verifique a orientação com o suporte do seu PSP.


## Confirmar o pagamento

Ao realizar uma consulta do pagamento, matenha o parâmetro *forceUpdate* com o valor *true*, desta forma é atualizado em nossa base de dados o retorno deste pagamento.