> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.
# Formas de pagamento
> Declare as formas de pagamento que sua conta cobra, e os dados que cada uma precisa antes que uma loja possa usá-la.
O Fire não vem com um catálogo de formas de pagamento. Sua conta declara as próprias, um conjunto por país — e, mais importante ainda, declara **o que cada forma precisa para cobrar e quem deve preencher isso**.
Essa segunda parte é o que esta tela realmente faz. Um processador de cartão precisa de um merchant ID do banco, um código por loja e o IP do pinpad ao lado de cada quiosque. Essas três coisas são preenchidas por três pessoas diferentes em três momentos diferentes. Se a forma não disser isso, a tela da loja ou pede dados que ninguém tem ou nunca pede o que importa — e o pagamento falha no balcão, com um cliente esperando.
Navegue até **Operação → Formas de pagamento**.
***
## A versão curta
**1. O código é um contrato, e é permanente.** Os canais referenciam a forma pelo seu `code`, então uma vez que você salva não pode mais alterá-lo. O nome você pode renomear quando quiser.
**2. Cada forma declara seus próprios campos, e em qual nível cada um é preenchido.** *Conta*, *Loja* ou *Terminal*. Essa decisão é o que a tela da loja lê para saber o que pedir.
**3. Desligar uma forma é reversível. Excluí-la não é.** *Ativo* desligado para de cobrar em todo lugar e mantém tudo. Excluir não pode ser desfeito: criar a forma de novo começa com a configuração vazia.
***
## O caminho simples
Se você só aceita dinheiro, isso leva um minuto.
1. **Nova forma de pagamento**.
2. **Nome**: `Dinheiro`. O **Código** se preenche sozinho como `dinheiro` enquanto você digita.
3. Marque **Esta forma não cobra com cartão**.
4. **Salvar**.
Sem campos de configuração, sem bandeiras de cartão, nada mais. A forma agora existe e a tela de [configuração por loja](/pt/manuals/payments/store-configuration) pode ativá-la onde você cobra em dinheiro.
Se dinheiro é tudo o que você aceita, terminou. Tudo abaixo é para o dia em que um processador aparecer.
***
## O código é o contrato
Enquanto você digita o nome, o Fire deriva o **Código** dele: minúsculo, sem acentos, sem espaços, underscores no lugar. Você pode sobrescrever — um provedor pode exigir uma grafia exata — mas no momento em que você salva, **o código fica travado**.
Isso é proposital. O código é o identificador que os canais usam para se referir à forma: quiosques, o POS, agregadores. Renomear *Datafast* para *Datafast EC* muda o que o cliente lê na tela e nada mais. O código continua `datafast` e tudo downstream continua funcionando.
Duas consequências que vale saber antes de salvar:
* **Um erro de digitação no código é permanente.** Ter `datafst` em produção significa criar uma nova forma e reconfigurar cada loja que usava a antiga.
* **O código é único por país.** Tentar reusar um traz *"Já existe uma forma de pagamento com esse código neste país"*. O mesmo código no Equador e no Brasil está bem — são formas separadas.
***
## Campos de configuração: o que a forma precisa, e quem preenche
Esta é a seção que se paga sozinha. Sob **Campos de configuração** você declara, uma linha por pedaço de dado, o que esta forma precisa para cobrar.
Cada campo tem:
| Campo | Para que serve |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **Rótulo** | O que a pessoa que está preenchendo lê. *"Merchant ID"*. |
| **Key** | O que viaja para o canal. Derivado do rótulo, editável — um provedor pode exigir um nome exato. Minúsculo, números e underscore. |
| **Preenchido em** | O nível. Este é o importante — veja abaixo. |
| **Texto de ajuda** | Opcional. Onde obter o valor: *"O banco te dá este."* |
| **Obrigatório** | Ligado por padrão. Sem isso, a combinação aparece como **Falta configurar**. |
| **Secreto** | Esconde o valor na tela enquanto é digitado. |
### Os três níveis
**Preenchido em** decide quem é perguntado pelo valor, e onde:
| Nível | Preenchido uma vez por | Exemplo típico | Onde é inserido |
| ------------ | ---------------------- | ------------------------- | ------------------------------------------------------- |
| **Conta** | Toda a conta | A API key do processador | Configuração por loja, seção *Configuração da conta* |
| **Loja** | Cada loja | O código da loja no banco | Configuração por loja, seção *Configuração da loja* |
| **Terminal** | Cada dispositivo | O IP do pinpad | Configuração por loja ou no próprio detalhe do quiosque |
Na hora de cobrar os três níveis são mesclados e **o mais específico ganha**: terminal sobre loja, loja sobre conta. É isso que permite que um quiosque tenha seu próprio IP de pinpad sem apagar o da loja.
**Uma key repetida quebra a mesclagem silenciosamente.** Dois campos com a mesma **Key** significa que um sobrescreve o outro e nenhum erro é levantado na hora de cobrar. O Fire não deixa você salvar — a key duplicada fica vermelha e **Salvar** continua desabilitado — mas a borda é o único aviso que você recebe, então vale lê-la pelo que é.
***
## Bandeiras
Uma nova forma nasce aceitando **todas as quatro** bandeiras: Visa, Mastercard, Amex, Discover. Você desmarca as que ela não aceita. Assim o caso comum não precisa de trabalho e a exceção é um clique.
Para uma forma que não tem nada a ver com cartões — dinheiro, transferência bancária, carteira — marque **Esta forma não cobra com cartão** e a grade desaparece. Não há uma flag separada "é um cartão?": uma lista vazia de bandeiras já diz isso.
***
## O logo
O logo é o que o cliente vê no checkout em canais que o renderizam. Você o carrega **abrindo uma forma que já existe** — o campo não está lá enquanto você está criando.
WebP, JPG, PNG ou SVG, até 1 MB, idealmente 744×744 px. Qualquer coisa que não seja SVG é convertida para WebP no caminho; SVGs são mantidos como estão porque são vetoriais e convertê-los custaria qualidade.
***
## Desligar não é excluir
Duas ações diferentes que as pessoas confundem sob pressão, quando um processador acabou de cair.
**Desmarcar Ativo** para essa forma de cobrar em todo lugar, e mantém a configuração de cada loja exatamente como estava. Quando você marca de novo, o Fire traz de volta **só o que a desativação desligou** — qualquer coisa que já estava pausada manualmente continua pausada. É a reversível, e é a certa para uma interrupção.
**Excluir** remove a forma da lista para sempre.
**Excluir não pode ser desfeito.** O diálogo diz isso: criar a forma de novo começa com a configuração vazia. É uma forma nova, com uma identidade nova — os valores carregados em suas lojas, as credenciais dos terminais, nada disso volta, mesmo se você reusar o mesmo código. Se o que você quer é uma pausa, use **Ativo** desligado.
***
## Receitas: como lidar com casos do mundo real
1. **Nova forma de pagamento** → Nome `Dinheiro`.
2. Marque **Esta forma não cobra com cartão**.
3. **Salvar**.
Sem campos de configuração: não há nada para preencher para que dinheiro funcione. Em [configuração por loja](/pt/manuals/payments/store-configuration) vai direto para **Pronto para cobrar** no momento em que você habilita.
O banco te dá um merchant ID, cada loja tem seu próprio código e cada quiosque tem seu próprio pinpad.
1. **Nova forma de pagamento** → Nome `Datafast`, código `datafast`.
2. Deixe marcadas as bandeiras que o processador aceita.
3. **Adicionar campo** três vezes:
* `merchant_id` — **Preenchido em** *Conta*, **Obrigatório**
* `store_code` — **Preenchido em** *Loja*, **Obrigatório**
* `pinpad_ip` — **Preenchido em** *Terminal*, **Obrigatório**, texto de ajuda *"O IP do pinpad neste quiosque."*
4. **Salvar**.
Daqui em diante a tela da loja pede exatamente esses três, cada um no seu próprio nível, e ninguém precisa lembrar qual é qual.
Um gateway que autentica uma vez para toda a conta e não precisa de nada por loja.
1. Crie a forma com seu nome e bandeiras.
2. **Adicionar campo** duas vezes, ambos **Preenchido em** *Conta*:
* `api_key` — **Obrigatório**, **Secreto**
* `api_password` — **Secreto**
3. **Salvar**.
Carregar esses dois valores uma vez na tela da loja deixa cada loja que oferece a forma pronta.
1. Abra a forma.
2. Desmarque **Ativo**.
3. **Salvar**.
Para de cobrar em cada loja, canal e fulfillment de uma vez, e cada configuração fica no lugar. Quando o provedor voltar, marque **Ativo** de novo: o que a desativação desligou volta sozinho.
O que quer que alguém tenha pausado manualmente antes da interrupção continua pausado. Reativar não desfaz decisões humanas.
Se o novo provedor precisa de dados diferentes mas você prefere não tocar em cada canal que referencia o código:
1. Abra a forma e edite seus **Campos de configuração** — adicione o que o novo provedor pede, remova o que não usa mais.
2. Renomeie se o nome voltado ao cliente mudar.
3. Recarregue os valores em [configuração por loja](/pt/manuals/payments/store-configuration).
O código não muda, então nada downstream precisa ser tocado. Excluir a forma e criar outra com o mesmo código também funcionaria, mas você perderia cada valor configurado.
***
## Uma forma, seguida de ponta a ponta
`datafast`, com seus quatro campos, em uma rede com duas lojas e três quiosques:
| Campo | Preenchido em | Vezes que é inserido | Quem insere |
| -------------- | --------------------- | -------------------- | -------------------------------------- |
| `merchant_id` | **Conta** | 1 | Quem configurou o contrato com o banco |
| `api_password` | **Conta** *(secreto)* | 1 | Mesma pessoa |
| `store_code` | **Loja** | 2 — um por loja | Quem abre cada loja |
| `pinpad_ip` | **Terminal** | 3 — um por quiosque | Quem instala o hardware |
Seis valores no total. Se todos os quatro tivessem sido declarados no nível **Loja**, a mesma configuração levaria oito, dois deles copiados e colados identicamente e um deles errado no dia em que alguém digitar errado. Se `pinpad_ip` tivesse sido declarado no nível **Conta**, os três quiosques compartilhariam um IP e dois deles nunca cobrariam.
**O nível não é formalidade: é quantas vezes alguém tem que digitar o valor, e quantas chances há de errar.**
***
## Erros que custam dinheiro
**Salvar com um erro de digitação no código.** Ele fica travado daquele momento em diante. A correção é uma nova forma mais reconfigurar cada loja que usava a antiga.
**Excluir em vez de desativar.** Excluir não pode ser desfeito e a configuração não volta com a forma. Para uma interrupção temporária, desmarque **Ativo**.
**Declarar um campo por dispositivo no nível Loja.** Todos os quiosques daquela loja acabam compartilhando um valor. Se é um IP de pinpad, só um deles cobra.
**Deixar Obrigatório desligado em um campo que realmente é obrigatório.** A combinação aparece como pronta na configuração por loja, a forma viaja para o quiosque com dados incompletos, e a falha aparece no balcão em vez de na tela onde poderia ter sido corrigida.
***
## Glossário
| Termo | O que significa |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| **Código** | O identificador estável da forma. Os canais o referenciam. Travado após salvar. |
| **Campo de configuração** | Um pedaço de dado que a forma precisa para cobrar. Tem uma key, um nível e se é obrigatório. |
| **Preenchido em** | O nível no qual o valor de um campo é inserido: *Conta*, *Loja* ou *Terminal*. |
| **Key** | O nome do campo que viaja para o canal. Não necessariamente o mesmo que o rótulo. |
| **Secreto** | Um campo cujo valor é escondido na tela enquanto é digitado. |
| **Ativo** | Se a forma cobra. Desligado pausa em todo lugar sem perder nada. |
| **Bandeiras** | As bandeiras que a forma aceita. Vazia significa que não é uma forma de cartão. |
***
## Perguntas frequentes
Não. Ele fica travado porque os canais já o referenciam. O que você pode alterar é o **Nome**, quantas vezes quiser — é isso que o cliente vê.
Não do app. Criá-la de novo — mesmo com o mesmo código — produz uma nova forma com uma configuração vazia: os valores carregados em suas lojas e terminais não são reconectados. Se você precisava de uma pausa, a ação reversível era desmarcar **Ativo**.
Existir aqui não é o mesmo que ser oferecida lá. A disponibilidade é decidida por loja, canal e fulfillment em [configuração por loja](/pt/manuals/payments/store-configuration). Verifique também que a forma está **Ativa** e que seu país corresponde ao da loja.
Esconde o valor na tela enquanto é digitado, do jeito que um campo de senha faz. É uma ajuda de exibição para quem está carregando, não uma garantia de criptografia — trate como tal quando decidir o que colocar ali.
Não. Uma forma pertence a uma conta **e um país**. A tela sempre mostra as formas para o país selecionado no cabeçalho, que é por isso que o mesmo código pode existir em dois países como duas formas separadas.
Ainda não. A lista é ordenada alfabeticamente por nome. Se a ordem importa para você, o nome é a alavanca que você tem.
***
## O que vem por aí
Coisas que esta tela **não** faz hoje, então ninguém as promete:
* **Sem restauração de uma forma excluída.** Excluir é final, como o diálogo diz.
* **Sem duplicar uma forma**, e sem copiar formas de um país para outro.
* **Sem ordenação manual** da lista.
* **Sem tipos de dados em campos de configuração**: tudo é capturado como texto. Não há número, booleano, dropdown ou validação de formato.
* **Bandeiras são as quatro listadas.** Bandeiras locais não podem ser adicionadas.
* **O logo é carregado editando**, nunca enquanto cria a forma.
* **Mudanças aqui não dizem se cada quiosque as recebeu.** Se um quiosque estava offline quando você renomeou ou desativou uma forma, o aviso aparece em [configuração por loja](/pt/manuals/payments/store-configuration), não aqui.