# Apresentação
## Bem-vindo à Documentação GoPag
A **GoPag** é uma solução completa de pagamentos que simplifica a forma como o seu negócio recebe dinheiro. Seja para vender na loja física, no celular ou pela internet, a GoPag oferece tudo que é necessário em uma única plataforma.
## 🚀 O que é a GoPag?
A GoPag oferece várias formas de receber pagamentos:
### 💳 Para o seu Negócio
#### 📱 Tap to Pay - Seu Celular Vira Maquininha
Transforme seu celular Android ou iPhone em uma maquininha de cartão. Basta baixar o app e começar a receber pagamentos por aproximação, sem precisar comprar ou alugar equipamentos.
**Vantagens:**
* Sem mensalidade de maquininha
* Sem aluguel de equipamento
* Receba em 1 dia útil
* Aceita cartão de crédito e débito
#### 🔗 Links de Pagamento
Crie links para receber pagamentos e envie para seus clientes por WhatsApp, e-mail ou redes sociais. Perfeito para vendas online.
**Vantagens:**
* Crie links em segundos
* Envie pelo WhatsApp
* Acompanhe os pagamentos pelo celular
* Aceita cartão, boleto e PIX
#### 💻 Portal Web GoPag
Acesse o portal pelo computador para gerenciar tudo em um só lugar: vendas, cobranças, transferências e relatórios.
**O que fazer no Portal:**
* Ver todas as suas vendas
* Criar cobranças
* Acompanhar recebimentos
* Fazer transferências
* Baixar relatórios
#### 📲 Manuais de Maquininhas
Caso já possua uma maquininha GoPag (modelos S920 ou SMART), consulte nossos guias completos com todas as instruções de uso.
**Consulte os manuais:**
* Como ligar e configurar
* Como realizar vendas
* Como fazer parcelamento
* Como estornar vendas
* Como conectar Wi-Fi
* Como trocar bobina
#### 🔄 Cobranças Recorrentes
Automatize o recebimento de mensalidades e assinaturas. O sistema cobra automaticamente seus clientes todo mês.
**Ideal para:**
* Academias
* Escolas
* Assinaturas
* Serviços mensais
### 🔧 Para Desenvolvedores e Empresas de Tecnologia
Se sua empresa desenvolve sistemas (ERP, app, site), é possível integrar a GoPag ao seu produto e oferecer pagamentos para seus clientes.
**O que oferecemos:**
* Integração simples por meio de programação
* Tap to Pay dentro do seu sistema
* Divisão automática de valores (split)
* Cada cliente com sua própria conta
* Documentação técnica completa
## 💡 Para quem é a GoPag?
### 👤 Autônomos e Profissionais
* Barbeiros, cabeleireiros
* Dentistas, médicos
* Personal trainers
* Advogados, contadores
* Vendedores
### 🏪 Comércio
* Lojistas
* Restaurantes e lanchonetes
* Delivery
* Feiras e eventos
* Vendedores ambulantes
### 🏢 Empresas
* Empresas de software
* Franquias
* Marketplaces
* Prestadores de serviço
* Escolas e academias
## ✨ Por que escolher a GoPag?
### 💰 Transparência Total
* Taxas claras, sem pegadinhas
* Veja o custo antes de vender
* Sem taxas escondidas
* Receba em 1 dia útil
### 🛡️ Segurança
* Seus dados protegidos
* Transações seguras
* Criptografia em todos os pagamentos
### 📞 Suporte que Funciona
* Equipe pronta para ajudar
* WhatsApp: (62) 3602-4409
* Manuais completos
* Tutoriais passo a passo
## 💳 Cartões Aceitos
A GoPag aceita todas as principais bandeiras:
* **Visa** - Crédito e Débito
* **Mastercard** - Crédito e Débito
* **Elo** - Crédito e Débito
* **American Express** - Crédito
* **Hipercard** - Crédito
* **Diners Club** - Crédito
## 📚 Como Usar Esta Documentação
Esta documentação está organizada para facilitar a consulta:
### 🌐 Portal Web GoPag
Aprenda a usar o portal no computador:
* Como criar cobranças
* Como acompanhar vendas
* Como fazer transferências
* Como gerar relatórios
### 📱 App GoPag (Tap to Pay)
Guia completo do aplicativo no celular:
* Como fazer login
* Como vender com o celular
* Como criar cobranças
* Como ver o extrato
### 📲 Maquininhas S920 e SMART
Manual das maquininhas físicas:
* Como ligar e configurar
* Como fazer vendas
* Como parcelar
* Como estornar
* Como imprimir comprovantes
### � Para Desenvolvedores
Se você é desenvolvedor ou tem uma empresa de software:
* Como integrar ao seu sistema
* Como usar a nossa programação (API)
* Exemplos práticos
* Códigos de exemplo
## 🎯 Primeiros Passos
### Para começar a usar:
1. **Baixe o App**
* Acesse [app.gopag.com.br/download](https://app.gopag.com.br/download)
* Disponível para Android e iPhone
2. **Crie sua Conta**
* Cadastro rápido e gratuito
* Sem burocracia
* Aprove em minutos
3. **Comece a Vender**
* Receba pelo celular (Tap to Pay)
* Crie links de pagamento
* Consulte os manuais se já tiver uma maquininha
## 💬 Precisa de Ajuda?
### Canais de Atendimento
* 📱 **WhatsApp:** (62) 3602-4409
* 🌐 **Site:** [gopag.com.br](https://gopag.com.br)
* 📧 **Portal de Suporte:** Acesse pelo app ou site
* 📚 **Esta Documentação:** Manuais e guias completos
### Dúvidas Frequentes
Encontre respostas rápidas na seção de cada produto:
* Dúvidas sobre Tap to Pay
* Dúvidas sobre Maquininhas
* Dúvidas sobre o Portal
* Dúvidas sobre Cobranças
## 🔗 Links Importantes
* � [Baixar App GoPag](https://app.gopag.com.br/download)
* 💻 [Acessar Portal Web](https://app.gopag.com.br/portal)
* 🌐 [Site Oficial](https://gopag.com.br)
* 💬 [Falar no WhatsApp](https://wa.me/556236024409)
* 📘 [Documentação Técnica (Desenvolvedores)](https://github.com/Gestao-Online/gopag-public-docs/blob/master/developers/README.md)
* 🔏 [Política de Privacidade](/politica-de-privacidade)
***
**GoPag** - Pagamentos simples, rápidos e seguros para o seu negócio.
*Comece agora mesmo. É grátis para começar!*
# Portal Web GoPag
Bem-vindo à documentação do Portal Web GoPag!
O Portal Web GoPag é a plataforma completa para gestão de cobranças, transações e configurações da conta.
## 📚 Navegação
Utilize o menu lateral para acessar as diferentes seções do portal:
* **Menu de Navegação** - Conheça a interface do portal
* **Dashboard** - Visão geral das transações e saldo
* **Criar Cobrança** - Gere links de pagamento para clientes
* **Cobranças** - Gerencie cobranças avulsas e modelos
* **Transações** - Acompanhe todas as vendas
* **Transferências** - Controle transferências bancárias
* **Simular Venda** - Calcule taxas e valores
* **Relatórios** - Exporte dados e análises
* **Suporte** - Obtenha ajuda
* **Configurações** - Personalize a conta
* **Aplicativos Pixel Ads** - Integre pixels de rastreamento
* **Planos GoPag** - Conheça os planos disponíveis
# Menu de Navegação
Ao acessar seu ambiente **GoPag**, nesse primeiro momento será a hora de conhecer a aplicação que está utilizando!
Sua tela inicial será similar ao que consta na imagem da tela de teste abaixo:
**Porém, com suas informações de saldo!**
Agora, voltando nossa atenção para o canto superior direito da tela, podemos visualizar um pequeno card com seu nome incluso. Clicando sobre este card, uma janelinha irá aparecer logo abaixo do seu nome com algumas informações:
* Nome da empresa e o CNPJ, isso para planos de conta do tipo pessoa jurídica;
* Nome da pessoa e CPF, este sendo para pessoas físicas;
* A última opção é a de sair/logout da conta.
É possível observar esses detalhes na imagem abaixo:
Olhando agora para o lado esquerdo da tela pode-se visualizar uma coluna com algumas figuras.
**Essas figuras são as opções de menu!**
Quando passamos a setinha do mouse por cima desta coluna ela irá se expandir e com isso os nomes de cada ícone irá aparecer.
Clicando no ícone de fixar 📌, o menu lateral irá ficar sempre com o tamanho cheio, sendo possível ver além dos ícones os nomes de cada um deles. 😉👍
| | |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  | Além disso, tem mais um detalhe essencial para podermos nos localizarmos dentro da plataforma. Quando selecionamos um menu, ele ficará destacado em uma cor laranja-claro.
Isso foi pensado justamente para poder facilitar sua navegação dentro da plataforma.
Incrível, não é mesmo!
Portanto, prepare-se, pois estamos prestes a conhecer cada uma das áreas disponíveis dentro da plataforma GoPag!
|
# Dashboard
Na tela principal da plataforma **GoPag**, há informações com o saldo atual, saldo futuro ou total de transações.
Também é possível ver os gráficos de transações, cobranças, e até o calendário com recebimentos futuros:
No primeiro card está disponível o botão para sacar o valor do saldo atual, mas vale uma atenção a mais nesta parte, pois este botão só aparece caso tenha sido optado por utilizar o tipo **`Saque manual`**:
Clicando neste botão você será direcionado para uma janela pop-up solicitando o valor a ser sacado, após inserir o valor e clicar em confirmar saque, ele será agendado a transferência bancária para a conta que estiver ativa no momento:
{% hint style="warning" %}
**Atenção:** Para mais informações sobre a **conta bancária cadastrada**, [**`clique aqui`**](https://docs.gopag.com.br/portal_gopag/configuracoes#conta-bancaria)
{% endhint %}
Descendo um pouco mais no dashboard, é possível ver os gráficos e a tabela com as informações de transações. Essas informações podem ser alteradas se for alterada a data de exibição, sendo por mês, semana ou dia;
Observe nosso teste abaixo com as três opções, primeiro com o mensal:
Agora definindo a data para uma semana:
E por último definindo para somente um dia:
Na parte final, há um pequeno relatório com as últimas cinco transações, e um atalho para ir direto ao menu de todas as transações:
{% hint style="warning" %}
**Atenção:** Para mais informações sobre **transações**, [**`clique aqui`**](/portal_gopag/transacoes)
{% endhint %}
**Mas as opções do dashboard não param por aí! 😁**
Clicando na opção cobranças que está logo ao lado de transações, há uma nova tela a ser exibida, agora com gráfico de crescimento, um botão de atalho para criar uma nova cobrança, o relatório das últimas cobranças geradas e o status dessas cobranças.
Lembrando que tudo é influenciado pela data que você determina
{% hint style="warning" %}
**Atenção:** Para mais informações sobre **transações**, [**`clique aqui`**](/portal_gopag/transacoes)
{% endhint %}
E fechando a explicação sobre todas as funções disponíveis no dashboard da plataforma da GoPag, há o calendário com os recebimentos futuros, projetado justamente para ter mais controle dos recebimentos.
Observe que ao clicar em um recebimento futuro, um novo card é exibido com todas as informações referentes:
Nesse mesmo calendário há disponível outras funções, por exemplo, exibir por semana e um botão para o calendário ir direto ao dia atual, demonstramos abaixo o uso dessas opções 😁
# Criar Cobrança
O acesso à criação de uma cobrança é facilitado, já no momento do login na plataforma da GoPag o botão de criar cobrança fica disponível em dois locais:
O primeiro lugar é ao lado esquerdo do início do menu que se recolhe.
O segundo local é no dashboard na aba de cobranças:
Ao clicar em uma das duas opções listadas, você abre a configuração da criação de cobrança, onde pode identificar o tipo de cobrança que será gerada, valor, e escolher um dos tipos disponíveis, sendo eles:
## [**Avulsa**](https://docs.gopag.com.br/portal_gopag/criar_cobranca/link_cobranca)
Quando falamos de cobrança do tipo avulsa nos referimos a um pagamento único ou pontual feito por um produto, ou serviço específico, sem a necessidade de um compromisso contínuo. Como exemplo a compra de um item em uma loja online e pagar por ele uma única vez.
## [**Modelo**](https://docs.gopag.com.br/portal_gopag/criar_cobranca/link_cobranca/link_cobranca_modelo)
A cobrança modelo ao ser gerada, cria um link único que pode ser utilizado diversas vezes para pagamento de um valor fixo, e para cada transação nesse único link haverá a informação completa de quem efetuou o pagamento, tudo isso e muito mais na plataforma da GoPag.
# Formas de Pagamento
Após preencher os dados iniciais da cobrança, é possível limitar as formas de pagamento para o cliente, sendo elas cartão de crédito (e a quantidade de parcelas), pix e/ou boleto.
{% hint style="warning" %}
**Detalhe:** Caso você não defina a forma de pagamento, ou se esqueça, não precisa se preocupar, pois por padrão, nós deixaremos disponíveis ao cliente as opções pix e cartão de crédito (Com parcelamento até 6x)😉
{% endhint %}
{% hint style="danger" %}
**Importante:** Para mais informações sobre as taxas, [clique aqui](https://docs.gopag.com.br/portal_gopag/simular_venda) e acesse nossa explicação detalhada sobre elas!
{% endhint %}
# Cartão de Crédito
Neste momento será definida a quantidade de parcelas disponíveis para o cliente. Observe que ao clicar na opção cartão de crédito logo abaixo um novo card ficará disponível para uso:
Nesse card disponível o uso é bem simples, precisando apenas de você definir a quantidade de parcelas disponíveis para o seu cliente.
Observe que deixamos no exemplo disponível para até 12x, mas lembre-se, quem definirá a quantidade ao cliente, será você.
{% hint style="danger" %}
**Importante:** Para mais informações sobre as taxas, [clique aqui](https://docs.gopag.com.br/portal_gopag/simular_venda) e acesse nossa explicação detalhada sobre elas!
{% endhint %}
Feito isso, aparecerá para o cliente três opções de parcelamento, dando assim a opção dele escolher, isso tudo dentro do limite que você estabeleceu:
# Pix
O sistema de pagamento PIX no Brasil também adotou uma forma profissional de recebimento, o EVP (Endereço virtual de pagamento), que facilita muito o recebimento e conferência dos pagamentos, sem precisar ficar analisando o extrato da sua conta bancária.
O legal, é que o nosso portal gera uma "chave" de PIX copia e cola para cada transação, dessa forma, o cliente realiza pagamentos de maneira instantânea bastando ler esse QRcode ou usar o PIX copia e cola.
{% hint style="info" %}
**Informação:** O controle dos pagamentos segue normalmente na plataforma da GOPag, para acompanhar todo o andamento da cobrança! 😁
{% endhint %}
Logo, para o cliente irá aparecer da seguinte forma para que ele possa preencher os dados e ter acesso à chave PIX para pagamento:
# Boleto
Na forma de pagamento boleto bancário, o prazo de compensação é de até 48h úteis. Mas não se preocupe, a compensação normalmente ocorre no próximo dia útil após o pagamento. 😁
{% hint style="warning" %}
**Detalhe:** Caso você tenha mais de um boleto a ser emitido, é possível repetir essa cobrança reaproveitando os dados que o cliente já preencheu, através do menu [criar cobrança novamente](https://docs.gopag.com.br/portal_gopag/criar_cobranca/link_cobranca)
{% endhint %}
Observe que ao clicarmos no botão `Habilitar configurações de multas e juros` um novo menu de opções será mostrado:
Neste menu será possível configurar a multa de atraso do boleto, podendo cobrar até 2% sobre o valor de pagamento em caso de atrasos.
Há duas opções, sendo definido se será em dinheiro ou porcentagem (a plataforma da GOPag corrige o valor automaticamente, caso coloque acima do padrão de 2% estabelecido pelo **Código Tributário Nacional** 😅)
Pode também configurar o juro mora ou moratórios, podendo ser em dinheiro ou porcentagem conforme imagem abaixo.
Esses juros consistem em uma taxa aplicada sobre o atraso no pagamento de uma conta, sendo possível colocar 1% ao mês no máximo, conforme estabelecido pelo Código Tributário Nacional:
Finalizando então com a data limite para pagamento, podendo o boleto ser pago no período que você definir, sendo o prazo máximo até 90 dias, após isso o cliente precisará entrar em contato com você para a emissão de um novo boleto:
Nesta parte em laranja-claro, tem um simulador de valores em caso de atraso, para que você confira as variações de valores conforme os dias de atraso:
Logo, para o cliente irá aparecer da seguinte forma para ele preencher os dados e logo após ter acesso ao boleto para pagamento:
{% hint style="danger" %}
**Importante:** Para mais informações sobre as taxas, [clique aqui](https://docs.gopag.com.br/portal_gopag/simular_venda) e acesse nossa explicação detalhada sobre elas!
{% endhint %}
# Informações do cliente
Na parte de informações do cliente, já é possível preencher no momento de gerar a cobrança, observe que ao final há um botão para ativar o envio de notificações e atualizações desta cobrança por e-mail ou SMS do pagador. Mas ele só ficará disponível caso seja preenchido o campo de e-mail.
Observe o exemplo que fizemos abaixo:
Agora se você tiver criado uma cobrança modelo, irá aparecer somente o botão de envio de notificações, não sendo necessário preencher nenhuma informação do cliente, pois ficará disponível para que ele preencha no ato do pagamento:
Ok, mas e quanto ao restante das informações no caso da cobrança avulsa?
O cliente pode completar as demais informações no momento em que for efetuar o pagamento! 😉👍
confira abaixo a visão do cliente no momento do pagamento:
# Gerar Link de Cobrança
Após você clicar para gerar o link de cobrança, teremos esta tela abaixo, aqui estão todas as informações necessárias para que você possa acompanhar o processo do pagamento/recebimento:
Qual o tipo de cobrança você está gerando? Clique abaixo na de sua preferência e veja mais informações sobre ela:
# Gerar Link Cobrança Avulsa
De início há um menu no canto direito da tela, com algumas funções importantes para utilizar, são elas:
{% tabs %}
{% tab title="↗️ Notificar" %}
Quando você usar esta função, será enviada uma notificação ao cliente do status atual da cobrança. Serão estas mensagens:\
\
**Nova cobrança:** Olá "........", Esperamos que esteja bem. Estamos entrando em contato para informá-lo(a) de que foi gerada uma nova cobrança por GESTÃO ONLINE para você e ela está pronta e disponível para pagamento.\
\
**Pagamento recusado:** Prezado(a) "........", Estamos entrando em contato para informá-lo(a) que houve um problema ao processar o seu pagamento e a transação não foi concluída.\
\
**Pagamento aprovado:** Prezado(a) "........", Gostaríamos de confirmar que o seu pagamento foi recebido com sucesso. Agradecemos por escolher os produtos/serviços da GESTÃO ONLINE e por sua pontualidade no pagamento.
{% endtab %}
{% tab title="🗑️ Excluir cobrança" %}
Em caso de erros, você tem disponível esta opção para poder excluir a cobrança, lembrando que essa função só estará disponível enquanto não houver o pagamento por parte do cliente, após o pagamento, não será mais possível excluir.
{% endtab %}
{% tab title="➕ criar cobrança novamente" %}
Com esta função é possível ganhar tempo ao reutilizar a mesma cobrança com os dados do cliente caso seja necessário, ou alterar algum item antes de usar novamente.
{% endtab %}
{% tab title="🖋️ Editar cobrança" %}
Caso tenha faltado alguma informação, ou chegou a fazer algum lançamento errado, é possível editar a cobrança antes do pagamento, mas lembre-se, após o pagamento esta função não estará mais disponível.
{% endtab %}
{% endtabs %}
No primeiro card tem três partes para acompanhamento, sendo elas:
* Status do pagamento (Novo, pago, pendente ou falha);
* Data da criação da cobrança;
* Forma de pagamento (Cartão de crédito, pix ou boleto).
   
| | |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| Já no segundo card, colocamos as formas de pagamentos disponíveis.
Lembrando que aqui só irão aparecer as opções que você selecionou no momento de criar o link da cobrança.
|  |
| | |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  | No terceiro card estão as opções de compartilhamento do link para pagamento, sendo possível utilizar para enviar via WhatsApp ou e-mail.
Mas caso queira, também pode copiar o link da cobrança diretamente e repassar ao cliente.
|
Agora no quarto card estão os dados da cobrança e dados do pagador. Saiba que a cada cobrança gerada é criado um código único para maior controle da plataforma da GOPag. 😊
Os dados do pagador podem ser preenchidos por você no ato da cobrança, ou caso prefira, deixar o próprio cliente preencher quando ele for efetuar o pagamento:
No quinto card vemos:
* Endereço do cliente (Lembrando que o próprio cliente pode fazer o preenchimento quando for pagar 😉);
* Configurações da cobrança (Caso tenha definido parcelas para o caso do cartão de crédito e a [taxa de transação](https://docs.gopag.com.br/portal_gopag/simular_venda) e adicional).
Aqui no último card colocamos as configurações aplicadas no boleto, como taxas, data de vencimento e juros aplicados:
{% hint style="warning" %}
**Atenção:** O card com as opções do boleto só serão exibidas caso você tenha adicionado ele como uma opção de pagamento, do contrário, ele ficará indisponível.
{% endhint %}
# Gerar Link Cobrança Modelo
Após você clicar para **`gerar o link de cobrança`**, teremos esta tela abaixo com todas as informações necessárias para podermos acompanhar todo o processo do pagamento:
De início há um menu no canto direito da tela, com algumas funções importantes para utilizar, são elas:
{% tabs %}
{% tab title="↗️ Notificar" %}
Quando você usar esta função, será enviada uma notificação ao cliente do status atual da cobrança. Serão estas mensagens:\
\
**Nova cobrança:** Olá "........", Esperamos que esteja bem. Estamos entrando em contato para informá-lo(a) de que foi gerada uma nova cobrança por GESTÃO ONLINE para você e ela está pronta e disponível para pagamento.\
\
**Pagamento recusado:** Prezado(a) "........", Estamos entrando em contato para informá-lo(a) que houve um problema ao processar o seu pagamento e a transação não foi concluída.\
\
**Pagamento aprovado:** Prezado(a) "........", Gostaríamos de confirmar que o seu pagamento foi recebido com sucesso. Agradecemos por escolher os produtos/serviços da GESTÃO ONLINE e por sua pontualidade no pagamento.
{% endtab %}
{% tab title="🗑️ Excluir cobrança" %}
Em caso de erros, você tem disponível esta opção para poder excluir a cobrança, lembrando que essa função só estará disponível enquanto não houver o pagamento por parte do cliente, após o pagamento, não será mais possível excluir.
{% endtab %}
{% tab title="➕ Criar cobrança novamente" %}
Com esta função é possível ganhar tempo ao reutilizar a mesma cobrança com os dados do cliente caso seja necessário, ou alterar algum item antes de usar novamente.
{% endtab %}
{% tab title="🖋️ Editar cobrança" %}
Caso tenha faltado alguma informação, ou chegou a fazer algum lançamento errado, é possível editar a cobrança antes do pagamento, mas lembre-se, após o pagamento esta função não estará mais disponível.
{% endtab %}
{% endtabs %}
No primeiro card existem duas partes para visualização, sendo elas:
* Status do pagamento (Sendo utilizado, novo ou cancelado);
* Data da criação da cobrança;
  
| | |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| Já no segundo card, colocamos as formas de pagamentos disponíveis.
Lembrando que aqui só irão aparecer as opções que você selecionou no momento de criar o link da cobrança.
|  |
| | |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  | No terceiro card estão as opções de compartilhamento do link para pagamento, sendo possível utilizar para enviar via WhatsApp ou e-mail.
Mas caso queira, também pode copiar o link da cobrança diretamente e repassar ao cliente.
|
Agora no quarto e quinto card estão os dados da cobrança e configurações da cobrança. Saiba que a cada cobrança gerada é criado um código único para maior controle da plataforma da GoPag 😊.
Ali, em configurações da cobrança, caso tenha definido parcelas para o caso do cartão de crédito, serão exibidas as parcelas disponíveis para o cliente pagar:
Por último, no sexto card tem a incorporação de link para pagamento, veja mais informações abaixo:
* Ao lado esquerdo em personalizar, é possível escolher entre duas opções, sendo elas a opção botão, que permite alterar a cor de fundo, cor do texto e a descrição ou o nome que terá escrito neste botão.
Como segunda opção de tipo, há o link, interessante para adicionar o link de cobrança em alguma postagem ou publicação em site, agregando com algum texto já existente, sendo possível alterar a cor do texto e a descrição.
# Cobranças
| | |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|  | Neste menu você conhecerá mais sobre as cobranças geradas avulsas e modelo, com as informações disponíveis e específicas de cada um desses tipos. |
Clique em uma das opções abaixo para saber mais sobre a que deseja:
# Cobranças Avulsa
Este é o menu de cobranças avulsas, todos os links gerados ficam registrados aqui e é possível acompanhar melhor as movimentações:
Colocamos já no início um atalho para que você possa criar uma nova cobrança enquanto estiver vendo os links de cobrança gerados, clicando aqui nesta opção:
{% hint style="warning" %}
**Importante:** Caso queira mais informações sobre criar cobrança [clique aqui ](https://docs.gopag.com.br/portal_gopag/criar_cobranca)para acessar a explicação completa dessa função.
{% endhint %}
Dando sequência à explicação, caso queira fazer uma busca por uma cobrança específica, é possível usar a **`barra de pesquisa`** que está marcada na imagem abaixo:
{% hint style="warning" %}
**Importante:** A barra de pesquisa faz uma busca somente pelo texto que foi colocado na descrição da cobrança avulsa, para outro tipo de busca, confira abaixo as opções disponíveis 😉
{% endhint %}
Em cada item das cobranças há filtros para facilitar a pesquisa por algo mais específico, por exemplo, a opção da **`data de criação`**, escolhendo data de início e término da busca, ou é possível usar um dos atalhos de período que aparecem assim que se abre o calendário, abaixo uma breve demonstração de uso:
Também é possível usar o filtro de busca por **`descrição`**, ele tem a mesma função que a barra de pesquisa, e é possível usar o que for mais prático para o momento:
Contamos com o filtro de **`status`** com todas as opções disponíveis, lembrando que os filtros podem ser utilizados em conjunto para uma busca específica:
* Pago
* Cancelado
* Pendente
* Falha
* Novo
* Pré-autorizado
* Revertido
* Reembolsado
* Disputa
* Charged back
Confira no exemplo abaixo:
Em cada cobrança gerada, é possível observar que na opção detalhes, há dois ícones:
* O ícone do olhinho abrirá o link de cobrança para conferir detalhes sobre ela.
* E o ícone do quadrado com a setinha, tem quase a mesma função, porém abrirá em uma nova janela.
Passando assim, mais de uma possibilidade para acessar as informações 😉👍
{% hint style="warning" %}
**Detalhe:** Caso queira mais informações sobre detalhes de cobrança avulsa [clique aqui ](https://docs.gopag.com.br/portal_gopag/criar_cobranca/link_cobranca/link_cobranca_avulsa)para acessar a explicação sobre cada parte desta função.
{% endhint %}
A paginação na parte final, onde é possível aumentar a quantidade visível de cobranças mostradas para até 1000 itens na página:
.
# Cobranças Modelo
Este é o menu de cobranças modelo, todos os links gerados ficam registrados aqui e é possível acompanhar melhor as movimentações, confira agora cada parte dele 😁:
Colocamos já no início um atalho para que você possa criar uma nova cobrança enquanto estiver vendo os links de cobrança gerados, clicando aqui nesta opção:
{% hint style="warning" %}
**Importante:** Caso queira mais informações sobre criar cobrança [clique aqui ](https://docs.gopag.com.br/portal_gopag/criar_cobranca)para acessar a explicação completa dessa função.
{% endhint %}
Para ficar mais fácil a busca específica por uma cobrança, é possível usar a **`barra de pesquisa`** que está marcada na imagem abaixo:
{% hint style="warning" %}
**Importante:** A barra de pesquisa faz uma busca somente pelo texto que foi colocado na descrição da cobrança modelo, para outro tipo de busca, confira abaixo as opções disponíveis 😉
{% endhint %}
Em cada item das cobranças modelo há filtros para facilitar a pesquisa por algo mais específico, por exemplo, a opção na **`data de criação`**, escolhendo data de início e término da busca, ou é possível usar um dos atalhos de período que aparecem assim que se abre o calendário, abaixo uma breve demonstração de uso:
Também é possível usar o filtro de busca por **`Descrição`**, ele tem a mesma função que a barra de pesquisa, e é possível usar o que for mais prático para o momento:
Já o filtro de **`status`**, traz todas as opções de status disponíveis, lembrando que os filtros também podem ser utilizados em conjunto para uma busca específica:
* Sendo utilizado
* Cancelado
* Pendente
* Novo
Confira no exemplo abaixo:
Em cada cobrança modelo gerada, é possível observar que na opção detalhes, há dois ícones:
* O ícone do olhinho abrirá o link de cobrança para conferir detalhes sobre ela.
* E o ícone do quadrado com a setinha, tem quase a mesma função, porém abrirá em uma nova janela.
Passando assim, mais de uma possibilidade para acessar as informações 😉👍
{% hint style="warning" %}
**Detalhe:** Caso queira mais informações sobre detalhes de cobrança modelo [clique aqui ](https://docs.gopag.com.br/portal_gopag/criar_cobranca/link_cobranca/link_cobranca_modelo)para acessar a explicação sobre cada parte desta função.
{% endhint %}
A paginação na parte final, onde é possível aumentar a quantidade visível de cobranças mostradas para até 1000 itens na página:
.
# 🔄️ Transações
Com a plataforma da GoPag sendo omnichannel, neste menu estão organizadas todas as transações realizadas, por máquinas MPOS(Mobile Point os Sale), POS(Point of Sale), PIN Pad, TEF e até mesmo E-commerces parceiros.
Aqui é possível utilizar os filtros para busca, ou a barra de pesquisa, confira melhor nas explicações abaixo:
Para ficar mais fácil a busca por uma transação específica, é possível usar a **`barra de pesquisa`** que está marcada na imagem abaixo:
{% hint style="warning" %}
**Importante:** A barra de pesquisa faz uma busca somente pelo **`Código de transação`** da cobrança. 😉
{% endhint %}
Em cada item das transações, há filtros para facilitar a pesquisa por algo mais específico, por exemplo, a opção da **`Data de criação`** escolhendo data de início e término da busca, ou é possível usar um dos atalhos de período que aparecem assim que se abre o calendário, abaixo uma breve demonstração de uso:
Também é possível usar o filtro de busca por **`Código de transação`**, ele tem a mesma função que a barra de pesquisa, e é possível utilizar o que for mais prático para o momento:
Já o filtro de **`Status`**, traz todas as opções de status disponíveis, lembrando que todos os filtros também podem ser utilizados em conjunto para uma busca específica:
* Pago
* Cancelado
* Pendente
* Falha
* Novo
* Pré-autorizado
* Revertido
* Reembolsado
* Disputa
* Charged back
Confira no exemplo abaixo:
Outro filtro importante é o do **`Tipo de pagamento`**, onde você procura pelo método utilizado e pode filtrar melhor, ou usá-lo em conjunto com outro filtro:
Em cada transação gerada, é possível observar que na opção **`Detalhes`**, há dois ícones:
* O ícone do olhinho abrirá o link de cobrança para conferir detalhes sobre ela.
* E o ícone do quadrado com a setinha, tem quase a mesma função, porém abrirá em uma nova janela.
Passando assim, mais de uma possibilidade para acessar as informações 😉👍
{% hint style="warning" %}
**Detalhe:** Caso queira mais informações sobre detalhes de transação [clique aqui ](https://docs.gopag.com.br/portal_gopag/transacoes/detalhes_transacoes)para acessar a explicação sobre cada parte desta função.
{% endhint %}
Logo na parte final das transações fica a paginação, onde é possível aumentar a quantidade visível de cobranças mostradas para até 1000 itens na página:
.
# Detalhes Transações
Agora no detalhamento de cada transação existem alguns pontos importantes a tratar, de início a tela que você verá será parecida com esta:
Já no primeiro card podemos ver o **`Status`** do pagamento, que pode ter as opções:
* Pago
* Cancelado
* Pendente
* Falha
* Novo
* Pré-autorizado
* Revertido
* Reembolsado
* Disputa
* Charged back
Enquanto no segundo card podemos ver a data e hora da transação. Fechamos com o terceiro card exibindo qual foi a forma de pagamento utilizada pelo cliente:
No quarto card pode ver os **`Dados do vendedor`** e descrição do link de cobrança gerado, enquanto no quinto card podemos ver os **`Dados do pagador`**, sendo eles, nome, quantidade de parcelas que esse cliente utilizou (Dependendo do tanto que você determinou ao criar o link de cobrança), o número do cartão que foi utilizado e validade do mesmo.
Além do código de autorização e código de NSU que usamos para identificar cada transação de cartão, seja crédito ou débito. 😉
Logo no sexto card é possível visualizar os **`Detalhes da transação`**, tais como valores, a taxa de venda aplicada, e o valor líquido que vai como saldo, assim como o ID da transação de referência.
Na parte inicial da tela de detalhes da transação há um botão chamado **`Estornar pagamento`**, esse botão faz com o que os pagamentos em cartão de crédito ou PIX seja cancelado (os valores serão devolvidos):
{% hint style="warning" %}
**Importante:** Este recurso **`Estornar pagamento`** não está disponível para boleto bancário.
{% endhint %}
Em caso de uso do boleto, existem algumas diferenças nas informações de pagamento, no caso abaixo temos a linha digitável do boleto, a descrição com o dia/horário que foi efetuado o pagamento e também o ID do pagamento:
E na parte inicial da tela de detalhes da **`transação de boleto`** há um botão chamado **`Cancelar`**, ele irá ajudar no momento em que for necessário encerrar a emissão de um boleto, ou alguma transação para fazer estorno ao cliente.
O boleto será cancelado (Não poderá mais ser pago pelo cliente) e também saíra do DDA(Débito Direto Autorizado) com prazo de 1 dia útil.
# Transferências
Quando você solicita uma transferência, seja ela manual ou automaticamente, irá aparecer neste menu, mostrando a data da criação, data de transferência, status, código de transação e o valor solicitado.
Assim é possível acompanhar o andamento de uma transferência até o valor ser baixado em sua conta bancária.
{% hint style="info" %}
**Atenção:** Caso queira mais informações sobre **Configurações de recebimento** [clique aqui ](https://docs.gopag.com.br/portal_gopag/configuracoes#configuracoes-de-recebimento)para acessar a explicação completa dessa função.
{% endhint %}
Aqui é possível utilizar os filtros para buscar uma transferência em específico, ou a barra de pesquisa, confira melhor nas explicações abaixo.
No primeiro momento temos a barra de pesquisa, com ela é possível achar mais rápido uma transferência que deseja conferir:
{% hint style="info" %}
**Importante:** A barra de pesquisa faz uma busca somente pelo **`Código de transação`** da cobrança. 😉
{% endhint %}
Em cada item das transferências, há filtros para facilitar a pesquisa por algo mais específico, por exemplo, as opções **`Data de criação`** e **`Data de transferência`**, podendo escolher a data de início e término da busca, ou é possível usar um dos atalhos de período que aparecem assim que se abre o calendário, abaixo uma breve demonstração de uso:
Já o filtro de **`Status`**, mostra todas as opções de status disponíveis, lembrando que todos os filtros também podem ser utilizados em conjunto para uma busca específica:
* Bem-sucedido;
* Confirmado;
* Agendado;
* Cancelado;
* Pendente;
* Falha;
* Criado.
Confira no exemplo abaixo:
Também é possível usar o filtro de busca por **`Código de transação`**, ele tem a mesma função que a barra de pesquisa, e é possível utilizar o que for mais prático para o momento:
Em cada transferência listada, é possível observar que na opção **`Detalhes`**, há dois ícones:
* O ícone do olhinho abrirá a transferência para conferir detalhes sobre ela.
* E o ícone do quadrado com a setinha, tem quase a mesma função, porém abrirá a transferência em uma nova janela.
Passando assim, mais de uma possibilidade para acessar as informações 😉👍
{% hint style="warning" %}
**Detalhe:** Caso queira mais informações sobre detalhes de transferências [clique aqui ](https://docs.gopag.com.br/portal_gopag/transferencias/detalhes_transferecencias)para acessar a explicação sobre cada parte desta função.
{% endhint %}
Logo na parte final das transferências fica a paginação, onde é possível aumentar a quantidade visível de itens mostrados para até 1000 itens na página:
.
# Detalhes Transferências
Na tela de detalhes da transferência você tem alguns cards com informações importantes.
No começo da página temos o status da transferência, lembrando que ele tem as opções (Bem-sucedido, Confirmado, Agendado, Cancelado, Pendente, Falha e Criado).
Você também encontra a data e hora da transferência, e logo ao lado o valor solicitado:
Logo mais abaixo, você encontra os dados da transferência com a descrição informando que foi um saque via GoPag e a data da criação da transferência.
Ao lado direito você vê também os detalhes da conta bancária, com as informações do banco que vai receber ou já recebeu a transferência que você criou
{% hint style="warning" %}
**Importante:** As transferências possuem um prazvo para serem efetuadas, sendo no máximo um dia útil. 😉
{% endhint %}
# Simular venda
É possível simular valores na plataforma da GoPag antes de você gerar a cobrança ao cliente. Podendo até testar com taxas e acréscimos em valores e condições diferentes para seu cliente, tudo isso antes de gerar o link da cobrança:
Bem fácil de se utilizar, bastando inserir o valor desejado para a simulação de taxas e parcelas, são quatro funções disponíveis, entre elas, o valor que você quer cobrar, que seria o da cobrança em si, o tipo de pagamento, se será online ou presencial e qual a bandeira do cartão a ser utilizado.
{% hint style="warning" %}
**Detalhe:** Cada bandeira de cartão pode ter variação na porcentagem de taxa a ser cobrada, observe bem estes valores 😉
{% endhint %}
No **`Tipo de pagamento`** colocamos duas opções, a online e presencial, o cálculo é feito com doze parcelas e incluso até o cartão de débito, lembrando que o cartão de débito funciona somente no modo presencial:
No menu simular venda, é possível marcar o botão **`Repassar taxas`** para saber qual valor será necessário repassar ao cliente (caso seja este o desejo) e então criar uma cobrança já baseada nesse valor, confira abaixo o exemplo do simulador:
{% hint style="warning" %}
**Informação:** A partir do plano escolhido, os recursos são cobrados em modelo de assinatura e cobranças mensais. Se necessário, somam-se taxas de configuração inicial e tarifas variáveis.
{% endhint %}
# Relatórios
Os relatórios podem ser gerados de forma simples, apenas com alguns cliques na plataforma. Logo abaixo, o card que aparece disponível para utilização é o de **`Extrato`**:
{% hint style="warning" %}
**Importante:** Os extratos podem ser gerados em dois formatos, PDF ou Excel, escolha o que melhor se aplicará.
{% endhint %}
É possível definir a data de início e fim do extrato que deseja fazer conferência:
E na sequência qual formato deseja fazer o download.
{% hint style="info" %}
**Informação:** É importante lembrar que a versão em Excel é editável, permitindo que você copie os dados com mais facilidade. No entanto, o relatório em formato PDF é um pouco diferente, focando mais na leitura das informações.
{% endhint %}
Observe abaixo o modo de emissão de um relatório:
Analisando melhor o relatório gerado em PDF, é possível ver a data que foi feita a transação, o ID para fazer uma busca na plataforma (caso seja necessário), descrição da transação, lançamento, se é de entrada ou saída de valor e o saldo final.
{% hint style="info" %}
**Informação:** Observe que na coluna `Lançamento` nós colocamos as cores `verde` para entrada de valor e **`vermelho`** para saída valor, tudo isso para facilitar sua análise no relatório.
{% endhint %}
# Suporte
Em caso de problemas com a plataforma, ou algo fora do comum e que não esteja conforme a normalidade do sistema, é possível contatar o suporte para que a equipe ajude o mais rápido possível:
É possível falar conosco direto pelo WhatsApp clicando no ícone, sendo encaminhado ao mensageiro automaticamente, conforme exemplo abaixo:
Ou pode usar o nosso portal para suporte, que estaremos prontos para lhe atender, bastando apenas preencher todos os dados necessários e aguardar nosso contato.
Pedimos sempre que explique bem o problema ou ajuda que está precisando, para podermos auxiliar da melhor e mais ágil forma, com nossa equipe de suporte 😉
{% hint style="warning" %}
**Importante:** Na solicitação de suporte, é necessário preencher todos os campos que estão com asterisco vermelho, para que a mensagem seja enviada, ao clicar no botão enviar solicitação!
{% endhint %}
Também é possível enviar um email, em caso de ajuda ou dúvida, para o [suporte@gopag.com.br)](https://github.com/Gestao-Online/gopag-public-docs/blob/master/PORTAL_GOPAG/SUPORTE/suporte@gopag.com.br), lembrando de tentar explicar o mais detalhadamente possível a situação para ajuda o mais breve possível, conforme exemplo abaixo:
# Configurações
Aqui estão as configurações do usuário. O primeiro card é o único que mostra os dados fornecidos no momento da contratação do portal. 😊
### Alterar senha de acesso
No segundo card você vê a opção de `Alterar a senha`, observe que deixamos um botão de segurança que só permite que esse card funcione se ele estiver marcado, o procedimento é simples e rápido, precisando apenas digitar sua antiga senha e depois a nova para usá-la. Confira abaixo:
{% hint style="danger" %}
**Importante:** As senhas seguem algumas regras para serem aceitas, precisa ter no mínimo 8 caracteres, incluindo letra minúscula (a - z), letra maiúscula (A - Z) e número (0 - 9).
{% endhint %}
### Alterar imagem de perfil
Mais abaixo, tem a opção de alterar `Imagem do perfil`. Pedimos apenas alguns requisitos para que tudo funcione direitinho no nosso portal. A imagem precisa estar em um dos seguintes formatos: PNG, JPEG ou SVG.
O tamanho também tem um limite, que é de apenas 5MB. Confira abaixo o passo a passo para a substituição da sua foto de perfil:
### Alterar logo da empresa
O mesmo também se aplica a `Logo da empresa`, é possível configurá-la igual o exemplo abaixo, deixando a identidade visual da empresa agregada ao portal, aparecendo nos boletos, links de cobrança e mensagens de aviso! 😉
{% hint style="warning" %}
**Detalhe:** As regras de imagem da logo da empresa são as mesmas para a foto de perfil descritas acima. Ou seja, a imagem precisa ter um dos seguintes formatos: PNG, JPEG ou SVG. O tamanho também tem um limite que é de apenas 5MB.
{% endhint %}
### Configurações de recebimento
Uma configuração importante presente na plataforma da **GoPag** é a opção de `Alterar política de recebimento`. É possível deixar as transferências de valores automáticas ou manuais.
Quando esta opção está ativada, é necessário definir o intervalo de transferência entre diário, semanal ou mensal (No modo mensal é possível definir o dia que ocorrerá a transferência, caso queira).
No último campo você define qual a menor quantia em dinheiro que pode ser transferida. Veja o exemplo abaixo:
### Conta bancária
Fechando as opções do menu de configurações, há a `Conta bancária`, sendo possível cadastrar mais de uma conta, e definir para onde irão as transferências.
Caso você queira trocar de conta por outra já cadastrada, um aviso será mostrado para confirmar a alteração. Observe abaixo:
Mas não fica só por aí, caso queira adicionar uma nova conta bancária, basta clicar no botão `Cadastrar conta` do lado esquerdo da tela:
Ao clicar neste botão, uma janela pop-up será mostrada a você para poder inserir os dados da conta, com o tipo, código do banco, agência bancária, digito do banco e número da conta. Confira o exemplo abaixo:
{% hint style="warning" %}
**Atenção:** O campo **"Dígito da agência (DV)"** é um número utilizado para autenticar a agência bancária, evitando erros na identificação da conta ao fazer uma transação. Ele vem depois de um traço, após a numeração da agência, no formato “0000-x”. Caso não tenha um número, coloque a letra “X” no campo de dígito da agência.
{% endhint %}
{% hint style="danger" %}
**Importante:** Ao adicionar uma conta bancária à plataforma, não é possível remover depois. Por isso, confira corretamente quando for fazer o cadastro.
{% endhint %}
# Aplicativos Pixel Ads
**Como funcionam os pixels de conversão?**
Você pode integrar a plataforma GoPag a diversas redes de anúncios e ferramentas externas para rastrear as visitas ao checkout, boletos gerados e vendas aprovadas.
Para isso, utilizamos os pixels de conversão. O mais utilizado é o pixel do Facebook Ads.
Todos os pixels de conversão na plataforma da GoPag são separados por produto, ou seja, é possível adicionar diferentes pixel em cada produto.
**Aprenda como integrar com o pixel de diversos serviços:**
[Pixel do Facebook](https://docs.gopag.com.br/portal_gopag/ads_pixel/facebook_ads)
[Pixel do Google](https://docs.gopag.com.br/portal_gopag/ads_pixel/google_ads)
[Pixel Analytics](https://docs.gopag.com.br/portal_gopag/ads_pixel/analytics_ads)
[Pixel do Pinterest](https://docs.gopag.com.br/portal_gopag/ads_pixel/pinterest_ads)
[Pixel Taboola](https://docs.gopag.com.br/portal_gopag/ads_pixel/taboola_ads)
[Pixel Outbrain](https://docs.gopag.com.br/portal_gopag/ads_pixel/outbrain_ads)
[Pixel do TikTok](https://docs.gopag.com.br/portal_gopag/ads_pixel/tiktok_ads)
[Pixel Kwai](https://docs.gopag.com.br/portal_gopag/ads_pixel/kwai_ads)
\
# Pixel do Facebook
É possível integrar o Pixel do Facebook aos produtos para rastrear as vendas e otimizar as campanhas de anúncio.
No menu principal, clique em Produtos e depois selecione o produto que deseja adicionar o pixel.
Em seguida, clique na aba Configurações:
Desça a tela até a opção de Pixels de conversão.
Preencha com o seu Pixel ID:
{% hint style="warning" %}
**Importante:** A plataforma permite adicionar até 50 Pixels do Facebook em cada produto.
{% endhint %}
Para cada Pixel, deve ser selecionado um domínio onde ele será disparado.
Por padrão, adicionamos o domínio da plataforma da GoPag, mas recomendamos que você coloque o domínio do seu website ou página de vendas, o mesmo que você verifica no Facebook.
## Perguntas frequentes
### Como funciona a verificação de domínio?
Os pixels são disparados no domínio, que pode ser conectado à plataforma da GoPag. Esse deve ser o mesmo domínio verificado no Facebook.
Temos um tutorial explicando o passo a passo, [clique aqui](https://docs.gopag.com.br/portal_gopag/ads_pixel/facebook_ads/conectar_dominio).
### Como adicionar uma porcentagem de conversão personalizada para pix ou boletos gerados?
É possível selecionar a porcentagem do valor do pix ou do boleto gerado para que ele tenha a conversão personalizada, gerando o evento de "purchase".
Essa ferramenta irá otimizar as suas campanhas, visto que auxilia a estimar uma porcentagem de conversão e qual valor de venda deve ser enviado ao Facebook.
Para ativar essa função, é necessário habilitar o evento Purchase ao gerar um pix ou boleto e adicionar a porcentagem desejada.
Veja o exemplo abaixo em que selecionamos a porcentagem de 50% do valor do boleto para enviar o evento de "purchase".
### Quais eventos a plataforma GoPag envia para o Pixel?
* InitiateCheckout (quando alguém visita o checkout)
* Purchase (compra aprovada no cartão ou PIX)
* Boleto (boleto gerado)
Em compras aprovadas no cartão, disparamos juntamente com o evento de "Purchase", o evento de "credit\_card".
Em compras aprovadas no pix, disparamos juntamente com o evento de "Purchase", o evento de "pix".
Por padrão, não disparamos o evento "purchase" para boleto gerado, mas é possível habilitar essa opção se preferir.
{% hint style="warning" %}
**Importante:** Compra recusada no cartão de crédito não gera evento de "purchase".
{% endhint %}
### Onde encontro meu Pixel do Facebook?
Acesse o Facebook Business Manager e no menu à esquerda clique em Mais ferramentas, depois em Gerenciador de eventos.
Uma nova página abrirá, basta clicar no menu lateral esquerdo em Fontes de Dados:
E você encontrará o seu Pixel ID na coluna à esquerda:
### Como verificar se o meu Pixel do Facebook foi instalado corretamente?
O Facebook disponibiliza um Plugin para o Google Chrome que ajuda a verificar o Pixel. É possível fazer o download no link abaixo:
Após instalado, acesse o link do checkout e selecione o ícone do FB Pixel Helper no canto superior direito do navegador para ver o Pixel encontrado.
É possível ver na imagem acima alguns dos parâmetros que enviamos nos eventos, como a forma de pagamento, valor, ID do produto, entre outras informações.
### É possível usar a API de conversão do Facebook também?
Sim, nós temos um tutorial explicando [como configurar a API de conversão do Facebook](https://docs.gopag.com.br/portal_gopag/ads_pixel/facebook_ads/config_api_facebook).
### Por que aparece outro Pixel ID que não é o meu no checkout?
Para a API de conversões do Facebook funcionar corretamente, é necessário disparar um evento de PageView utilizando o Pixel da própria plataforma da GoPag. Isso é necessário para que os cookies do Facebook sejam identificados.
Por isso, é possível ver o pixel sendo disparado como PageView no checkout, mas pode ignorar essa informação.
# Conectar domínio
## 🔵 Conectar domínio
## Como conectar o domínio verificado do Facebook Ads
Devido as novas atualizações do iOS 14, o Facebook exige que o seu pixel de conversão seja disparado no domínio do seu site (que deve ser verificado no Facebook).
Você pode conectar esse mesmo domínio (ou vários) a pltaforma da GoPag, para que o pixel seja disparado nele, e não ocorra nenhum problema de rastreio no Facebook.
A pltaforma da GoPag pode fazer o disparo do Pixel dentro do seu domínio, através de um subdomínio no formato pixels.seusite.com
#### Como conectar meu domínio na plataforma da GoPag
Dentro de Editar produto -> Configurações, na parte de Pixels de conversão, clique no link Gerenciar domínios Facebook
Em seguida clique em Adicionar domínio
Preencha o seu domínio base
#### Configurando o DNS
Agora vá no lugar onde você registrou o seu domínio, ou onde gerencia o DNS (GoDaddy, Namecheap, Cloudflare, etc...)
Crie uma entrada CNAME, com valor pixels, apontando para pixels.gopag-stage.com.br
{% hint style="warning" %}
**Importante:** Caso você use Cloudflare, crie a entrada sem proxy, ou seja "apenas DNS".
{% endhint %}
Pronto, agora pode voltar para a plataforma da GoPag e salvar o domínio que acabou de adicionar
#### Verificando o seu domínio
Ao adicionar um domínio, ele já pode ser usado para disparar os Pixels, a verificação não é obrigatória.
Se você quer verificar que o domínio foi configurado corretamente, clique sobre ele:
Em seguida, clique em Verificar domínio. Pode levar 15-20 segundos carregando.
Se o ícone mudar para a cor verde, o domínio foi configurado com sucesso.
{% hint style="warning" %}
**Importante:** Se posteriormente você alterar os nameservers do domínio, ou alterar / remover a entrada CNAME que criou, o pixel irá parar de funcionar.
{% endhint %}
#### Verificando se a entrada DNS foi adicionada corretamente
Para conferir se está tudo certo é bem simples! Primeiro, acesse o site da [MX toolbox](https://mxtoolbox.com/)
Preencha a barra de pesquisa dessa forma: pixels.seudomínio.com.br trocando "seudomínio.com.br" pelo que está utilizando.
Se a configuração estiver correta, estará marcado com um certinho verde e apontando para a plataforma da GoPag!
#### Utilizando o seu domínio para disparar Pixels
Na parte de configuração dos Pixels do Facebook, selecione o domínio onde quer que o Pixel dispare.
Diferentes Pixels podem disparar em diferentes domínios, ou no mesmo domínio. Você tem total controle.
[Clique aqui para ler o nosso artigo mais completo sobre como instalar o Pixel do Facebook](https://docs.gopag.com.br/portal_gopag/ads_pixel/facebook_ads)
#### Sou afiliado, preciso ter um domínio próprio para instalar o Pixel do Facebook?
Sim, para que os eventos sejam disparados corretamente é necessário ter a sua própria estrutura, como a página de vendas.
# API de Conversão do Facebook
### Como configurar a API de Conversão do Facebook
A API de conversão ajuda o seu Pixel a ter mais precisão e rastrear as vendas corretamente.
Ela é uma **opção adicional** de rastreio, e não interfere no funcionamento do pixel comum. Você continuará usando o Pixel convencional.
Os eventos da API de conversão nunca duplicarão com os do Pixel convencional, pois em cada evento passamos um ID único, e o Facebook se encarrega de evitar duplicações.
Em resumo: Você só tem a ganhar implementando a API de conversões. É um adicional que irá melhorar as suas campanhas!
### Pegando o Token da API de Conversão no Facebook
Em **Fontes de Dados**, acesse o seu **Pixel do Facebook** e clique na guia **Configurações**.
Desça a tela até a seção da API de Conversões e clique no link **Gerar token de acesso**.
Aparecerá uma caixinha com o Token da API de conversão. Copie ele inteiro.
### Colocando o Token da API de conversão na plataforma da GoPag
No painel da plataforma da GoPag, edite o produto que você quer configurar a API de conversões, e na seção de **Configurações > Pixels do Facebook**, clique no ícone de configurações.
Então, cole o Token da API e salve.
Pronto! A API de conversões foi configurada corretamente!
Você deverá repetir esse processo para cada novo produto que criar, ou se quiser usar várias contas do Facebook ao mesmo tempo.
Lembrando que a API de conversão não é obrigatória, e é possível ter ao mesmo tempo, Pixels com e sem API de conversão.
# Pixel do Google
### Como adicionar o pixel de conversão do Google Ads
Você pode adicionar até 5 pixels ou eventos de conversão por produto.
O primeiro passo é gerar ou encontrar o seu Pixel do Google Ads.
### Encontrando o ID do Pixel Google Ads e Label de conversão
O ID do Pixel Google Ads é único para a sua conta inteira do Google, ou seja, ele não muda.
O Label de conversão muda quando você cria conversões diferentes no Google Ads.
Você pode encontrar o seu Pixel Google Ads em **Metas -> Resumo -> Nova ação de conversão**
 
Será preciso selecionar a opção **Criar ações de conversão manualmente usando código** e, após isso, salvar e continuar para a próxima etapa.
Após concluir a criação do pixel, clique na opção **ver snippet do evento**:
O ID do Pixel Google ads e o Label de conversão são separados por uma barra `/`.
Os dados da foto acima seriam:
**ID do Pixel Google Ads:** AW-11468698711
**Label de conversão:** FW1mCOf\_i4cZENfo2dwq
### Adicionando o pixel do Google Ads no seu produto
Você pode adicionar até 5 pixels ou eventos de conversão diferentes por produto.
Basta ir em **Editar produto** -> aba **Configurações**.
Então, desça até a seção de Pixels de conversão (é no mesmo local onde coloca o Pixel do Facebook). E clique na aba Google Ads.
{% hint style="warning" %}
**Importante:** Para cada pixel / evento que você deseja disparar, é necessário ter uma conversão separada no Google Ads, ou seja, o ID do Pixel será o mesmo, mas o Label irá se alterar em cada conversão. Dessa forma, deve-se configurar os eventos separadamente na plataforma da GoPag.
{% endhint %}
**Veja um exemplo:** Um produtor adicionou a conversão “Iniciate checkout” no Google Ads. Já na plataforma da GoPag ele deve adicionar as informações dessa conversão e selecionar apenas a opção “Disparar ao visitar o Checkout”. Caso selecione mais opções, isso irá interferir no disparo dos eventos.
Para as outras conversões, basta seguir o mesmo passo a passo!
### Testando a integração com o Google Ads
Você pode baixar a extensão Google Tag Assistant para checar se os disparos estão sendo feitos corretamente.
# Pixel Analytics
## Como adicionar o pixel do Google Analytics ao seu produto
No menu principal, clique em Produtos, selecione o produto desejado e na aba Configurações:
Agora basta selecionar o pixel G Analytics e adicionar o ID de acompanhamento:
## Perguntas frequentes
### O que é o ID de acompanhamento do Google Analytics?
Para integração e marcação de eventos entre a plataforma da GoPag e o Google Analytics, utiliza-se a Tag Universal Analytics (UA).
Este é o ID de acompanhamento, inserido automaticamente no código-fonte da plataforma da GoPag ao adicionar a configuração acima.
{% hint style="danger" %}
**Importante:** Não é possível conectar o Google Analytics usando uma tag Google Analytics 4.
{% endhint %}
### Como configurar o Google Analytics (Universal Analytics)?
Você pode conferir as instruções de configuração do ID Universal Analytics no link abaixo:
* [Configurando o Google Analytics (Universal Analytics)](https://support.google.com/analytics/answer/10269537?hl=pt-BR\&ref_topic=9303319)
### Quais os parâmetros rastreados no Google Analytics?
No momento, o único parâmetro rastreado é o de PageView. Estamos trabalhando para trazer atualizações em breve.
# Pixel do Pinterest
### Como adicionar o Pixel do Pinterest ao seu produto
O pixel do Pinterest é uma excelente ferramenta para mensurar conversões e auxiliar na otimização dos anúncios.
### Onde encontro meu Pixel do Pinterest?
Acesse **Pinterest Ads Manager** e clique em **Anúncios**, em seguida, clique em **Conversões**.
Após isso, será preciso clicar em **Gerenciador de Tags** e, depois, em **Instalar a Tag do Pinterest**.
Você deverá seguir com a **Configuração manual**, coletar o pixel ID e, então, instalar na plataforma da GoPag.
{% hint style="warning" %}
**Importante:** Lembrando que na imagem acima é apenas um exemplo, é necessário criar o seu próprio pixel ID na plataforma do **Pinterest Ads**.
{% endhint %}
### Colocando o Pixel ID do Pinterest na plataforma da GoPag
Na plataforma, acesse **Produtos -> Selecione o seu produto -> Configurações**, clique na opção do Pinterest e cole o pixel ID lá.
Após isso, é possível salvar o produto.
### Como adicionar uma porcentagem de conversão personalizada para pix e boletos gerados?
É possível selecionar a porcentagem do valor do pix ou boleto para que ele tenha a conversão personalizada, gerando o evento de **Checkout**.
Essa ferramenta irá otimizar as campanhas, visto que auxilia a estimar uma porcentagem de conversão e qual valor de venda deve ser enviado ao Pinterest Ads.
Veja o exemplo abaixo em que selecionamos a porcentagem de 50% do valor do pix para enviar o evento de Checkout.
Para ativar essa função, é necessário habilitar abaixo do Pixel ID.
### Quais eventos a plataforma da GoPag envia para o Pixel?
* **PageVisit** (Quando ocorre uma visita ao seu checkout)
* **AddToCart** (Início da finalização de compra)
* **Checkout** (Registro de compra aprovada)
{% hint style="info" %}
**Importante:** Por padrão, não disparamos o evento "checkout" para boleto e pix gerado, mas é possível habilitar essa opção se preferir.
{% endhint %}
### Como verificar se o meu Pixel do Pinterest foi instalado corretamente?
O Pinterest disponibiliza um Plugin para o Google Chrome que auxilia na verificação do seu pixel, com ele é possível analisar em tempo real os disparos de eventos.
Para baixar, basta acessar o link a seguir:
[https://chrome.google.com/webstore/detail/pinterest-tag-helper](https://chrome.google.com/webstore/detail/pinterest-tag-helper/gmlcbajhgoaaegmlbaclmmmhpmfdajmp)
Após instalado, basta acessar o seu checkout e clicar no ícone do Pinterest Tag Helper para abrir a central de verificação da extensão e conseguir visualizar o seu pixel.
Na imagem acima é possível observar, também, alguns dos parâmetros que enviamos.
### É possível usar a API de conversão do Pinterest também?
A API de conversão do Pinterest ainda não está disponível.
\
# Pixel Taboola
### Como adicionar o pixel do Taboola
A integração da plataforma da GoPag com a Taboola funciona através do disparo de eventos.
Você precisa criar os eventos na sua conta do Taboola (cada evento terá um nome único), e em seguida cadastrar esses eventos nas configurações do produto da plataforma da GoPag.
O primeiro passo é pegar o seu Account ID. Precisamos disso para instalar o Pixel.
### Pegando o Account ID Taboola
Faça o login na sua conta do Taboola. Você então poderá ver o Account ID no canto direito superior da tela.
**Exemplo:**
Account ID: 1386930
### Criando o Pixel Taboola
Se você ainda não tem um Pixel taboola, vá ao menu **Tracking** e clique em **Create Pixel**.
Você não precisa copiar o código do seu Pixel agora, pois usaremos o seu **Account ID**.
### Criando os eventos de conversão
Agora é possível criar os eventos de conversão no Taboola.
Basta acessar o menu **Tracking -> New Conversion**
No tipo de conversão, selecione a opção **Event**
Você pode selecionar um nome de evento pré-existente ou criar um novo, e configurar opções como, por exemplo, um valor fixo da conversão.
Preste atenção, será necessário cadastrar o **Event Name** na plataforma da GoPag, então copie-o para um bloco de notas.
Basta então salvar a conversão recém-criada no Taboola no fim da página.
### Cadastrando os eventos de conversão na plataforma da GoPag
{% hint style="warning" %}
**Importante:** Você pode cadastrar até 5 pixels/eventos de conversão por produto na plataforma da GoPag.
{% endhint %}
Acesse a aba de **Configurações** do seu produto e desça a tela até a seção de **Pixels**, depois clique em Taboola.
Clique em adicionar e preencha as informações do evento que acabou de gerar.
Você pode adicionar até 5 eventos por produto, com nomes e combinações diferentes. Basta repetir o processo e configurar cada um.
Por exemplo, pode ter um evento para visitas ao checkout e outro para compras aprovadas.
### Testando o Pixel Taboola
Você pode utilizar a própria extensão do Taboola para Google Chrome para testar as conversões:
[https://chrome.google.com/webstore/detail/taboola-pixel-helper](https://chrome.google.com/webstore/detail/taboola-pixel-helper/aefiepimkogajhddmhcekceihikjcabd)
\
# Pixel Outbrain
### Como adicionar o pixel da Outbrain
A integração da plataforma da GoPag com a Outbrain funciona por meio do disparo de eventos.
Você precisa criar os eventos na sua conta da Outbrain (cada evento terá um nome único), e em seguida cadastrar esses eventos nas configurações do produto da plataforma da GoPag.
O primeiro passo é pegar o ID do seu pixel Outbrain. Ele se chama OB\_ADV\_ID.
### Pegando o ID do Pixel Outbrain (OB\_ADV\_ID)
Faça o login na sua conta da Outbrain. Clique no menu **Conversions**, e em seguida em **Install Pixel**.
 
Selecione a opção **Install pixel manually** e depois clique em **Install**.
Você precisará então extrair o **OB\_ADV\_ID** do código do Pixel.
Recomendamos que você copie o pixel inteiro para um bloco de notas no seu computador, e depois extraia o **OB\_ADV\_ID**.
No exemplo da imagem acima, o ID extraído seria: **005ac8c25cf8c87a79d79c832a914d0cc2**
### Criando os eventos na Outbrain
No menu **Conversions**, clique em Add Conversion.
Em Type selecione a opção **Event-based conversion** e abaixo, selecione a opção **Manual code**
Escolha uma categoria para o evento de conversão e escreva um nome.
O nome do evento será o mesmo que você cadastrará na plataforma da GoPag
No exemplo da imagem acima, o nome do evento criado foi **venda**, mas é possível escolher qualquer nome que quiser.
Por exemplo, é possível ter um nome de evento diferente para cada produto.
Clique em salvar no fim da tela.
Pronto, o evento foi criado na Outbrain, agora é necessário cadastrar o mesmo pixel e evento na plataforma da GoPag
### Cadastrando o pixel e eventos na plataforma da GoPag
Você pode cadastrar até 5 pixels/eventos de conversão por produto na plataforma da GoPag.
Basta ir em **Editar produto -> aba Configurações**, e descer a tela até a seção de Pixels, então clicar em Outbrain.
Clique em adicionar, e preencha as informações do pixel e evento que acabou de criar na Outbrain.
Você pode adicionar até 5 eventos por produto, com nomes e combinações diferentes. Basta repetir o processo e configurar cada um.
Por exemplo, pode ter um evento para visitas ao checkout, e outro para compras aprovadas.
Você pode usar sempre o mesmo Pixel ID (OB\_ADV\_ID), e apenas criar diferentes eventos de conversão na Outbrain segundo os seus objetivos.
### Testando o pixel da Outbrain
Você pode usar a extensão Outbrain Pixel Tracker no Google Chrome. Faça o download abaixo:
[https://chrome.google.com/webstore/detail/outbrain-pixel-tracker](https://chrome.google.com/webstore/detail/outbrain-pixel-tracker/daebadnaphbiobojnpgcenlkgpihmbdc?hl=en)
\
# Pixel do TikTok
### Como configurar o pixel do TikTok
A plataforma da GoPag integra com o pixel do TikTok. O primeiro passo é coletar o código do seu pixel TikTok, para depois configurar na GoPag.
### Coletando o seu Pixel no TikTok
No **Ads Manager do TikTok**, clique no menu **Ferramentas**, depois em **Evento**.
Então, clique na opção **Gerenciar** em **Eventos para web**.
Depois em **Configurar eventos web -> Configuração manual** e, então, adicione um nome para o seu pixel.
 
Após isso, será necessário pular a etapa de criação do funil, visto que a plataforma da GoPag irá captar os eventos de maneira automática. Depois, selecione a opção "Código personalizado" e prossiga. Isso é necessário para o pixel funcionar com a GoPag.
Clique em **Exibir instruções** e copie o código gerado.
Exemplo de código:
É necessário agora extrair o pixel ID. Seguindo o exemplo acima, o ID extraído seria esse: **CAUALHRC77U7KHVMKB4G**.
{% hint style="warning" %}
**Importante:** Lembrando que o exemplo acima é fictício, é necessário criar o próprio pixel ID.
{% endhint %}
Pronto, esse é o seu pixel ID do TikTok.
### Colocando o Pixel ID do TikTok na plataforma da GoPag
Agora na plataforma da GoPag, acesse **Produtos -> Selecione o seu produto -> Configurações**, clique na opção do TikTok e cole o Pixel ID lá.
Após isso, é possível salvar o produto.
### Como adicionar uma porcentagem de conversão personalizada para pix e boletos gerados?
É possível selecionar a porcentagem do valor do pix ou boleto para que ele tenha a conversão personalizada, gerando o evento de **Complete Payment**.
Essa ferramenta irá otimizar as campanhas, visto que auxilia a estimar uma porcentagem de conversão e qual valor de venda deve ser enviado ao TikTok Ads.
Veja o exemplo abaixo em que selecionamos a porcentagem de 50% do valor do boleto para enviar o evento de **Complete Payment**.
Para ativar essa função, é necessário habilitar abaixo do Pixel ID.
### Quais eventos a plataforma da GoPag envia para o Pixel?
* **Initiate Checkout** (Quando alguém visita o checkout).
* **Complete payment** (Compra aprovada no cartão ou PIX).
Por padrão, não disparamos o evento **Complete payment** para boleto gerado, mas é possível habilitar essa opção.
\
# Pixel Kwai
### Como configurar o Pixel do Kwai
A plataforma da GoPag integra com o pixel do Kwai. O primeiro passo é coletar o código do seu pixel Kwai, para depois configurar na GoPag.
### Coletando o seu Pixel no Kwai
No **Ads Manager** do Kwai, clique no menu **Assets**, depois em **Pixel**.
Então, clique na opção **Create New Pixel**.
Na tela seguinte, insira o nome do seu pixel, selecione a opção **Developer Mode** e clique em **Create**. Isso é necessário para o Pixel funcionar com a plataforma da GoPag.
Clique em **Copy** para copiar o código do seu pixel.
Ao final do código, localize o seu **Pixel ID** como no exemplo:
Seguindo o exemplo acima, o ID extraído seria esse: **410984069679040162**
{% hint style="warning" %}
**Importante:** Para a integração funcionar, é necessário gerar o seu próprio ID, este é apenas um exemplo.
{% endhint %}
Pronto, agora tem o seu Pixel ID do Kwai!
### Colocando o Pixel ID do Kwai na plataforma da GoPag
Agora na plataforma da GoPag, acesse **Produtos -> Selecione o seu produto -> Configurações**, clique na opção do Kwai e cole o Pixel ID lá.
Após isso, é possível salvar o seu produto.
### Como adicionar uma porcentagem de conversão personalizada para pix e boletos gerados?
É possível selecionar a porcentagem do valor do pix ou boleto para que ele tenha a conversão personalizada, gerando o evento de **Purchase**.
Essa ferramenta irá otimizar as campanhas, visto que auxilia a estimar uma porcentagem de conversão e qual valor de venda deve ser enviado ao Kwai Ads.
Veja o exemplo abaixo em que selecionamos a porcentagem de 50% do valor do boleto para enviar o evento de **Purchase**.
Para ativar essa função, é necessário habilitar abaixo do Pixel ID.
### Quais eventos a plataforma da GoPag envia para o Pixel?
* **Add to Cart** (Quando alguém visita o checkout).
* **Initiated Checkout** (Quando alguém visita o checkout).
* **Purchase** (compra aprovada no cartão ou PIX).
Por padrão, não disparamos o evento **Purchase** para boleto gerado, mas é possível habilitar essa opção.
{% hint style="warning" %}
**Importante:** Os eventos serão marcados no Kwai somente se houver campanhas ativas com o seu pixel.
{% endhint %}
### Como verificar se meu pixel do Kwai está funcionando?
Existe um Plugin para o Google Chrome que te ajuda a verificar o seu Pixel. Você pode fazer o download no link abaixo:
[https://chromewebstore.google.com/detail/kwai-pixel-helper](https://chromewebstore.google.com/detail/kwai-pixel-helper/egbeiaidfnjbliaaoijfcnopfopcnkbd)
Após instalado, acesse o link do seu checkout e selecione o ícone do Kwai Pixel Helper no canto superior direito do seu navegador para ver o Pixel encontrado.
Você pode ver na imagem acima alguns dos eventos que são enviados, com os detalhes da compra. A mensagem em laranja não afeta o envio dos eventos!
# Planos GoPag
Ficou interessado no sistema?
Ainda não faz uso da plataforma?
Então, não perca tempo e fale com o comercial, há a melhor condição disponível.
Clique no link abaixo e será encaminhado para um dos atendentes, para escolher a opção mais adequada para a necessidade. 😉👍
# Maquininha no celular
## O que é o Aplicativo GoPag?
A GoPag é uma empresa inovadora no mercado de meios de pagamento, oferecendo um aplicativo que permite a inserção da sua marca nos serviços prestados. Comprometida em oferecer soluções eficientes e econômicas para empresas e negócios. Com taxas competitivas e transparentes, nosso objetivo é garantir que o empreendedor tenha o melhor custo-benefício ao processar suas transações financeiras.
Além das taxas competitivas, a GoPag se orgulha de sua política de transparência. Nossos clientes têm acesso a todas as informações relacionadas às transações, taxas e prazos de recebimento, proporcionando um maior controle financeiro e eliminando possíveis preocupações.
Explore as próximas páginas e conheça tudo o que o aplicativo pode oferecer! 😉👍
# Login / Cadastro
## 🔹 Registro no GoPag
Para criar sua conta no aplicativo GoPag, toque em **Cadastro** e preencha os dados solicitados. Após o envio, siga as instruções para ativação da conta.
## 🔹 Login no GoPag
Para acessar sua conta, informe o e‑mail e a senha cadastrados. Caso tenha esquecido a senha, utilize a opção **Esqueceu a senha? Clique aqui** para redefini‑la.
## 🔹 Trocar de Conta no GoPag
Caso deseje acessar outra conta no aplicativo, você pode realizar a troca de forma simples e rápida. Para isso, toque nos três pontinhos no canto superior direito da tela e selecione a opção Gerenciar usuários.
Em seguida, você poderá adicionar um novo usuário ou remover uma conta existente, conforme necessário.
Após clicar em adicionar novo usuário, você será direcionado para a tela de login, onde deverá inserir os dados da conta desejada.
Na própria tela de login, também é possível gerenciar e selecionar a conta que deseja acessar.
# Dashboard
## 🔹 Informações Principais
Na primeira seção da tela inicial você visualiza o saldo disponível de forma rápida e clara. Temos também atalhos para visualizar as **Transações Aprovadas**, **Transações Pendentes**, **Transações canceladas**, **Transações canceladas**, **Transações falhadas**.
## 🔹 Atalhos e serviços
A área de serviços reúne atalhos para as principais funcionalidades do aplicativo:
* **Tap to Pay** — cobrar com dispositivo compatível;
* **Criar cobrança** — emitir links ou cobranças avulsas;
* **Simular venda** — testar fluxo de vendas;
* **Recebimentos** — vêr o fluxo financeiro por data;
* **Configurações** — ajustar dados da conta;
* **Suporte** — abrir chamados e obter ajuda.
# Tap to Pay
## 🔹 Cartão de Crédito
Para cobrar com cartão de crédito:
1. Informe o valor da cobrança.
2. Selecione **Cartão de Crédito** como forma de pagamento.
3. Opcionalmente, selecione o número de parcelas.
4. Toque em **Confirmar** para abrir a tela do Tap to Pay e concluir a transação.
## 🔹 Cartão de débito e Pix
Para cobrar com cartão de débito ou Pix, selecione a forma desejada e toque em **Confirmar** para acessar a tela do Tap to Pay.
## 💰 Repassar taxa para o cliente
Na tela de cobrança com cartão de crédito, existe a opção **“Repassar taxa para o cliente”**.
Ao ativar essa opção:
* O valor das taxas da transação é **incluído no valor final pago pelo cliente**.
* O valor exibido nas parcelas é atualizado automaticamente, mostrando:
* **Valor da parcela**
* **Valor total da compra com taxas incluídas**
### 📌 Como funciona na prática
* **Desativado:**\
A taxa é descontada do valor da venda.\
Exemplo: em uma cobrança de R$ 20,00, você recebe menos devido às taxas.
* **Ativado:**\
O sistema recalcula o valor para que o cliente pague as taxas.\
Exemplo:
* 1x de R$ 20,81
* 2x de R$ 10,57
* etc.
Nesse caso, você recebe o valor integral (R$ 20,00), e a taxa é repassada ao cliente.
{% hint style="warning" %}
**Detalhe:** As taxas apresentadas nesta documentação são meramente ilustrativas. As condições reais podem variar de acordo com o perfil do negócio e outros fatores específicos.
Para consultar as taxas atualizadas e aplicáveis ao seu caso, acesse o aplicativo.
Ressaltamos que as taxas podem ser alteradas a qualquer momento, sem aviso prévio.
{% endhint %}
## ✅ Transação aprovada
Após a aproximação do cartão e a autorização do emissor, a transação será concluída com sucesso.
A tela de confirmação exibe:
* Valor da transação
* Forma de pagamento
* Data e hora
* Status da operação
O usuário pode escolher entre:
* **Ver recibo**: visualizar os detalhes completos da transação.
* **Novo pagamento**: iniciar uma nova cobrança.
***
## 🧾 Visualizar recibo
Ao tocar em **Ver recibo**, serão exibidos os detalhes completos da transação, incluindo:
* Valor pago
* Final do cartão
* Tipo da transação
* Data e hora
* ID da transação
* Bandeira do cartão
* Informações técnicas da leitura
***
## 📤 Enviar comprovante
Para compartilhar o comprovante com o cliente, toque em **Enviar comprovante**.
***
## 📧 Selecionar forma de envio
Ao tocar em **Enviar comprovante**, será exibida uma janela para seleção da forma de compartilhamento.
As opções disponíveis são:
* **WhatsApp**
* **E-mail**
Ao selecionar **E-mail**, informe o endereço desejado e toque em **Enviar** para compartilhar o comprovante.
Também é possível cancelar a operação utilizando o botão **Cancelar**.
***
## ✅ Comprovante enviado
Após o envio do comprovante, o aplicativo exibirá uma mensagem de confirmação na parte inferior da tela informando que o compartilhamento foi realizado com sucesso.
# Criar Cobrança
Para emitir uma cobrança no aplicativo, preencha os campos exibidos na tela de criação:
1. **Nome da cobrança:** descreva o motivo ou referência da cobrança.
2. **Valor:** informe o valor a ser cobrado.
3. **Tipo:** escolha entre **Única** ou **Recorrente**.
4. **Formas de pagamento:** selecione uma ou mais opções (Cartão, Pix, Boleto, etc.).
# Cobrança Recorrente
Ao escolher **Cobrança Recorrente**, será possível configurar a frequência e o período das cobranças conforme a necessidade.
A frequência disponível pode ser:
* **Diária**
* **Semanal**
* **Mensal**
* **Anual**
Também é possível definir o período da recorrência:
* **Data de início** — quando a primeira cobrança será gerada;
* **Data de término** — quando a última cobrança ocorrerá (opcional).
É possível, opcionalmente, adicionar informações adicionais do pagador para personalizar a cobrança.
# Cobrança Única
Ao selecionar **Cobrança Única**, será possível definir o número de parcelas (quando aplicável) e preencher os dados da cobrança.
Opcionalmente, adicione as informações pessoais do pagador (nome, e‑mail, telefone) para facilitar a identificação.
Após configurar os detalhes, toque em **Salvar link de cobrança** para gerar o link de pagamento.
Ao abrir o link da cobrança, a tela exibe as informações detalhadas da cobrança. Na primeira seção são apresentados o status do pagamento, a data e a forma de pagamento.
Na segunda seção você encontra o link de pagamento com opções para abrir, copiar para a área de transferência ou compartilhar por e‑mail e WhatsApp.
Na terceira seção são exibidos os dados do pagador informados no momento da criação do link.
Por fim, a tela mostra as configurações da cobrança e o histórico de transações relacionadas.
# Configurações
### 🔹 Configurações da Conta
Nesta tela, você pode visualizar e gerenciar as informações da sua conta no GoPag.
Na aba **Conta**, são exibidos os **dados do vendedor**, incluindo:
* **CPF/CNPJ**
* **Nome ou Razão Social**
* **ID da conta**
* **Data de abertura da conta**
Essas informações são apresentadas de forma clara para facilitar a conferência dos dados cadastrados.
Além disso, é possível acessar a opção **Minhas taxas**, onde você pode consultar as condições e tarifas aplicadas à sua conta.
Outras abas, como **Recebimento** e **Aparência/Layout**, permitem a configuração de preferências adicionais conforme a necessidade.
### Alterar senha de acesso
No segundo card está a opção **Alterar a senha**. Por segurança, o recurso só fica ativo quando o botão correspondente estiver habilitado. O procedimento é simples: informe a senha antiga e, em seguida, a nova senha.
{% hint style="danger" %}
**Importante:** a senha deve ter no mínimo 8 caracteres, incluindo letra minúscula (a–z), letra maiúscula (A–Z) e número (0–9).
{% endhint %}
# Recebimento
### Configurações de recebimento
Nesta tela, você pode configurar como deseja receber seus valores no GoPag.
No card **Alterar política de recebimento**, é possível definir:
* **Transferência automática ativada ou desativada**
* **Intervalo de transferência** (ex: diário)
* **Valor mínimo para transferência**
Essas opções permitem automatizar o envio dos valores para sua conta bancária de acordo com suas preferências.
Após realizar as alterações desejadas, basta clicar em **Confirmar alteração** para salvar as configurações.
### Conta bancária
Na parte inferior da tela, você encontra a seção de **Conta bancária**, onde é possível cadastrar uma conta para recebimento dos valores.
Para isso, clique em **Cadastrar conta** e preencha os dados solicitados.
### Cadastro de conta bancária
Nesta tela, você pode cadastrar uma conta bancária para receber os valores das suas transações no GoPag.
Para isso, é necessário preencher os dados solicitados, incluindo:
* **Banco**
* **Agência bancária**
* **Dígito da agência (DV)**
* **Número da conta**
* **Dígito da conta (DV)**
* **Tipo da conta**
Os campos marcados com (\*) são obrigatórios para o cadastro.
Após preencher todas as informações corretamente, clique em **Cadastrar conta** para concluir o processo.
Caso deseje cancelar a operação, utilize o botão **Cancelar**.
# Aparencia e layout
Nesta tela, você pode personalizar a aparência do seu ambiente no GoPag.
No card **Logo da empresa**, é possível realizar o upload ou alterar o logotipo da sua empresa, que será exibido no sistema whitelabel.
Para adicionar uma imagem, clique em **Adicionar imagem** e selecione o arquivo desejado.
São aceitos os formatos:
* **PNG**
* **JPEG**
* **SVG**
O tamanho máximo permitido para o arquivo é de **5MB**.
Essa funcionalidade permite personalizar a identidade visual do sistema de acordo com a sua marca.
# Suporte
Se encontrar algum problema ou comportamento inesperado no aplicativo, entre em contato com nossa equipe de suporte para que possamos ajudar o mais rápido possível.
Ao abrir um chamado, descreva o problema com detalhes (passos executados, telas afetadas e, se possível, prints). Essas informações agilizam a investigação e a solução.
Também é possível enviar um e‑mail para: . Sempre inclua uma descrição clara do problema e, quando aplicável, os prints que ilustram a situação.
# Maquininhas GoPag
Bem-vindo à documentação das Maquininhas GoPag!
Selecione o modelo da maquininha para acessar o guia completo:
## 📱 Modelos Disponíveis
### [S920 - Maquininha GoPag](/maquininhas/s920)
Maquininha tradicional com todas as funcionalidades para processar pagamentos com cartão de crédito e débito.
**Recursos:**
* Pagamentos com cartão (crédito e débito)
* Parcelamento
* Impressão de comprovantes
* Conexão Wi-Fi
* Relatórios detalhados
***
### [SMART - Maquininha Smart GoPag](/maquininhas/smart)
Maquininha inteligente com recursos avançados e tela touch.
**Recursos:**
* Interface touch screen
* Pagamentos com cartão
* Parcelamento
* Impressão de comprovantes
* Design moderno
***
## 📚 Precisa de Ajuda?
Consulte a seção [🆘 Suporte](/portal_gopag/suporte) para obter assistência adicional.
# S920
Experimente a liberdade financeira com nossas maquininhas e taxas competitivas, e transforme seus resultados de vendas! 😉👍
Sem surpresas nas taxas e custos adicionais, ao escolher a GoPag, você tem a garantia de um serviço que prioriza a economia e a simplicidade na gestão financeira do seu negócio. Diga adeus às surpresas desagradáveis e às letras miúdas, e abrace a confiança e a tranquilidade proporcionadas pela nossa solução em pagamentos.
# Conheça sua maquininha
**Maquininha GoPag S920**
| | |
| ----------------------- | ------------------------------ |
| 1) Teclado Completo | 5) Tela touch screen |
| 2) Botão de Confirmação | 6) Local da Impressão e Bobina |
| 3) Botão de Apagar | 7) Local Cartão de Tarja |
| 4) Botão de Cancelar | 8) Local para Inserir o Cartão |
# Como ligar sua maquininha
| 01 - Ligar a Maquininha | 02 - Desligar a maquininha |
| -------------------------------------------- | -------------------------------------------- |
| Pressione o botão de cancelar por 3 segundos | Pressione o Botão de Cancelar por 3 segundos |
# Trocar bobina da maquininha
**Passo 01 -** Empurre a trava da tampa para cima e abra o compartimento da bobina.
**Passo 02 -** Retire o restante da bobina e coloque uma bobina nova.
**Passo 03 -** Trave a tampa pressionando ela para baixo, e está pronto!
# Realizar uma venda
**Passo 1 -** Para iniciar uma venda, na tela inicial, clique no botão "Confirmar".
**Passo 2 -** Digite o valor da venda utilizando o teclado numérico, após isso, clique em "Confirmar".
**Passo 3 -** Selecione o tipo de pagamento:
1. Para vender no Débito.
2. Para vender no Crédito.
3. Para vender Parcelado.
**Passo 4 -** Peça para que o cliente aproxime ou insira o cartão e digite a senha para finalizar a venda.
# Venda parcelada
**Passo 1 -** Inicie uma venda. Digite o valor da venda utilizando o teclado numérico, após digitar o valor, clique em "Confirmar".
**Passo 2 -** Selecione a opção 03 para pagamento parcelado.
**Passo 3 -** Digite o número de parcelas utilizando o teclado numérico, após digitar o número de parcelas clique em "Confirmar".
**Passo 4 -** Peça para que o cliente aproxime ou insira o cartão e digite a senha para finalizar a venda.
# Estornando uma Venda
**Passo 1 -** Clique na tela em "2.FUNÇÕES" ou tecle 2.
**Passo 2 -** Digite sua senha utilizando o teclado numérico para acessar o menu de funções.
**Passo 3 -** Selecione a primeira opção "1- Cancelar venda" ou tecle 1.
**Passo 4 -** Aproxime ou insira o cartão que deseja estornar a venda.
**Passo 5 -** Selecione a venda que deseja estornar o pagamento e clique em "Confirmar".
# Economizando Bateria
**Passo 1 -** Clique na tela em "1. MENU" ou tecle o número 1 na página inicial.
**Passo 2 -** Clique no botão "" para ver mais opções.
**Passo 3 -** Clique em "1- Ajustes" ou tecle o número 1.
**Passo 4 -** Clique em "3- Brilho" ou tecle o número 3.
**Passo 5 -** Utilize os botões "+" e "-" para aumentar e diminuir o brilho, quanto menor for o valor mais tempo a bateria irá durar.
# Conectar Wi-fi
**Passo 1 -** Acesse o menu clicando em "1. MENU" ou tecle o número 1 na página inicial.
**Página 2 -** Selecione a opção "2 - Conexões" ou tecle o número 2.
**Página 3 -** Selecione a opção "1 - WIFI" ou tecle o número 1
**Página 4 -** Selecione sua rede wifi, digite a senha e tecle "Confirmar"
# Relatórios
**Passo 1 -** Acesse o menu clicando em "1. MENU" ou tecle o número 1 na página inicial.
**Passo 2 -** Selecione a opção "3- Relatórios" ou tecle o número 3.
**Passo 3 -** Selecione uma das 3 opções de como quer ver seu relatório.
**Passo 4 -** Selecione o dia para consultar o seu relatório.
# 🔄️ Reimpressão da Via
**Passo 1 -** Acesse o menu clicando em "1. MENU" ou tecle o número 1 na página inicial.
**Passo 2 -** Selecione a opção "4- Reimpressão de via" ou tecle o número 4.
**Passo 3-** Selecione se quer reimprimir para o "1- Estabelecimento" ou "2- Cliente" e aguarde a reimpressão da via.
# Fechamento de Turno
**Passo 1 -** Acesse o menu clicando em "1. MENU" ou tecle o número 1 na página inicial.
**Passo 2 -** Selecione a opção "5- Fechamento de turno" ou tecle 5.
**Passo 3 -** Confira a data e horário do Início do turno.
**Passo 4 -** Selecione a opção "1. Fechar turno" para fechar o turno na hora atual.
# SMART
Experimente a liberdade financeira com nossas maquininhas smart e transforme seus resultados de vendas! 😉👍
Sem surpresas nas taxas e custos adicionais, ao escolher a GoPag, você tem a garantia de um serviço que prioriza a economia e a simplicidade na gestão financeira do seu negócio.
Diga adeus às surpresas desagradáveis e às letras miúdas, e abrace a confiança e a tranquilidade proporcionadas pela nossa solução em pagamentos.
# Conheça sua maquininha smart
**Maquininha GoPag GPOS720**
| | |
| ------------------------------ | ------------------------------ |
| 1) Local da Impressão e Bobina | 5) Área leitor sem contato NFC |
| 2) Botão de Ligar/Desligar | 6) Local Cartão de Tarja |
| 3) Botão de Volume | 7) Local para Inserir o Cartão |
| 4) Tela touch screen | |
# Como ligar sua maquininha smart
| 01 - Ligar a Maquininha | 02 - Desligar a maquininha |
| ----------------------------------------- | -------------------------------------- |
| Pressione o botão de power por 3 segundos | Pressione o Botão power por 3 segundos |
# Trocar bobina da maquininha smart
**Passo 01 -** Para abrir o compartimento da bobina, levante a alavanca localizada na parte traseira e movimente a tampa da impressora para cima.
**Passo 02 -** Retire o restante da bobina e coloque uma bobina nova , deixando um pedaço para fora do compartimento. livrando as partes amassadas, e corte o excesso para começar a impressão.
**Passo 03 -** Trave a tampa pressionando ela para baixo, e está pronto!
# Realizar uma venda
**Passo 1 -** Para iniciar uma venda, na tela inicial, clique no botão "Iniciar venda".
\
**Passo 2 -** Digite o valor da venda utilizando o teclado numérico, após isso, clique em "Confirmar".
**Passo 3 -** Selecione o tipo de pagamento:
1. Débito à vista.
2. Crédito à vista.
3. Crédito Parcelado.
4. Pix QR Code.
\
**Passo 4 -** Peça para que o cliente aproxime ou insira o cartão e digite a senha para finalizar a venda.
\
**Passo 5 -** Pronto, venda finalizada, pode clicar no botão "Via do cliente" e imprimir a via dele.
# Venda parcelada
**Passo 1 -** Inicie uma venda. Digite o valor da venda utilizando o teclado touchscreen. Após digitar o valor, clique em "Confirmar".
\
**Passo 2 -** Selecione a terceira opção para pagamento Crédito parcelado.
\
**Passo 3 -** Digite o número de parcelas utilizando o teclado numérico, após digitar o número de parcelas clique em "Confirmar".
\
**Passo 4 -** Peça para que o cliente aproxime ou insira o cartão e digite a senha para finalizar a venda.
# Estornando uma Venda
\
**Passo 1 -** Clique na tela em **1.Menu de opções**, e digite a senha de administrador.
\
**Passo 2 -** Selecione a segunda opção **"****2. Estornar venda****"**
\
**Passo 3 -** Clique sobre a venda que deseja fazer o estorno/cancelamento.
\
**Passo 4 -** Aproxime ou insira o cartão que deseja estornar a venda.
\
**Passo 5 -** Pronto, estorno realizado, o valor será devolvido ao cliente.
# 🔄️ Reimpressão da Via
\
**Passo 1 -** Acesse o menu clicando em "1. Menu de Opções" na página inicial e digitando a senha.
\
**Passo 2 -** Selecione a opção "1. Reimpressão de via".
\
**Passo 3 -** Selecione qual venda deseja fazer a reimpressão.
\
**Passo 4 -** Selecione se quer reimprimir para o "Negócio" ou "Cliente" e aguarde a reimpressão da via.
# Desenvolvedores/Integrações
Bem-vindo à documentação oficial da GoPag API! Esta API foi desenvolvida para facilitar a integração de soluções de pagamento em sua aplicação.
## 🎯 Objetivo
Prover uma camada de abstração e segurança para acesso aos serviços de pagamento da GoPag, permitindo que:
* **Partner (Marketplaces)** integrem seus sistemas com a plataforma de pagamentos e gerenciem seus sellers e transações de forma isolada e segura
* **Clientes Finais** acessem funcionalidades de pagamento de forma simplificada
## 🔐 Modelo de Autenticação e Segurança
### Marketplace Token (Atual)
O sistema utiliza um modelo de **marketplace virtual** onde cada parceiro possui:
* **Token de Marketplace**: Autenticação via OAuth2 (Bearer token) com certificado mTLS
* **Escopo Limitado**: Acesso restrito apenas aos sellers dentro do escopo do partner
* **Marketplace Virtual**: Cada parceiro opera em seu próprio "marketplace" com gestão independente
## 🚀 Principais Funcionalidades
### 📊 Gestão de Transações
* Criação de transações (cartão, boleto, Pix)
* Consulta de transações individuais e em lote
* Captura de transações pré-autorizadas
* Histórico completo de transações por seller
### 🖥️ Gestão de Terminais
Gerenciamento de dispositivos de pagamento:
* **Físicos**: Maquininhas tradicionais
* **Virtuais**:
* Tap2Pay (pagamento por aproximação)
* Aplicativos Android/iOS
* Pareamento de terminais
* Monitoramento de status
### 👥 Gestão de Sellers
* Listagem de sellers do marketplace
* Consulta de dados individuais
* Busca por CPF/CNPJ
### 💳 Gestão de Compradores (Buyers)
* CRUD completo de compradores
* Busca por CPF/CNPJ
* Validação de dados cadastrais
## 🔄 Fluxos de Pagamento Suportados
### Fluxo Tradicional
* **Cartão de Crédito/Débito**: Transações com captura imediata ou posterior
* **Boleto Bancário**: Geração e consulta de boletos
* **Pix**: Pagamentos instantâneos via QR Code ou Pix Copia e Cola
### Fluxo Inteligente
* **Cadastro de Link de Pagamento**: Criação automatizada de métodos de pagamento
* **Tap2Pay**: Integração nativa para pagamentos por aproximação
## 📚 Índice
### Introdução e Aspectos Gerais
* [Introdução](/developers/introducao/visao-geral)
* [Requisitos de Segurança](/developers/introducao/requisitos-seguranca)
* [Autenticação](/developers/introducao/autenticacao)
* [Testando a API](/developers/introducao/testando)
* [Códigos de Erro](/developers/introducao/codigos-erro)
### Cadastro e Credenciamento
#### Vendedores
* [Listando Vendedores](/developers/cadastro/vendedores/listar)
* [Buscando Vendedor por CPF/CNPJ](/developers/cadastro/vendedores/buscar-cpf-cnpj)
* [Recuperar Detalhes de Vendedor](/developers/cadastro/vendedores/detalhes)
* [Categoria MCC (Merchant Category Codes)](/developers/cadastro/vendedores/mcc)
#### Compradores
* [Gerenciar Compradores](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/cadastro/compradores/compradores.md)
### Transações
* [Listar Transações](/developers/transacoes/listar)
* [Recuperar Detalhes de Transação](/developers/transacoes/detalhes)
* [Capturar Transação](/developers/transacoes/capturar)
* [Tokenizar Cartão](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/transacoes/tokenizar.md)
#### Criar Transação - Via API
* [Cartão de Crédito/Débito](/developers/transacoes/criar-transacao-sem-checkout/cartao)
* [PIX](/developers/transacoes/criar-transacao-sem-checkout/pix)
* [Boleto e Bolepix](/developers/transacoes/criar-transacao-sem-checkout/boleto)
#### Criar Transação - Payment Locales
* [MPOS](/developers/transacoes/criar-transacao-maquininhas-e-celular/mpos)
* [Tap to Pay (NFC)](/developers/transacoes/criar-transacao-maquininhas-e-celular/tap-to-pay)
* [PINPAD](/developers/transacoes/criar-transacao-maquininhas-e-celular/pinpad)
* [Link de Pagamento](/developers/transacoes/criar-transacao-checkout-gopag/link-pagamento)
## 🚀 Começando
Para começar a usar a GoPag API, você precisará:
1. **Bearer Token**: Obtido via Portal GoPag ou enviado pela GoPag (Entre em contato para solicitar)
2. **Certificado mTLS**: Certificado ICP-Brasil para autenticação bidirecional
3. **Marketplace ID**: Identificador único do seu marketplace
4. **Ambiente**: URLs de homologação e produção
Consulte a seção [Autenticação](/developers/introducao/autenticacao) para mais detalhes.
## 🔒 Segurança
A GoPag API utiliza:
* **Bearer Token**: Autenticação via OAuth 2.0
* **mTLS (Mutual TLS)**: Autenticação bidirecional com certificados ICP-Brasil
* **Isolamento por Marketplace**: Cada marketplace só acessa seus próprios dados
## 📞 Suporte
Para suporte técnico, dúvidas sobre integração ou solicitação de credenciamento:
📧 Email:
# Introdução
# Visão Geral
## O que é a GoPag API?
A GoPag API é uma solução completa para processamento de pagamentos que permite a integração de múltiplos métodos de pagamento em sua aplicação. Com suporte a cartões de crédito/débito, boletos, PIX e dispositivos físicos (MPOS, PINPAD, Tap to Pay), nossa API oferece flexibilidade e segurança para seu negócio.
## Características Principais
### 🔐 Segurança de Nível Empresarial
* Autenticação OAuth 2.0 com Bearer Token
* Certificados ICP-Brasil (mTLS) para autenticação bidirecional
* Isolamento completo entre marketplaces
* Criptografia end-to-end
### 💳 Múltiplos Métodos de Pagamento
#### Pagamentos Online (API)
* **Cartão de Crédito**: Até 12x parcelamento
* **Cartão de Débito**: Pagamento à vista
* **Boleto**: Com ou sem PIX (Bolepix)
* **PIX**: Pagamento instantâneo
* **Link de Pagamento**: Interface pronta para compartilhar com clientes
#### Dispositivos Físicos
* **Tap to Pay**: Pagamento por aproximação via smartphone
* **MPOS**: Maquininha mobile conectada via Bluetooth
* **PINPAD**: Terminal fixo com digitação de senha
### 📊 Recursos Avançados
* **Tokenização de Cartões**: Armazene cartões de forma segura para reuso
* **Split de Pagamento**: Divida automaticamente entre múltiplos recebedores
* **3D Secure**: Autenticação adicional para maior segurança
* **Captura Manual**: Autorize agora, capture depois
* **Metadata Customizado**: Adicione informações personalizadas às transações
## Arquitetura da API
A GoPag API segue o padrão REST com respostas no formato HAL+JSON (Hypertext Application Language).
### Base URLs
```
Homologação: https://api-stage.gopag.com.br
Produção: https://api.gopag.com.br
```
### Versionamento
A API utiliza versionamento na URL:
```
/v1/marketplaces/{marketplace_id}/...
```
Sempre recomendamos usar a versão mais recente para ter acesso aos recursos mais novos.
## Estrutura de Requisição
Todas as requisições devem incluir:
1. **Authorization Header**: Bearer Token (obtido via Portal GoPag ou consultor)
2. **Certificado mTLS**: Certificado ICP-Brasil para autenticação bidirecional
3. **Content-Type**: `application/json` para requisições POST/PATCH
4. **Accept**: `application/json` para respostas
### Exemplo de Headers
```http
POST /v1/marketplaces/abc123.../transactions HTTP/1.1
Host: api.gopag.com.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json
Accept: application/json
```
## Estrutura de Resposta
As respostas seguem o formato HAL+JSON com campos padronizados:
```json
{
"resource": "transaction",
"uri": "/v1/marketplaces/.../transactions/123",
"id": "abc123def456...",
"status": "succeeded",
"amount": 10000,
"currency": "BRL",
"created_at": "2025-12-21T10:30:00Z",
"updated_at": "2025-12-21T10:30:15Z"
}
```
### Coleções (Listas)
```json
{
"resource": "list",
"uri": "/v1/marketplaces/.../sellers",
"items": [...],
"total": 150,
"limit": 20,
"offset": 0,
"has_more": true
}
```
## Valores Monetários
Todos os valores monetários são representados em **centavos** (inteiros):
* R$ 100,00 = `10000`
* R$ 1,50 = `150`
* R$ 0,99 = `99`
## Formatos de Data
Todas as datas seguem o padrão ISO 8601:
```
2025-12-21T10:30:00Z
```
## Próximos Passos
1. [Configure sua autenticação](/developers/introducao/autenticacao)
2. [Entenda os requisitos de segurança](/developers/introducao/requisitos-seguranca)
3. [Teste sua primeira requisição](/developers/introducao/testando)
4. Comece a integrar:
* [Cadastre vendedores](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/vendedores/listar.md)
* [Cadastre compradores](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/compradores/criar.md)
* [Crie sua primeira transação](/developers/transacoes/criar-transacao-sem-checkout/cartao)
# Requisitos de Segurança
A segurança é fundamental para o processamento de pagamentos. A GoPag API implementa múltiplas camadas de proteção para garantir a integridade e confidencialidade dos dados.
## 🔐 Camadas de Segurança
### 1. Bearer Token (OAuth 2.0)
Token de autenticação fornecido via Portal GoPag ou enviado pela GoPag (Entre em contato para solicitar)
> **📋 OBTENÇÃO DO TOKEN**
>
> O Bearer Token pode ser obtido de duas formas:
>
> * **Portal GoPag**: Acesse Configurações > API > Exportar Token
> * **Canal de Suporte/Consultor**: Token enviado via e-mail ou canal seguro
>
> 📧 Contato:
#### Características
* **Tipo**: Bearer
* **Uso**: Header `Authorization` em todas as requisições
* **Validade**: Configurável (geralmente longa duração)
#### Usando o Token
Inclua o token no header `Authorization`:
```http
GET /v1/marketplaces/abc123.../sellers HTTP/1.1
Host: api.gopag.com.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
```
### 2. mTLS (Mutual TLS) - Certificado ICP-Brasil
Autenticação bidirecional através de certificados digitais.
> **📋 CREDENCIAMENTO NECESSÁRIO**
>
> Para integrar com a GoPag API, você precisará de um **certificado digital ICP-Brasil** (e-CPF ou e-CNPJ).
>
> Entre em contato com nossa equipe de suporte para iniciar o processo de credenciamento.
>
> 📧 Email:
#### Como Funciona
1. **Cliente se autentica**: Apresenta certificado digital ICP-Brasil
2. **Servidor valida**: Verifica a autenticidade do certificado
3. **Servidor se autentica**: Apresenta seu próprio certificado
4. **Cliente valida**: Verifica a autenticidade do servidor
5. **Conexão estabelecida**: Canal criptografado bidirecional
#### Certificado do Cliente
* Formato: Certificado Digital ICP-Brasil (e-CPF ou e-CNPJ)
* Padrão: X.509 PEM
* Algoritmo: RSA 2048 bits ou superior
* Emissão: Fornecido pela equipe GoPag após credenciamento
* Serial Number: Deve corresponder ao `marketplace_id`
**⚠️ IMPORTANTE**: O `certSerialNumber` do certificado **DEVE** ser igual ao `marketplace_id` usado na URL. Esta é uma verificação crítica de segurança.
### 3. Isolamento por Marketplace
Cada marketplace possui acesso isolado aos seus próprios recursos:
* ✅ **Permitido**: Acessar apenas sellers do seu marketplace
* ❌ **Bloqueado**: Acessar sellers de outros marketplaces
* ✅ **Validado**: `certSerialNumber === marketplace_id` em todas as requisições
#### Exemplo de Isolamento
```http
GET /v1/marketplaces/marketplace-A/sellers HTTP/1.1
Authorization: Bearer token-marketplace-A
✅ SUCESSO - certSerialNumber do certificado = marketplace-A
```
```http
GET /v1/marketplaces/marketplace-B/sellers HTTP/1.1
Authorization: Bearer token-marketplace-A
❌ ERRO 401 - certSerialNumber não corresponde ao marketplace_id
```
## 🔑 Gestão de Credenciais
### Armazenamento Seguro
**Nunca armazene credenciais em:**
* ❌ Código-fonte
* ❌ Repositórios Git
* ❌ Arquivos de configuração versionados
* ❌ Logs de aplicação
* ❌ Banco de dados sem criptografia
**Armazene credenciais em:**
* ✅ Variáveis de ambiente
* ✅ Cofres de segredos (AWS Secrets Manager, Azure Key Vault, etc.)
* ✅ Sistemas de gestão de configuração seguros
* ✅ HSM (Hardware Security Module) para ambientes críticos
### Rotação de Credenciais
Recomendamos rotacionar suas credenciais regularmente:
* **Client Secret**: A cada 90 dias
* **Certificados mTLS**: Anualmente (antes do vencimento)
* **Tokens de Acesso**: Gerados dinamicamente (1 hora de validade)
### Certificado mTLS - Boas Práticas
```bash
# Armazene o certificado e chave em arquivos separados
/etc/ssl/certs/gopag-client.crt # Certificado público
/etc/ssl/private/gopag-client.key # Chave privada
# Defina permissões restritivas
chmod 644 /etc/ssl/certs/gopag-client.crt
chmod 600 /etc/ssl/private/gopag-client.key
# Apenas o usuário da aplicação deve ter acesso
chown app-user:app-group /etc/ssl/private/gopag-client.key
```
## 🛡️ Proteção de Dados Sensíveis
### Dados de Cartão
**NUNCA armazene:**
* ❌ Número completo do cartão (`card_number`)
* ❌ Código de segurança CVV (`security_code`)
* ❌ Trilha magnética
* ❌ PIN do cartão
**Você PODE armazenar:**
* ✅ Token do cartão (ID retornado pela API)
* ✅ Primeiros 4 dígitos (`first4_digits`)
* ✅ Últimos 4 dígitos (`last4_digits`)
* ✅ Data de validade (se necessário para UX)
* ✅ Nome do portador
#### Tokenização
Use a funcionalidade de tokenização para armazenar cartões de forma segura:
```json
{
"source": {
"card": {
"card_number": "4111111111111111",
"holder_name": "João Silva",
"expiration_month": "12",
"expiration_year": "2026",
"security_code": "123"
},
"usage": "reusable"
}
}
```
**Resposta:**
```json
{
"id": "abc123def456...",
"first4_digits": "4111",
"last4_digits": "1111",
"card_brand": "visa"
}
```
Nas próximas transações, use apenas o `id`:
```json
{
"source": {
"card": {
"id": "abc123def456..."
}
}
}
```
### Dados Pessoais (LGPD/GDPR)
Para conformidade com LGPD e GDPR:
#### Minimize a Coleta
* Colete apenas dados necessários para a transação
* Não armazene dados pessoais desnecessariamente
* Use campos opcionais quando apropriado
#### Anonimização
* Remova ou mascare CPF/CNPJ em logs
* Use hash para identificação interna quando possível
* Implemente políticas de retenção de dados
#### Direitos do Titular
* Permita exclusão de dados (DELETE endpoints)
* Forneça acesso aos dados armazenados (GET endpoints)
* Mantenha registro de consentimento
## 🚨 Detecção de Ameaças
### Monitoramento de Segurança
A GoPag monitora continuamente:
* **Tentativas de acesso não autorizado**
* **Padrões anormais de requisições**
* **Uso de certificados revogados**
* **Requisições de IPs suspeitos**
* **Tentativas de força bruta**
### Trace ID
Todas as requisições geram um `trace_id` único para rastreamento:
```json
{
"trace_id": "a1b2c3"
}
```
Use este ID para:
* Debugar problemas
* Reportar incidentes de segurança
* Auditar operações
### Logs de Auditoria
Mantemos logs detalhados de todas as operações:
```json
{
"event": "TRANSACTION_CREATE_START",
"timestamp": "2025-12-21T10:30:00Z",
"trace_id": "a1b2c3",
"marketplace_id": "abc123...",
"user_id": "user123",
"ip_address": "203.0.113.42",
"action": "create_transaction"
}
```
## 🔒 Checklist de Segurança
Antes de ir para produção, verifique:
* [ ] Certificado mTLS configurado e testado
* [ ] Client Secret armazenado em cofre seguro
* [ ] Validação de `marketplace_id` implementada
* [ ] Tokens OAuth renovados automaticamente
* [ ] Dados sensíveis não armazenados localmente
* [ ] Logs não expõem credenciais ou dados de cartão
* [ ] HTTPS obrigatório em todas as comunicações
* [ ] Rate limiting implementado no cliente
* [ ] Tratamento de erros não expõe informações sensíveis
* [ ] Política de rotação de credenciais definida
* [ ] Monitoramento de segurança configurado
* [ ] Plano de resposta a incidentes documentado
## 📞 Reportando Problemas de Segurança
Se você identificar uma vulnerabilidade de segurança:
1. **NÃO** divulgue publicamente
2. Entre em contato imediatamente com
3. Forneça detalhes da vulnerabilidade e steps para reproduzir
4. Aguarde nossa resposta (SLA: 24 horas)
Agradecemos pesquisadores de segurança responsáveis!
## Próximos Passos
* [Configurar Autenticação](/developers/introducao/autenticacao)
* [Testar a API](/developers/introducao/testando)
* [Entender Códigos de Erro](/developers/introducao/codigos-erro)
# Autenticação
A GoPag API utiliza autenticação de dois fatores para garantir a segurança das comunicações:
1. **Bearer Token (OAuth 2.0)**: Obtido via Portal GoPag ou enviado pela GoPag (Entre em contato para solicitar)
2. **Certificado mTLS (ICP-Brasil)**: Autenticação bidirecional com certificado digital
> **📋 CREDENCIAMENTO NECESSÁRIO**
>
> Para integrar com a GoPag API, você precisará de:
>
> * **Bearer Token**: Exportado pelo Portal GoPag ou enviado pelo seu consultor
> * **Certificado digital ICP-Brasil**: e-CPF ou e-CNPJ para mTLS
>
> Entre em contato com nossa equipe de suporte para iniciar o processo de credenciamento.
>
> 📧 Email:
## Fluxo de Autenticação
```
┌──────────┐ ┌─────────────┐
│ Cliente │ │ GoPag API │
└────┬─────┘ └──────┬──────┘
│ │
│ 1. Conexão TLS + Certificado mTLS (ICP-Brasil) │
├──────────────────────────────────────────────────>│
│ │
│ 2. Validação do Certificado │
│<──────────────────────────────────────────────────┤
│ │
│ 3. Requisição API + Bearer Token │
├──────────────────────────────────────────────────>│
│ │
│ 4. Validação Token + marketplace_id │
│ │
│ 5. Resposta │
│<──────────────────────────────────────────────────┤
│ │
```
## Passo 1: Obter Bearer Token
### Via Portal GoPag
1. Acesse o Portal GoPag
2. Navegue até **Configurações > API**
3. Clique em **Exportar Token**
4. Copie o Bearer Token gerado
### Via Consultor
O Bearer Token pode ser enviado diretamente pelo seu consultor GoPag via e-mail ou canal seguro.
### Características do Token
* **Tipo**: Bearer
* **Validade**: Configurável (geralmente longa duração)
* **Uso**: Incluir no header `Authorization` de todas as requisições
```
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
```
## Passo 2: Configurar Certificado mTLS
### Recebimento do Certificado
Após o credenciamento, você receberá da equipe GoPag:
1. **Certificado Digital ICP-Brasil** (`client.crt`)
* Certificado público X.509 formato PEM
* Tipo: e-CPF (pessoa física) ou e-CNPJ (pessoa jurídica)
* Contém o `certSerialNumber` que deve corresponder ao seu `marketplace_id`
2. **Chave Privada** (`client.key`)
* Chave privada RSA 2048 bits ou superior
* **NUNCA compartilhe esta chave**
3. **CA Certificate** (`ca.crt`)
* Certificado da Autoridade Certificadora
**⚠️ IMPORTANTE**: O certificado é emitido exclusivamente pela equipe GoPag após análise e aprovação do credenciamento.
### Instalação
#### Linux/MacOS
```bash
# Criar diretório para certificados
sudo mkdir -p /etc/ssl/gopag
# Copiar certificados
sudo cp client.crt /etc/ssl/gopag/
sudo cp client.key /etc/ssl/gopag/
sudo cp ca.crt /etc/ssl/gopag/
# Definir permissões
sudo chmod 644 /etc/ssl/gopag/client.crt
sudo chmod 644 /etc/ssl/gopag/ca.crt
sudo chmod 600 /etc/ssl/gopag/client.key
sudo chown app-user:app-group /etc/ssl/gopag/client.key
```
#### Verificar Certificado
```bash
# Ver informações do certificado
openssl x509 -in /etc/ssl/gopag/client.crt -text -noout
# Verificar serial number (deve corresponder ao marketplace_id)
openssl x509 -in /etc/ssl/gopag/client.crt -serial -noout
```
### Configuração por Linguagem
#### cURL
```bash
curl https://api.gopag.com.br/v1/marketplaces/abc123.../sellers \
--cert /etc/ssl/gopag/client.crt \
--key /etc/ssl/gopag/client.key \
--cacert /etc/ssl/gopag/ca.crt \
-H "Authorization: Bearer SEU_TOKEN"
```
#### PHP (com cURL)
```php
$ch = curl_init('https://api.gopag.com.br/v1/marketplaces/abc123.../sellers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_SSLCERT => '/etc/ssl/gopag/client.crt',
CURLOPT_SSLKEY => '/etc/ssl/gopag/client.key',
CURLOPT_CAINFO => '/etc/ssl/gopag/ca.crt',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $accessToken,
'Content-Type: application/json'
]
]);
$response = curl_exec($ch);
curl_close($ch);
```
#### Node.js (com axios)
```javascript
const fs = require('fs');
const https = require('https');
const axios = require('axios');
const httpsAgent = new https.Agent({
cert: fs.readFileSync('/etc/ssl/gopag/client.crt'),
key: fs.readFileSync('/etc/ssl/gopag/client.key'),
ca: fs.readFileSync('/etc/ssl/gopag/ca.crt')
});
const response = await axios.get(
'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers',
{
httpsAgent,
headers: {
'Authorization': `Bearer ${accessToken}`
}
}
);
```
#### Python (com requests)
```python
import requests
response = requests.get(
'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers',
cert=('/etc/ssl/gopag/client.crt', '/etc/ssl/gopag/client.key'),
verify='/etc/ssl/gopag/ca.crt',
headers={'Authorization': f'Bearer {access_token}'}
)
```
#### Java (com OkHttp)
```java
OkHttpClient client = new OkHttpClient.Builder()
.sslSocketFactory(sslContext.getSocketFactory(), trustManager)
.build();
Request request = new Request.Builder()
.url("https://api.gopag.com.br/v1/marketplaces/abc123.../sellers")
.header("Authorization", "Bearer " + accessToken)
.build();
Response response = client.newCall(request).execute();
```
## Passo 3: Usar nas Requisições
### Header de Autorização
Inclua o Bearer Token em todas as requisições:
```http
GET /v1/marketplaces/abc123.../sellers HTTP/1.1
Host: api.gopag.com.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Accept: application/json
```
### Validação do Marketplace ID
**CRÍTICO**: O `certSerialNumber` do certificado mTLS **DEVE** corresponder ao `marketplace_id` na URL.
```
✅ Correto:
- certSerialNumber: marketplace-abc123
- URL: /v1/marketplaces/marketplace-abc123/sellers
❌ Erro 401:
- certSerialNumber: marketplace-abc123
- URL: /v1/marketplaces/marketplace-xyz789/sellers
```
## Tratamento de Erros de Autenticação
### 401 Unauthorized
```json
{
"type": "https://httpstatuses.com/401",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid or expired access token"
}
```
**Causas comuns:**
* Bearer Token inválido ou expirado
* Token não fornecido no header
**Solução:**
* Verifique se o token está correto
* Solicite um novo token via Portal GoPag ou consultor
### 401 Unauthorized (Marketplace)
```json
{
"type": "https://httpstatuses.com/401",
"title": "Unauthorized",
"status": 401,
"detail": "Unauthorized"
}
```
**Causas comuns:**
* `certSerialNumber` não corresponde ao `marketplace_id`
* Certificado mTLS inválido ou expirado
**Solução:**
* Verifique se o `marketplace_id` na URL está correto
* Confirme que seu certificado ainda está válido
* Entre em contato com suporte se necessário
### 403 Forbidden
```json
{
"type": "https://httpstatuses.com/403",
"title": "Forbidden",
"status": 403,
"detail": "Insufficient permissions"
}
```
**Causas comuns:**
* Tentando acessar recurso de outro marketplace
* Permissões insuficientes
**Solução:**
* Verifique se está acessando apenas recursos do seu marketplace
* Entre em contato com suporte se necessário
## Segurança - Melhores Práticas
### ✅ Fazer
* Armazenar certificados e chaves em locais seguros
* Usar variáveis de ambiente para Bearer Token
* Validar certificados SSL do servidor
* Usar HTTPS em todas as comunicações
* Implementar timeout em requisições
* Logar tentativas de autenticação (sem expor credenciais)
### ❌ Não Fazer
* Commitar certificados, chaves ou tokens no Git
* Expor Bearer Token em código cliente (frontend)
* Compartilhar credenciais entre ambientes
* Ignorar erros de validação SSL
* Armazenar tokens sem proteção
* Usar certificados expirados
* Fazer hard-code de credenciais
## Ambientes
### Homologação
```
Base URL: https://api-stage.gopag.com.br
```
* Use credenciais de homologação
* Certificado de homologação
* Sem impacto em produção
### Produção
```
Base URL: https://api.gopag.com.br
```
* Use credenciais de produção
* Certificado de produção
* Transações reais
**⚠️ NUNCA use credenciais de produção em homologação!**
## Próximos Passos
* [Testar sua Autenticação](/developers/introducao/testando)
* [Entender Códigos de Erro](/developers/introducao/codigos-erro)
* [Começar a Integração](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/vendedores/listar.md)
# Testando a API
Este guia mostra como realizar seus primeiros testes com a GoPag API.
## Pré-requisitos
Antes de começar, certifique-se de ter:
* ✅ Bearer Token (obtido via Portal GoPag ou consultor)
* ✅ Certificado mTLS (ICP-Brasil) instalado e configurado
* ✅ Marketplace ID fornecido pela GoPag
* ✅ Acesso ao ambiente de homologação
## Ferramentas Recomendadas
### cURL
Disponível nativamente em Linux/MacOS, ou via Git Bash/WSL no Windows.
### Postman
* Download:
* Suporta mTLS nativamente
* Facilita organização de coleções
### Insomnia
* Download:
* Interface simples e intuitiva
* Suporte completo a certificados
## Teste 1: Listar Vendedores
Teste básico para validar autenticação completa (mTLS + Bearer Token).
### Request
```bash
curl --location 'https://api-stage.gopag.com.br/v1/marketplaces/SEU_MARKETPLACE_ID/sellers?limit=10' \
--cert /etc/ssl/gopag/client.crt \
--key /etc/ssl/gopag/client.key \
--cacert /etc/ssl/gopag/ca.crt \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
### Response Esperada
```json
{
"resource": "list",
"uri": "/v1/marketplaces/abc123.../sellers",
"limit": 10,
"offset": 0,
"has_more": false,
"query_count": 2,
"total": 2,
"items": [
{
"id": "17d9e827664b47509f12a082b6047e7a",
"status": "pending",
"resource": "seller",
"type": "business",
"business_name": "Empresa XYZ LTDA",
"ein": "12345678000190",
"created_at": "2025-12-15T10:30:00Z"
}
]
}
```
### ✅ Teste bem-sucedido se:
* Status code: `200 OK`
* Campo `items` retorna array (pode estar vazio)
* Estrutura HAL+JSON válida
## Teste 2: Criar Transação PIX
Teste de criação de transação simples.
### Request
```bash
curl --location 'https://api-stage.gopag.com.br/v1/marketplaces/SEU_MARKETPLACE_ID/transactions' \
--cert /etc/ssl/gopag/client.crt \
--key /etc/ssl/gopag/client.key \
--cacert /etc/ssl/gopag/ca.crt \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"payment_type": "pix",
"on_behalf_of": "SELLER_ID",
"description": "Teste de integração PIX",
"currency": "BRL",
"amount": 1000,
"pix_expiration_date_time": "2025-12-22 23:59:59"
}'
```
### Response Esperada
```json
{
"id": "abc123def456...",
"status": "pending",
"resource": "transaction",
"payment_type": "pix",
"amount": "10.00",
"currency": "BRL",
"description": "Teste de integração PIX",
"on_behalf_of": "SELLER_ID",
"qr_code": "00020126....",
"qr_code_url": "https://...",
"created_at": "2025-12-21T14:30:00Z"
}
```
### ✅ Teste bem-sucedido se:
* Status code: `201 Created`
* Campo `qr_code` presente
* Status inicial: `pending`
## Teste 4: Consultar Transação
Verificar status de transação criada.
### Request
```bash
curl --location 'https://api-stage.gopag.com.br/v1/marketplaces/SEU_MARKETPLACE_ID/transactions/TRANSACTION_ID' \
--cert /etc/ssl/gopag/client.crt \
--key /etc/ssl/gopag/client.key \
--cacert /etc/ssl/gopag/ca.crt \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
### Response Esperada
```json
{
"id": "abc123def456...",
"status": "succeeded",
"resource": "transaction",
"payment_type": "pix",
"amount": "10.00",
"fees": "0.50",
"created_at": "2025-12-21T14:30:00Z",
"updated_at": "2025-12-21T14:35:00Z"
}
```
## Configurando Postman
### 1. Importar Certificados
1. Settings → Certificates → Add Certificate
2. Host: `api-stage.gopag.com.br`
3. CRT file: Selecione `client.crt`
4. KEY file: Selecione `client.key`
5. PFX/P12: (deixe vazio se usar CRT+KEY)
### 2. Criar Environment
```json
{
"base_url": "https://api-stage.gopag.com.br",
"marketplace_id": "abc123...",
"bearer_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
```
### 3. Configurar Authorization
Em cada requisição ou na collection:
1. Authorization → Type: **Bearer Token**
2. Token: `{{bearer_token}}`
## Troubleshooting
### SSL Certificate Error
**Erro:**
```
SSL certificate problem: unable to get local issuer certificate
```
**Solução:**
```bash
# Adicione o CA certificate
curl --cacert /etc/ssl/gopag/ca.crt ...
```
### Bearer Token Inválido
**Erro:**
```json
{
"status": 401,
"detail": "Invalid or expired access token"
}
```
**Solução:**
* Verifique se o Bearer Token está correto
* Solicite novo token via Portal GoPag ou consultor
### Marketplace ID Incorreto
**Erro:**
```json
{
"status": 403,
"detail": "Certificate serial number does not match marketplace_id"
}
```
**Solução:**
* Verifique se `certSerialNumber` do certificado === `marketplace_id` na URL
* Use `openssl x509 -in client.crt -serial -noout` para verificar
### Campos Inesperados
**Erro:**
```json
{
"status": 400,
"detail": "Unexpected fields found: ['campo_invalido']"
}
```
**Solução:**
* A API valida campos estritamente
* Remova campos não documentados do payload
## Próximos Passos
Agora que você testou a API com sucesso:
1. [Criar Transações de Cartão](/developers/transacoes/criar-transacao-sem-checkout/cartao)
2. [Gerenciar Vendedores](/developers/cadastro/vendedores/listar)
3. [Entender Webhooks](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/webhooks/introducao.md)
4. [Códigos de Erro](/developers/introducao/codigos-erro)
## Ambiente de Produção
Quando estiver pronto para produção:
1. ✅ Substitua base URL para `https://api.gopag.com.br`
2. ✅ Use certificado mTLS de **produção**
3. ✅ Use Bearer Token de **produção**
4. ✅ Configure monitoramento e logs
5. ✅ Implemente tratamento de erros robusto
6. ✅ Configure webhooks para notificações
**⚠️ NUNCA use credenciais de produção em homologação!**
# Códigos de Erro
A GoPag API utiliza códigos de status HTTP padronizados e retorna detalhes adicionais no corpo da resposta seguindo o padrão RFC 7807 (Problem Details).
## Estrutura de Erro
Todas as respostas de erro seguem este formato:
```json
{
"type": "https://httpstatuses.com/400",
"title": "Bad Request",
"status": 400,
"detail": "Field payment_type is required",
"trace_id": "a1b2c3"
}
```
### Campos
| Campo | Tipo | Descrição |
| ---------- | ------- | ----------------------------------------- |
| `type` | string | URI que identifica o tipo de erro |
| `title` | string | Resumo legível do erro |
| `status` | integer | Código de status HTTP |
| `detail` | string | Descrição detalhada do erro |
| `trace_id` | string | ID único para rastreamento (6 caracteres) |
## Códigos de Status HTTP
### 2xx - Sucesso
#### 200 OK
Requisição bem-sucedida.
```json
{
"resource": "seller",
"id": "abc123...",
"status": "active"
}
```
#### 201 Created
Recurso criado com sucesso.
```json
{
"resource": "transaction",
"id": "def456...",
"status": "succeeded",
"created_at": "2025-12-21T10:30:00Z"
}
```
### 4xx - Erros do Cliente
#### 400 Bad Request
Requisição inválida ou mal formatada.
**Exemplos:**
```json
{
"type": "https://httpstatuses.com/400",
"title": "Bad Request",
"status": 400,
"detail": "Field payment_type is required",
"trace_id": "a1b2c3"
}
```
```json
{
"type": "https://httpstatuses.com/400",
"title": "Bad Request",
"status": 400,
"detail": "Invalid on_behalf_of (seller_id) format",
"trace_id": "d4e5f6"
}
```
```json
{
"type": "https://httpstatuses.com/400",
"title": "Bad Request",
"status": 400,
"detail": "Unexpected fields in request [g7h8i9]",
"trace_id": "g7h8i9",
"skipped_fields": {
"invalid_field": "value",
"source.card.wrong_field": "value"
}
}
```
**Causas comuns:**
* Campo obrigatório ausente
* Formato de campo inválido (ex: ID não hexadecimal de 32 chars)
* Campos inesperados na requisição
* Valor fora do intervalo permitido
* Tipo de dado incorreto
**Solução:**
* Verifique os campos obrigatórios
* Valide formatos antes de enviar
* Remova campos não documentados
* Consulte a documentação do endpoint
#### 401 Unauthorized
Não autenticado ou credenciais inválidas.
**Exemplos:**
```json
{
"type": "https://httpstatuses.com/401",
"title": "Unauthorized",
"status": 401,
"detail": "Unauthorized"
}
```
```json
{
"type": "https://httpstatuses.com/401",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid or expired access token"
}
```
```json
{
"type": "https://httpstatuses.com/401",
"title": "Unauthorized",
"status": 401,
"detail": "Unauthorized to access this seller [j1k2l3]",
"trace_id": "j1k2l3"
}
```
**Causas comuns:**
* Token OAuth expirado (após 1 hora)
* Token inválido ou ausente
* `certSerialNumber` não corresponde ao `marketplace_id`
* Tentando acessar seller de outro marketplace
* Certificado mTLS inválido
**Solução:**
* Obtenha um novo token OAuth 2.0
* Verifique o `marketplace_id` na URL
* Confirme que o seller pertence ao seu marketplace
* Valide seu certificado mTLS
#### 403 Forbidden
Autenticado, mas sem permissão para acessar o recurso.
```json
{
"type": "https://httpstatuses.com/403",
"title": "Forbidden",
"status": 403,
"detail": "Insufficient permissions"
}
```
**Causas comuns:**
* Tentando acessar recursos de outro marketplace
* Permissões insuficientes no client\_id
**Solução:**
* Verifique se o recurso pertence ao seu marketplace
* Entre em contato com suporte para revisar permissões
#### 404 Not Found
Recurso não encontrado.
```json
{
"type": "https://httpstatuses.com/404",
"title": "Not Found",
"status": 404,
"detail": "Transaction not found"
}
```
```json
{
"type": "https://httpstatuses.com/404",
"title": "Not Found",
"status": 404,
"detail": "Seller not found"
}
```
**Causas comuns:**
* ID incorreto na URL
* Recurso foi deletado
* Recurso pertence a outro marketplace
**Solução:**
* Verifique o ID do recurso
* Confirme que o recurso existe
* Verifique se está usando o marketplace\_id correto
#### 429 Too Many Requests
Rate limit excedido.
```json
{
"type": "https://httpstatuses.com/429",
"title": "Too Many Requests",
"status": 429,
"detail": "Rate limit exceeded. Try again in 60 seconds",
"retry_after": 60
}
```
**Solução:**
* Adicione cache de respostas
* Otimize número de requisições
* Entre em contato com o suporte
### 5xx - Erros do Servidor
#### 500 Internal Server Error
Erro interno do servidor.
```json
{
"type": "https://httpstatuses.com/500",
"title": "Internal Server Error",
"status": 500,
"detail": "Unknown error occurred [m4n5o6]",
"trace_id": "m4n5o6"
}
```
**Causas comuns:**
* Erro inesperado no servidor
* Falha na comunicação com gateway de pagamento
**Solução:**
* Tente novamente após alguns segundos
* Se persistir, reporte usando o `trace_id`
#### 501 Not Implemented
Funcionalidade ainda não implementada.
```json
{
"type": "https://httpstatuses.com/501",
"title": "Not Implemented",
"status": 501,
"detail": "MPOS transaction flow not yet implemented [p7q8r9]",
"trace_id": "p7q8r9",
"validated_data": {...}
}
```
**Causas comuns:**
* Usando `payment_locale` que ainda não está ativo (PINPAD, MPOS, Tap to Pay, Link Payment)
**Solução:**
* Use `payment_locale`: "api" (ou omita o campo)
* Aguarde disponibilidade da funcionalidade
* Entre em contato com suporte para roadmap
#### 502 Bad Gateway
Erro na comunicação com serviço externo.
```json
{
"type": "https://httpstatuses.com/502",
"title": "Bad Gateway",
"status": 502,
"detail": "Error communicating with payment gateway",
"trace_id": "s1t2u3"
}
```
**Causas comuns:**
* Gateway de pagamento indisponível
* Timeout na comunicação
* Erro de rede
**Solução:**
* Tente novamente após alguns segundos
* Implemente retry com backoff exponencial
* Se persistir, reporte o `trace_id`
#### 503 Service Unavailable
Serviço temporariamente indisponível.
```json
{
"type": "https://httpstatuses.com/503",
"title": "Service Unavailable",
"status": 503,
"detail": "Service under maintenance",
"retry_after": 300
}
```
**Causas comuns:**
* Manutenção programada
* Alta carga no sistema
**Solução:**
* Aguarde e tente novamente
* Respeite o header `Retry-After`
## Erros Específicos de Negócio
### Validação de Transação
```json
{
"type": "https://httpstatuses.com/400",
"title": "Bad Request",
"status": 400,
"detail": "Field amount must be a positive number",
"trace_id": "v4w5x6"
}
```
```json
{
"type": "https://httpstatuses.com/400",
"title": "Bad Request",
"status": 400,
"detail": "Invalid payment_type. Allowed values: credit, debit, boleto, bolepix, pix",
"trace_id": "y7z8a9"
}
```
```json
{
"type": "https://httpstatuses.com/400",
"title": "Bad Request",
"status": 400,
"detail": "Field installment_plan.number_installments must be between 1 and 12",
"trace_id": "b1c2d3"
}
```
### Erro do Gateway de Pagamento
Quando o gateway retorna erro, a API repassa a mensagem:
```json
{
"type": "https://httpstatuses.com/400",
"title": "Bad Request",
"status": 400,
"detail": "Cartão com restrição",
"category": "card_error",
"trace_id": "e4f5g6"
}
```
## Tratamento de Erros - Melhores Práticas
### 1. Sempre Verifique o Status HTTP
```javascript
const response = await fetch(url, options);
if (!response.ok) {
const error = await response.json();
console.error(`Error ${error.status}: ${error.detail}`);
console.error(`Trace ID: ${error.trace_id}`);
throw new Error(error.detail);
}
```
### 2. Log do Trace ID
```javascript
catch (error) {
console.error('API Error:', {
status: error.status,
detail: error.detail,
trace_id: error.trace_id, // IMPORTANTE para suporte
timestamp: new Date().toISOString()
});
// Enviar para sistema de monitoramento
sendToMonitoring({
type: 'api_error',
trace_id: error.trace_id,
details: error
});
}
```
### 3. Mensagens Amigáveis para Usuário
```javascript
function getUserFriendlyMessage(error) {
switch (error.status) {
case 400:
return 'Verifique os dados informados e tente novamente.';
case 401:
return 'Sessão expirada. Faça login novamente.';
case 404:
return 'Recurso não encontrado.';
case 429:
return 'Muitas requisições. Aguarde um momento.';
case 500:
case 502:
case 503:
return 'Erro temporário. Tente novamente em instantes.';
default:
return 'Ocorreu um erro inesperado.';
}
}
```
## Trace ID para Suporte
Sempre que reportar um problema ao suporte, inclua:
```
Trace ID: a1b2c3
Timestamp: 2025-12-21T10:30:00Z
Endpoint: POST /v1/marketplaces/abc.../transactions
Status: 500
Mensagem: Unknown error occurred
```
O `trace_id` permite que nossa equipe rastreie o que aconteceu de forma facilitada.
## Próximos Passos
* [Começar a Testar](/developers/introducao/testando)
* [Criar Primeira Transação](/developers/transacoes/criar-transacao-sem-checkout/cartao)
* [Ver Exemplos Completos](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/vendedores/listar.md)
# Cadastro
# Vendedores
# Visão Geral
Gerenciamento completo de vendedores no GoPag API.
## Documentação
### Operações Disponíveis
* [**Criar Vendedor**](/developers/cadastro/vendedores/criar) - Cadastrar pessoa física ou jurídica
* [**Buscar por CPF/CNPJ**](/developers/cadastro/vendedores/buscar-cpf-cnpj) - Localizar vendedor usando documento
* [**Listar Vendedores**](/developers/cadastro/vendedores/listar) - Visualizar todos os vendedores
* [**Detalhes do Vendedor**](/developers/cadastro/vendedores/detalhes) - Recuperar e atualizar informações
* [**MCC (Merchant Category Codes)**](/developers/cadastro/vendedores/mcc) - Códigos de categoria de negócio
***
## Visão Geral
Os vendedores (sellers) são os comerciantes que processam pagamentos através da plataforma. Cada vendedor pode ser:
* **Pessoa Física (PF)**: Empresário individual
* **Pessoa Jurídica (PJ)**: Empresas registradas com CNPJ
### Informações do Vendedor
* **Dados pessoais/empresariais**: Nome, documento, contatos
* **Endereço**: Localização física do negócio
* **Dados bancários**: Contas para recebimento
* **MCC**: Categoria do negócio (ramo de atividade)
* **Status**: Pending, active, suspended
* **Metadata**: Campos customizados
### Fluxo Básico
```
1. Criar Vendedor (PF ou PJ)
↓
2. Aguardar Aprovação/Análise
↓
3. Cadastrar Conta Bancária
↓
4. Vendedor Pronto para Receber Pagamentos
```
***
## Início Rápido
### Criar Vendedor Pessoa Física
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/sellers' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"taxpayer_id": "12345678900",
"email": "vendedor@email.com",
"phone_number": "11987654321",
"first_name": "João Silva"
}'
```
### Criar Vendedor Pessoa Jurídica
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/sellers' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"ein": "12345678000190",
"email": "contato@empresa.com.br",
"phone_number": "1133334444",
"first_name": "Minha Empresa LTDA"
}'
```
### Buscar por CPF
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/sellers/search?taxpayer_id=12345678900' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
### Buscar por CNPJ
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/sellers/search?ein=12345678000190' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
***
## Status do Vendedor
| Status | Descrição |
| ----------- | ------------------------------- |
| `pending` | Aguardando análise/documentação |
| `active` | Aprovado e operacional |
| `suspended` | Temporariamente suspenso |
| `rejected` | Não aprovado |
***
## Validações Importantes
### ✅ Documento Único
* Cada CPF ou CNPJ só pode ter **um vendedor ativo** por marketplace
* Use busca antes de criar para evitar duplicatas
### ✅ Email Único
* Email deve ser único no marketplace
* Recomenda-se validação antes do cadastro
***
## Segurança e Compliance
### 🔒 KYC (Know Your Customer)
Vendedores passam por análise que pode incluir:
* Validação de documentos
* Verificação de endereço
* Análise de risco
* Consulta a bureaus de crédito
### 📋 Documentação Requerida
Dependendo do tipo e volume:
* **PF**: RG, CPF, comprovante de endereço
* **PJ**: Contrato social, CNPJ, documentos do owner
### ⚠️ Conformidade
* Sellers devem estar em conformidade com regulamentações locais
* Transações podem ser bloqueadas se houver problemas
***
## Fluxo de Aprovação
```
┌─────────────────┐
│ Criar Seller │
│ (pending) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Análise KYC │
│ (automática) │
└────────┬────────┘
│
┌────┴────┐
│ │
▼ ▼
┌────────┐ ┌──────────┐
│ Active │ │ Rejected │
└────────┘ └──────────┘
```
***
## Boas Práticas
### ✅ Recomendações
1. **Busque antes de criar**: Evite duplicatas consultando por CPF/CNPJ
2. **Valide documentos**: Use bibliotecas para validar CPF/CNPJ antes de enviar
3. **Preencha dados completos**: Quanto mais informações, mais rápida a aprovação
4. **Email válido**: Use email ativo para notificações importantes
## Próximos Passos
1. [Criar seu primeiro vendedor](/developers/cadastro/vendedores/criar)
2. [Buscar vendedor existente](/developers/cadastro/vendedores/buscar-cpf-cnpj)
3. [Listar vendedores do marketplace](/developers/cadastro/vendedores/listar)
4. [Entender códigos MCC](/developers/cadastro/vendedores/mcc)
***
## Suporte
Dúvidas? Entre em contato:
* 📧 Email:
* 📚 Documentação completa:
* 💬 Chat: Disponível no painel administrativo
# Criar Vendedor
Cadastre vendedores pessoa física (PF) ou pessoa jurídica (PJ) no marketplace.
***
## Endpoint
```
POST /v1/marketplaces/{marketplace_id}/sellers
```
***
## Autenticação
```
Authorization: Bearer {access_token}
```
***
## Tipos de Vendedor
A API suporta dois tipos de vendedores, diferenciados pelo campo de documento enviado:
| Tipo | Campo Documento | Tamanho | Descrição |
| ------------------------ | --------------- | ---------- | ------------------ |
| **Pessoa Física (PF)** | `taxpayer_id` | 11 dígitos | CPF do comerciante |
| **Pessoa Jurídica (PJ)** | `ein` | 14 dígitos | CNPJ da empresa |
> **Importante**: Use **apenas um** dos campos (`taxpayer_id` ou `ein`) por requisição. A presença do campo determina o tipo de vendedor.
***
## Criar Vendedor Pessoa Física (PF)
### Request
```http
POST /v1/marketplaces/{marketplace_id}/sellers
Authorization: Bearer {access_token}
Content-Type: application/json
{
"taxpayer_id": "12345678900",
"email": "suporte@gopag.com.br",
"phone_number": "6236024409",
"first_name": "Jhon exemplo"
}
```
### Campos Obrigatórios (PF)
| Campo | Tipo | Descrição |
| -------------- | ------ | -------------------------------- |
| `taxpayer_id` | string | CPF (11 dígitos, apenas números) |
| `email` | string | Email do vendedor |
| `phone_number` | string | Telefone (DDD + número) |
| `first_name` | string | Nome completo |
### Response (201 Created)
```json
{
"kyc_href":"https://cloud.identifique.se/app-ui/t/t/c7357fd6-4881-11f0-a158-597c4a62c31e",
"detail":"Seller creation process initiated successfully [WIU2C6]"
}
```
***
## Criar Vendedor Pessoa Jurídica (PJ)
### Request
```http
POST /v1/marketplaces/{marketplace_id}/sellers
Authorization: Bearer {access_token}
Content-Type: application/json
{
"ein": "58753292000113",
"email": "suporte@gopag.com.br",
"phone_number": "6236024409",
"first_name": "Gopag Soluções Tecnológicas em Pagamentos Ltda"
}
```
### Campos Obrigatórios (PJ)
| Campo | Tipo | Descrição |
| -------------- | ------ | --------------------------------- |
| `ein` | string | CNPJ (14 dígitos, apenas números) |
| `email` | string | Email da empresa |
| `phone_number` | string | Telefone (DDD + número) |
| `first_name` | string | Razão social ou nome fantasia |
### Response (201 Created)
```json
{
"kyc_href":"https://cloud.identifique.se/app-ui/t/t/c7357fd6-4881-11f0-a158-597c4a62c31e",
"detail":"Seller creation process initiated successfully [WIU2C6]"
}
```
***
## Status do Vendedor
Após criação, o vendedor passa por análise:
| Status | Descrição |
| ----------- | ------------------------------- |
| `pending` | Aguardando análise/documentação |
| `active` | Aprovado e operacional |
| `suspended` | Temporariamente suspenso |
| `rejected` | Não aprovado (motivo fornecido) |
### Fluxo de Aprovação
```
POST /sellers
↓
[pending] → Análise KYC
↓
[active] ou [rejected]
```
***
## Validações
### CPF (taxpayer\_id)
* ✅ Exatamente 11 dígitos numéricos
* ✅ CPF válido (algoritmo de validação)
* ✅ Único na GOPAG
* ❌ Não pode ser CPF em blacklist
### CNPJ (ein)
* ✅ Exatamente 14 dígitos numéricos
* ✅ CNPJ válido (algoritmo de validação)
* ✅ Único na GOPAG
* ❌ Não pode estar inativo na Receita Federal
### Email
* ✅ Formato válido (RFC 5322)
* ✅ Único na GOPAG
* ✅ Domínio existente
### Telefone
* ✅ 10-11 dígitos (DDD + número)
* ✅ DDD válido do Brasil
* ✅ Formato: `11987654321` (sem formatação)
***
## Próximos Passos
Após criar o vendedor:
1. **Aguardar Aprovação**: Monitorar status via polling
2. **Testar Transação**: Realizar uma transação de teste
### Recursos Relacionados
* [Buscar Vendedor por CPF/CNPJ](/developers/cadastro/vendedores/buscar-cpf-cnpj)
* [Listar Vendedores](/developers/cadastro/vendedores/listar)
* [Detalhes do Vendedor](/developers/cadastro/vendedores/detalhes)
* [Códigos MCC](/developers/cadastro/vendedores/mcc)
* [Criar Conta Bancária](/developers/contas-bancarias/criar)
***
## Suporte
Dúvidas? Entre em contato:
* 📧 Email:
* 📚 Documentação:
# Listar Vendedores
Lista todos os vendedores (sellers) vinculados ao seu marketplace.
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/sellers
```
## Parâmetros de Query
| Parâmetro | Tipo | Obrigatório | Descrição |
| --------- | ------- | ----------- | ---------------------------------------------------------------- |
| `limit` | integer | Não | Quantidade de resultados por página (padrão: 100, máximo: 100) |
| `offset` | integer | Não | Número de registros a pular (padrão: 0) |
| `sort` | string | Não | Campo para ordenação (ex: `created_at`, `-created_at` para desc) |
| `status` | string | Não | Filtrar por status: `pending`, `active`, `inactive` |
## Request
### cURL
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers?limit=10&offset=0' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
### PHP
```php
'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers?limit=10',
CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $accessToken
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
?>
```
### Node.js
```javascript
const https = require('https');
const fs = require('fs');
const options = {
hostname: 'api.gopag.com.br',
path: '/v1/marketplaces/abc123.../sellers?limit=10',
method: 'GET',
cert: fs.readFileSync('/etc/ssl/gopag/client.crt'),
key: fs.readFileSync('/etc/ssl/gopag/client.key'),
headers: {
'Authorization': `Bearer ${accessToken}`
}
};
const req = https.request(options, (res) => {
let data = '';
res.on('data', (chunk) => data += chunk);
res.on('end', () => console.log(JSON.parse(data)));
});
req.end();
```
### Python
```python
import requests
response = requests.get(
'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers',
params={'limit': 10, 'offset': 0},
headers={'Authorization': f'Bearer {access_token}'}
)
sellers = response.json()
```
## Response
### Status: 200 OK
```json
{
"resource": "list",
"uri": "/v1/marketplaces/abc123.../sellers",
"limit": 10,
"offset": 0,
"has_more": false,
"query_count": 2,
"total": 2,
"items": [
{
"id": "17d9e827664b47509f12a082b6047e7a",
"status": "active",
"resource": "seller",
"type": "business",
"account_balance": 0,
"current_balance": 0,
"owner": {
"first_name": "José",
"last_name": "Da Silva",
"email": "jose@empresa.com.br",
"phone_number": "11987654321",
"taxpayer_id": "12345678901",
"birthdate": "1985-03-15"
},
"business_name": "Empresa XYZ LTDA",
"business_phone": "1133334444",
"business_email": "contato@empresa.com.br",
"business_website": "https://empresa.com.br",
"ein": "12345678000190",
"statement_descriptor": "EMPRESA XYZ",
"business_address": {
"line1": "Rua das Flores, 123",
"line2": "Sala 456",
"neighborhood": "Centro",
"city": "São Paulo",
"state": "SP",
"postal_code": "01310100",
"country_code": "BR"
},
"mcc": "5411",
"created_at": "2025-12-01T10:00:00Z",
"updated_at": "2025-12-15T14:30:00Z"
},
{
"id": "28e0f938775c58610e23b193c7158f8b",
"status": "pending",
"resource": "seller",
"type": "individual",
"owner": {
"first_name": "Maria",
"last_name": "Santos",
"email": "maria@exemplo.com",
"phone_number": "11912345678",
"taxpayer_id": "98765432100",
"birthdate": "1990-07-20"
},
"statement_descriptor": "MARIA SANTOS",
"created_at": "2025-12-20T08:15:00Z",
"updated_at": "2025-12-20T08:15:00Z"
}
]
}
```
### Campos da Resposta
| Campo | Tipo | Descrição |
| ------------- | ------- | ----------------------------------- |
| `resource` | string | Sempre `"list"` para listagens |
| `uri` | string | URI da requisição |
| `limit` | integer | Quantidade de itens por página |
| `offset` | integer | Offset aplicado |
| `has_more` | boolean | Indica se há mais páginas |
| `query_count` | integer | Quantidade de itens na página atual |
| `total` | integer | Total de vendedores no marketplace |
| `items` | array | Array de objetos seller |
### Campos do Seller
| Campo | Tipo | Descrição |
| ---------------------- | ------ | ------------------------------------------------------------ |
| `id` | string | ID único do vendedor |
| `status` | string | `pending`, `active`, `inactive` |
| `type` | string | `individual` (pessoa física) ou `business` (pessoa jurídica) |
| `owner.taxpayer_id` | string | CPF do responsável |
| `ein` | string | CNPJ (apenas para `type: business`) |
| `business_name` | string | Razão social (apenas para empresas) |
| `statement_descriptor` | string | Nome que aparece na fatura do cliente |
| `mcc` | string | Código de categoria do comerciante |
## Paginação
Para navegar pelos resultados:
```bash
# Primeira página (itens 0-99)
GET /v1/marketplaces/abc123.../sellers?limit=100&offset=0
# Segunda página (itens 100-199)
GET /v1/marketplaces/abc123.../sellers?limit=100&offset=100
# Terceira página (itens 200-299)
GET /v1/marketplaces/abc123.../sellers?limit=100&offset=200
```
### Exemplo de Loop
```php
```
## Filtros
### Por Status
```bash
# Apenas vendedores ativos
GET /v1/marketplaces/abc123.../sellers?status=active
# Apenas vendedores pendentes
GET /v1/marketplaces/abc123.../sellers?status=pending
```
### Ordenação
```bash
# Mais recentes primeiro
GET /v1/marketplaces/abc123.../sellers?sort=-created_at
# Mais antigos primeiro
GET /v1/marketplaces/abc123.../sellers?sort=created_at
# Ordem alfabética por razão social
GET /v1/marketplaces/abc123.../sellers?sort=business_name
```
## Erros
### 401 Unauthorized
```json
{
"status": 401,
"detail": "Invalid or expired access token",
"trace_id": "a1b2c3"
}
```
**Solução**: Renove o access token via endpoint `/oauth`
### 403 Forbidden
```json
{
"status": 403,
"detail": "Certificate does not match marketplace_id",
"trace_id": "d4e5f6"
}
```
**Solução**: Verifique se o `certSerialNumber` corresponde ao `marketplace_id`
### 429 Too Many Requests
```json
{
"status": 429,
"detail": "Rate limit exceeded. Try again in 60 seconds",
"trace_id": "g7h8i9"
}
```
**Solução**: Respeite rate limits (Caso necessário entre em contato com o time de suporte)
## Próximos Passos
* [Buscar Vendedor por CPF/CNPJ](/developers/cadastro/vendedores/buscar-cpf-cnpj)
* [Recuperar Detalhes de Vendedor](/developers/cadastro/vendedores/detalhes)
* [Códigos MCC](/developers/cadastro/vendedores/mcc)
* [Criar Transação para Vendedor](/developers/transacoes/criar-transacao-sem-checkout/cartao)
# Buscar por CPF/CNPJ
Busca um vendedor específico utilizando CPF (pessoa física) ou CNPJ (pessoa jurídica).
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/sellers/search
```
## Parâmetros de Query
| Parâmetro | Tipo | Obrigatório | Descrição |
| ------------- | ------ | ---------------------- | ----------------------------------------------- |
| `taxpayer_id` | string | Sim (ou `ein`) | CPF do responsável (11 dígitos, apenas números) |
| `ein` | string | Sim (ou `taxpayer_id`) | CNPJ da empresa (14 dígitos, apenas números) |
**⚠️ IMPORTANTE**: Use `taxpayer_id` para buscar por CPF ou `ein` para buscar por CNPJ. Não envie ambos simultaneamente.
## Request
### Buscar por CPF
#### cURL
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers/search?taxpayer_id=12345678901' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
#### PHP
```php
"https://api.gopag.com.br/v1/marketplaces/{$marketplaceId}/sellers/search?taxpayer_id={$taxpayerId}",
CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$accessToken}"
]
]);
$response = curl_exec($ch);
$seller = json_decode($response, true);
curl_close($ch);
?>
```
#### Python
```python
import requests
response = requests.get(
f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/sellers/search',
params={'taxpayer_id': '12345678901'},
headers={'Authorization': f'Bearer {access_token}'}
)
seller = response.json()
```
### Buscar por CNPJ
#### cURL
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers/search?ein=12345678000190' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
#### Node.js
```javascript
const https = require('https');
const fs = require('fs');
const ein = '12345678000190'; // CNPJ sem pontos, barras e hífen
const options = {
hostname: 'api.gopag.com.br',
path: `/v1/marketplaces/${marketplaceId}/sellers/search?ein=${ein}`,
method: 'GET',
cert: fs.readFileSync('/etc/ssl/gopag/client.crt'),
key: fs.readFileSync('/etc/ssl/gopag/client.key'),
headers: {
'Authorization': `Bearer ${accessToken}`
}
};
const req = https.request(options, (res) => {
let data = '';
res.on('data', (chunk) => data += chunk);
res.on('end', () => {
const seller = JSON.parse(data);
console.log(seller);
});
});
req.end();
```
## Response
### Status: 200 OK (Vendedor Encontrado)
```json
{
"id": "17d9e827664b47509f12a082b6047e7a",
"status": "active",
"resource": "seller",
"type": "business",
"account_balance": 15000,
"current_balance": 15000,
"owner": {
"first_name": "José",
"last_name": "Da Silva",
"email": "jose@empresa.com.br",
"phone_number": "11987654321",
"taxpayer_id": "12345678901",
"birthdate": "1985-03-15"
},
"description": "Vendedor de produtos eletrônicos",
"business_name": "Empresa XYZ LTDA",
"business_phone": "1133334444",
"business_email": "contato@empresa.com.br",
"business_website": "https://empresa.com.br",
"business_description": "Comércio de eletrônicos e acessórios",
"ein": "12345678000190",
"statement_descriptor": "EMPRESA XYZ",
"business_address": {
"line1": "Rua das Flores, 123",
"line2": "Sala 456",
"line3": "",
"neighborhood": "Centro",
"city": "São Paulo",
"state": "SP",
"postal_code": "01310100",
"country_code": "BR"
},
"business_opening_date": "2010-05-20",
"owner_address": {
"line1": "Rua Principal, 789",
"line2": "Apto 101",
"neighborhood": "Jardim Paulista",
"city": "São Paulo",
"state": "SP",
"postal_code": "01419000",
"country_code": "BR"
},
"mcc": "5732",
"metadata": {
"internal_id": "VEND-12345",
"sales_channel": "marketplace"
},
"created_at": "2025-12-01T10:00:00Z",
"updated_at": "2025-12-15T14:30:00Z"
}
```
### Status: 404 Not Found (Vendedor Não Encontrado)
```json
{
"type": "https://httpstatuses.com/404",
"title": "Not Found",
"status": 404,
"detail": "Seller not found with taxpayer_id: 12345678901",
"trace_id": "a1b2c3"
}
```
## Casos de Uso
### 1. Validar se Vendedor Já Existe
```php
```
### 2. Obter Seller ID para Criar Transação
```javascript
async function getSellerIdByDocument(ein) {
const response = await fetch(
`https://api.gopag.com.br/v1/marketplaces/${marketplaceId}/sellers/search?ein=${ein}`,
{
headers: {
'Authorization': `Bearer ${accessToken}`
},
cert: clientCert,
key: clientKey
}
);
if (response.ok) {
const seller = await response.json();
return seller.id;
}
return null;
}
// Uso
const sellerId = await getSellerIdByDocument('12345678000190');
if (sellerId) {
// Criar transação usando sellerId
}
```
### 3. Sincronizar Status com Sistema Interno
```python
import requests
def sync_seller_status(ein, internal_status):
response = requests.get(
f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/sellers/search',
params={'ein': ein},
headers={'Authorization': f'Bearer {access_token}'}
)
if response.status_code == 200:
seller = response.json()
gopag_status = seller['status']
if gopag_status != internal_status:
print(f"Status divergente! GoPag: {gopag_status}, Interno: {internal_status}")
return False
return True
```
## Formato de Documentos
### CPF (`taxpayer_id`)
* **Formato**: Apenas números
* **Tamanho**: Exatamente 11 dígitos
* **Exemplo válido**: `12345678901`
* **Exemplo inválido**: `123.456.789-01` ❌
### CNPJ (`ein`)
* **Formato**: Apenas números
* **Tamanho**: Exatamente 14 dígitos
* **Exemplo válido**: `12345678000190`
* **Exemplo inválido**: `12.345.678/0001-90` ❌
## Erros Comuns
### 400 Bad Request - Formato Inválido
```json
{
"status": 400,
"detail": "Invalid taxpayer_id format. Expected 11 digits",
"trace_id": "d4e5f6"
}
```
**Solução**: Remova pontos, hífens e barras. Envie apenas números.
### 400 Bad Request - Múltiplos Parâmetros
```json
{
"status": 400,
"detail": "Provide either taxpayer_id or ein, not both",
"trace_id": "g7h8i9"
}
```
**Solução**: Envie apenas um dos parâmetros por requisição.
### 400 Bad Request - Nenhum Parâmetro
```json
{
"status": 400,
"detail": "Either taxpayer_id or ein is required",
"trace_id": "j1k2l3"
}
```
**Solução**: Inclua pelo menos um dos parâmetros de busca.
## Performance
* **Cache**: Recomendado cachear resultados por 1 hora
* **Rate Limit**: Máximo 100 requisições/minuto
* **Timeout**: 5 segundos recomendado
### Exemplo com Cache (PHP)
```php
```
## Próximos Passos
* [Listar Todos os Vendedores](/developers/cadastro/vendedores/listar)
* [Recuperar Detalhes Completos](/developers/cadastro/vendedores/detalhes)
* [Códigos MCC](/developers/cadastro/vendedores/mcc)
* [Criar Transação para Vendedor](/developers/transacoes/criar-transacao-sem-checkout/cartao)
# Detalhes do Vendedor
Recupera informações completas de um vendedor específico pelo ID.
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/sellers/{seller_id}
```
## Parâmetros de Path
| Parâmetro | Tipo | Descrição |
| ---------------- | ------ | -------------------- |
| `marketplace_id` | string | ID do marketplace |
| `seller_id` | string | ID único do vendedor |
## Request
### cURL
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers/17d9e827664b47509f12a082b6047e7a' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
## Response
### Status: 200 OK
```json
{
"id": "17d9e827664b47509f12a082b6047e7a",
"status": "active",
"resource": "seller",
"type": "business",
"account_balance": 15000,
"current_balance": 15000,
"fiscal_responsibility": "merchant",
"owner": {
"first_name": "José",
"last_name": "Da Silva",
"email": "jose@empresa.com.br",
"phone_number": "11987654321",
"taxpayer_id": "12345678901",
"birthdate": "1985-03-15"
},
"description": "Vendedor de produtos eletrônicos",
"business_name": "Empresa XYZ LTDA",
"business_phone": "1133334444",
"business_email": "contato@empresa.com.br",
"business_website": "https://empresa.com.br",
"business_description": "Comércio de eletrônicos e acessórios",
"business_facebook": "https://facebook.com/empresaxyz",
"business_twitter": "https://twitter.com/empresaxyz",
"ein": "12345678000190",
"statement_descriptor": "EMPRESA XYZ",
"business_address": {
"line1": "Rua das Flores, 123",
"line2": "Sala 456",
"line3": "",
"neighborhood": "Centro",
"city": "São Paulo",
"state": "SP",
"postal_code": "01310100",
"country_code": "BR"
},
"business_opening_date": "2010-05-20",
"owner_address": {
"line1": "Rua Principal, 789",
"line2": "Apto 101",
"line3": "",
"neighborhood": "Jardim Paulista",
"city": "São Paulo",
"state": "SP",
"postal_code": "01419000",
"country_code": "BR"
},
"delinquent": false,
"default_debit": "card_abc123",
"default_credit": "card_def456",
"mcc": "5732",
"metadata": {
"internal_id": "VEND-12345",
"sales_channel": "marketplace"
},
"created_at": "2025-12-01T10:00:00Z",
"updated_at": "2025-12-15T14:30:00Z"
}
```
### Campos Específicos para Empresas (`type: business`)
Os campos iniciados com `business_` são retornados apenas para vendedores do tipo `business` (pessoa jurídica):
* `business_name` - Razão social
* `business_phone` - Telefone comercial
* `business_email` - Email comercial
* `business_website` - Website
* `business_description` - Descrição do negócio
* `business_facebook` - URL do Facebook
* `business_twitter` - URL do Twitter
* `business_address` - Endereço comercial
* `business_opening_date` - Data de abertura da empresa
* `ein` - CNPJ
Para vendedores `type: individual` (pessoa física), esses campos não estarão presentes.
## Próximos Passos
* [Listar Vendedores](/developers/cadastro/vendedores/listar)
* [Buscar por CPF/CNPJ](/developers/cadastro/vendedores/buscar-cpf-cnpj)
* [Códigos MCC](/developers/cadastro/vendedores/mcc)
# Códigos MCC
Os códigos MCC (Merchant Category Code) classificam o tipo de negócio do vendedor. São utilizados por adquirentes e bandeiras para identificar a categoria do estabelecimento comercial.
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/mcc
```
## Request
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../mcc' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
## Response
```json
{
"resource": "list",
"items": [
{
"code": "5411",
"description": "Supermercados e Mercearias"
},
{
"code": "5732",
"description": "Lojas de Eletrônicos"
},
{
"code": "5812",
"description": "Restaurantes e Lanchonetes"
},
{
"code": "5999",
"description": "Lojas Diversas - Varejo"
},
{
"code": "7230",
"description": "Salões de Beleza e Barbearias"
},
{
"code": "7299",
"description": "Serviços Pessoais Diversos"
},
{
"code": "8011",
"description": "Médicos e Clínicas"
}
]
}
```
## MCCs Comuns
| Código | Descrição |
| ------ | ----------------------------- |
| 5411 | Supermercados e Mercearias |
| 5541 | Postos de Gasolina |
| 5732 | Lojas de Eletrônicos |
| 5812 | Restaurantes e Lanchonetes |
| 5912 | Farmácias |
| 5999 | Lojas Diversas - Varejo |
| 7230 | Salões de Beleza e Barbearias |
| 7299 | Serviços Pessoais Diversos |
| 8011 | Médicos e Clínicas |
| 8021 | Dentistas |
| 8099 | Profissionais de Saúde |
## Importância do MCC
O código MCC é importante para:
* ✅ **Taxas de intercâmbio**: Diferentes MCCs podem ter taxas diferentes
* ✅ **Análise de risco**: Algumas categorias são consideradas de maior risco
* ✅ **Programas de benefícios**: Categorias específicas podem ter cashback
* ✅ **Compliance**: Necessário para regulamentações do setor
## Selecionando o MCC Correto
Ao cadastrar um vendedor, escolha o MCC que melhor descreve a atividade principal:
❌ **Errado**: Loja de roupas usando MCC 5999 (genérico) ✅ **Correto**: Loja de roupas usando MCC 5651 (Lojas de Vestuário Familiar)
## Próximos Passos
* [Listar Vendedores](/developers/cadastro/vendedores/listar)
* [Buscar Vendedor](/developers/cadastro/vendedores/buscar-cpf-cnpj)
* [Detalhes do Vendedor](/developers/cadastro/vendedores/detalhes)
# Compradores
# Visão Geral
Gerenciamento completo de compradores no GoPag API.
## Documentação
### Operações CRUD
* [**Criar Comprador**](/developers/cadastro/compradores/criar) - Cadastrar novo comprador no sistema
* [**Buscar por CPF/CNPJ**](/developers/cadastro/compradores/buscar-cpf-cnpj) - Localizar comprador usando documento
* [**Detalhes do Comprador**](/developers/cadastro/compradores/detalhes) - Recuperar e atualizar informações
* [**Remover Comprador**](/developers/cadastro/compradores/remover) - Deletar comprador do sistema
***
## Visão Geral
Os compradores (buyers) são os clientes finais que realizam compras através da plataforma. Cada comprador possui:
* **Dados pessoais**: Nome, email, telefone, CPF/CNPJ
* **Endereço**: Informações completas de localização
* **Cartões tokenizados**: Métodos de pagamento salvos
* **Metadata**: Campos customizados para sua aplicação
### Fluxo Básico
```
1. Criar Comprador
↓
2. Tokenizar Cartão (opcional)
↓
3. Criar Transação
↓
4. Reutilizar em próximas compras
```
***
## Início Rápido
### Criar Primeiro Comprador
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/buyers' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "Maria",
"last_name": "Santos",
"email": "maria@email.com",
"taxpayer_id": "12345678901"
}'
```
### Buscar por CPF
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/buyers/search?taxpayer_id=12345678901' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
### Atualizar Email
```bash
curl --location --request PATCH 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/buyers/BUYER_ID' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"email": "novo@email.com"}'
```
***
## Casos de Uso Comuns
### 1. Checkout com Comprador Novo
```javascript
// Verificar se comprador já existe
let buyer = await searchBuyerByCPF(cpf);
if (!buyer) {
// Criar novo comprador
buyer = await createBuyer({
first_name: 'Maria',
last_name: 'Santos',
email: 'maria@email.com',
taxpayer_id: cpf
});
}
// Criar transação
const transaction = await createTransaction({
customer: buyer.id,
amount: 10000,
payment_type: 'credit'
});
```
### 2. Compra Recorrente (Assinatura)
```python
# Buscar comprador existente
buyer = search_buyer_by_cpf('12345678901')
# Criar cobrança mensal usando customer_id
transaction = create_transaction({
'customer': buyer['id'], # Usa cartão tokenizado
'amount': 4990,
'currency': 'BRL',
'description': 'Assinatura Premium - Mensal',
'capture': True
})
```
### 3. Atualização de Cadastro
```php
'novo@email.com',
'metadata' => [
'email_updated_at' => date('c'),
'email_updated_by' => 'customer_portal'
]
]);
?>
```
***
## Estrutura de Dados
### Objeto Buyer Completo
```json
{
"id": "e4e8c5b569da48b28d896385f5481bcf",
"resource": "buyer",
"first_name": "Maria",
"last_name": "Santos",
"email": "maria.santos@email.com",
"phone_number": "11987654321",
"taxpayer_id": "12345678901",
"birthdate": "1990-07-15",
"address": {
"line1": "Rua das Palmeiras, 456",
"line2": "Apto 789",
"line3": "",
"neighborhood": "Jardins",
"city": "São Paulo",
"state": "SP",
"postal_code": "01418000",
"country_code": "BR"
},
"metadata": {
"customer_level": "gold",
"origin": "mobile_app"
},
"created_at": "2025-12-21T10:00:00Z",
"updated_at": "2025-12-21T10:00:00Z"
}
```
***
## Boas Práticas
### ✅ Recomendado
* **Sempre busque antes de criar**: Evite duplicatas verificando CPF primeiro
* **Armazene o buyer\_id**: Guarde para reutilizar em transações futuras
* **Use metadata**: Adicione informações customizadas relevantes para seu negócio
* **Valide dados**: Verifique email e CPF antes de enviar
* **Tokenize cartões**: Use `usage: 'reusable'` para vendas recorrentes
### ❌ Evite
* Criar compradores duplicados sem verificar CPF
* Armazenar dados sensíveis em metadata
* Atualizar todos os campos quando precisa mudar apenas um
* Deletar compradores sem verificar transações pendentes
* Formatar CPF com pontos e traços (use apenas números)
***
## Próximos Passos
### Documentação Relacionada
* [Criar Transação com Comprador](/developers/transacoes/criar-transacao-sem-checkout/cartao)
* [Tokenização de Cartões](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/transacoes/tokenizar.md)
* [Gestão de Vendedores](/developers/cadastro/vendedores/listar)
* [API Reference](/developers/introducao/autenticacao)
### Tutoriais
* [Implementar Checkout Completo](/developers/cadastro/compradores/compradores)
* [Sistema de Assinaturas](/developers/cadastro/compradores/compradores)
* [LGPD e Privacidade](/developers/cadastro/compradores/compradores)
***
## Precisa de Ajuda?
* 📧 Email:
* 📚 [Documentação Completa](/developers)
* 💬 [Portal do Desenvolvedor](/developers/cadastro/compradores/compradores)
# Criar Comprador
Endpoint para criação de novos compradores (buyers) no GoPag API.
## Endpoint
```
POST /v1/marketplaces/{marketplace_id}/buyers
```
## Request Body
```json
{
"first_name": "Maria",
"last_name": "Santos",
"email": "maria.santos@email.com",
"phone_number": "11987654321",
"taxpayer_id": "12345678901",
"birthdate": "1990-07-15",
"address": {
"line1": "Rua das Palmeiras, 456",
"line2": "Apto 789",
"line3": "",
"neighborhood": "Jardins",
"city": "São Paulo",
"state": "SP",
"postal_code": "01418000",
"country_code": "BR"
},
"metadata": {}
}
```
## Response: 201 Created
```json
{
"id": "e4e8c5b569da48b28d896385f5481bcf",
"resource": "buyer",
"first_name": "Maria",
"last_name": "Santos",
"email": "maria.santos@email.com",
"phone_number": "11987654321",
"taxpayer_id": "12345678901",
"birthdate": "1990-07-15",
"address": {
"line1": "Rua das Palmeiras, 456",
"line2": "Apto 789",
"line3": "",
"neighborhood": "Jardins",
"city": "São Paulo",
"state": "SP",
"postal_code": "01418000",
"country_code": "BR"
},
"metadata": {
"customer_id": "CUST-12345",
"origin": "mobile_app"
},
"created_at": "2025-12-21T10:00:00Z",
"updated_at": "2025-12-21T10:00:00Z"
}
```
## Exemplo cURL
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../buyers' \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "Maria",
"last_name": "Santos",
"email": "maria.santos@email.com",
"phone_number": "11987654321",
"taxpayer_id": "12345678901",
"birthdate": "1990-07-15"
}'
```
***
## Campos do Comprador
| Campo | Tipo | Obrigatório | Descrição |
| -------------- | ------ | ----------- | ------------------------------------- |
| `first_name` | string | Sim | Primeiro nome |
| `last_name` | string | Sim | Sobrenome |
| `email` | string | Sim | Email válido |
| `phone_number` | string | Não | Telefone (apenas números) |
| `taxpayer_id` | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos) |
| `birthdate` | string | Não | Data de nascimento (YYYY-MM-DD) |
| `address` | object | Não | Endereço completo |
| `metadata` | object | Não | Dados customizados (chave-valor) |
### Campos do Endereço
| Campo | Tipo | Obrigatório | Descrição |
| -------------- | ------ | ----------- | ------------------------------- |
| `line1` | string | Sim | Logradouro e número |
| `line2` | string | Não | Complemento |
| `line3` | string | Não | Ponto de referência |
| `neighborhood` | string | Sim | Bairro |
| `city` | string | Sim | Cidade |
| `state` | string | Sim | UF (2 letras) |
| `postal_code` | string | Sim | CEP (8 dígitos, apenas números) |
| `country_code` | string | Sim | Código do país (BR) |
***
## Casos de Uso
### 1. Criar Comprador e Tokenizar Cartão
```php
'Maria',
'last_name' => 'Santos',
'email' => 'maria@email.com',
'taxpayer_id' => '12345678901'
]);
$buyerId = $buyer['id'];
// 2. Criar transação com cartão (será tokenizado automaticamente)
$transaction = createTransaction([
'payment_type' => 'credit',
'customer' => $buyerId,
'amount' => 5000,
'currency' => 'BRL',
'description' => 'Primeira compra',
'source' => [
'card' => [
'card_number' => '4111111111111111',
'holder_name' => 'MARIA SANTOS',
'expiration_month' => '12',
'expiration_year' => '2028',
'security_code' => '123'
],
'usage' => 'reusable', // Tokeniza para reutilização
'type' => 'card'
]
]);
?>
```
### 2. Compra Recorrente com Comprador Existente
```javascript
// 1. Buscar comprador por CPF
const buyer = await searchBuyerByCPF('12345678901');
if (buyer) {
// 2. Criar transação usando customer_id
const transaction = await createTransaction({
payment_type: 'credit',
customer: buyer.id,
amount: 3000,
currency: 'BRL',
description: 'Assinatura mensal',
capture: true
});
}
```
***
## Erros Comuns
### CPF Já Cadastrado
```json
{
"status": 400,
"detail": "Buyer with taxpayer_id 12345678901 already exists",
"trace_id": "a1b2c3"
}
```
**Solução**: Use busca por CPF para obter ID do comprador existente.
### Email Inválido
```json
{
"status": 400,
"detail": "Invalid email format",
"trace_id": "d4e5f6"
}
```
**Solução**: Valide formato de email antes de enviar.
### CPF Inválido
```json
{
"status": 400,
"detail": "Invalid taxpayer_id format. Expected 11 digits for CPF",
"trace_id": "g7h8i9"
}
```
**Solução**: Envie CPF com 11 dígitos (apenas números, sem pontos ou hífen).
***
## Próximos Passos
* [Buscar Comprador por CPF/CNPJ](/developers/cadastro/compradores/buscar-cpf-cnpj)
* [Recuperar Detalhes do Comprador](/developers/cadastro/compradores/detalhes)
* [Remover Comprador](/developers/cadastro/compradores/remover)
* [Criar Transação com Comprador](/developers/transacoes/criar-transacao-sem-checkout/cartao)
# Buscar por CPF/CNPJ
Endpoint para buscar um comprador utilizando CPF ou CNPJ.
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/buyers/search?taxpayer_id={cpf}
```
```
GET /v1/marketplaces/{marketplace_id}/buyers/search?ein={cnpj}
```
## Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
| ------------- | ------ | ----------------- | -------------------------------- |
| `taxpayer_id` | string | Sim (quando CPF) | CPF (11 dígitos) apenas números |
| `ein` | string | Sim (quando CNPJ) | CNPJ (14 dígitos) apenas números |
## Request
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../buyers/search?taxpayer_id=12345678901' \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../buyers/search?ein=12345678000199' \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
## Response: 200 OK
```json
{
"id": "e4e8c5b569da48b28d896385f5481bcf",
"resource": "buyer",
"first_name": "Maria",
"last_name": "Santos",
"email": "maria.santos@email.com",
"phone_number": "11987654321",
"taxpayer_id": "12345678901", // quando CPF
"ein": "12345678000199", // quando CNPJ
"birthdate": "1990-07-15",
"address": {
"line1": "Rua das Palmeiras, 456",
"line2": "Apto 789",
"neighborhood": "Jardins",
"city": "São Paulo",
"state": "SP",
"postal_code": "01418000",
"country_code": "BR"
},
"created_at": "2025-12-21T10:00:00Z",
"updated_at": "2025-12-21T10:00:00Z"
}
```
## Response: 404 Not Found
```json
{
"status": 404,
"detail": "Buyer not found with taxpayer_id: 12345678901",
"trace_id": "a1b2c3"
}
```
***
## Exemplo de Uso
### Verificar se Comprador já Existe
```javascript
async function findOrCreateBuyer(taxpayerId, buyerData) {
try {
// Tenta buscar comprador existente
const response = await fetch(
`https://api.gopag.com.br/v1/marketplaces/${marketplaceId}/buyers/search?taxpayer_id=${taxpayerId}`,
{
headers: {
'Authorization': `Bearer ${accessToken}`
}
}
);
if (response.ok) {
return await response.json(); // Comprador encontrado
}
// Se não encontrar (404), cria novo comprador
return await createBuyer(buyerData);
} catch (error) {
console.error('Erro ao buscar/criar comprador:', error);
throw error;
}
}
```
### Validar CPF Antes de Criar
```python
import requests
def get_buyer_by_cpf(cpf):
"""Busca comprador por CPF"""
url = f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/buyers/search'
params = {'taxpayer_id': cpf}
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(url, params=params, headers=headers)
if response.status_code == 200:
return response.json()
elif response.status_code == 404:
return None
else:
response.raise_for_status()
# Uso
buyer = get_buyer_by_cpf('12345678901')
if buyer:
print(f'Comprador já existe: {buyer["id"]}')
else:
print('Comprador não encontrado, pode criar novo')
```
```python
import requests
def get_buyer_by_cnpj(cnpj):
"""Busca comprador por CNPJ"""
url = f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/buyers/search'
params = {'ein': cnpj}
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(url, params=params, headers=headers)
if response.status_code == 200:
return response.json()
elif response.status_code == 404:
return None
else:
response.raise_for_status()
# Uso
buyer = get_buyer_by_cnpj('12345678000199')
if buyer:
print(f'Comprador já existe: {buyer["id"]}')
else:
print('Comprador não encontrado, pode criar novo')
```
### Reutilizar Comprador em Nova Transação
```php
'credit',
'customer' => $buyer['id'],
'amount' => $amount,
'currency' => 'BRL',
'description' => 'Nova compra',
'capture' => true
]);
}
?>
'credit',
'customer' => $buyer['id'],
'amount' => $amount,
'currency' => 'BRL',
'description' => 'Nova compra',
'capture' => true
]);
}
?>
```
***
## Dicas
### ✅ Boas Práticas
1. **Sempre busque antes de criar**: Evite criar compradores duplicados
2. **Armazene o buyer\_id**: Guarde o ID retornado para reutilizar em transações futuras
3. **Use apenas números**: Remova pontos, traços e outros caracteres do CPF ou CNPJ
4. **Cache do resultado**: Se vai fazer várias transações seguidas, armazene o buyer\_id em memória
### ⚠️ Observações
* Para CPF, use o parâmetro `taxpayer_id`
* Para CNPJ, use o parâmetro `ein`
***
## Erros Comuns
### Formato Inválido
```json
{
"status": 400,
"detail": "Invalid taxpayer_id format. Expected 11 or 14 digits",
"trace_id": "x1y2z3"
}
```
**Solução**: Envie apenas números, sem formatação.
### Marketplace Inválido
```json
{
"status": 404,
"detail": "Marketplace not found",
"trace_id": "a1b2c3"
}
```
**Solução**: Verifique se o `marketplace_id` está correto.
***
## Próximos Passos
* [Criar Novo Comprador](/developers/cadastro/compradores/criar)
* [Recuperar Detalhes do Comprador](/developers/cadastro/compradores/detalhes)
* [Atualizar Dados do Comprador](/developers/cadastro/compradores/detalhes#alterar-detalhes)
* [Remover Comprador](/developers/cadastro/compradores/remover)
# Detalhes do Comprador
Endpoints para recuperar e atualizar informações de um comprador.
## Índice
* [Recuperar Detalhes](#recuperar-detalhes)
* [Alterar Detalhes](#alterar-detalhes)
***
## Recuperar Detalhes
### Endpoint
```
GET /v1/marketplaces/{marketplace_id}/buyers/{buyer_id}
```
### Request
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../buyers/e4e8c5b569da48b28d896385f5481bcf' \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
### Response: 200 OK
```json
{
"id": "e4e8c5b569da48b28d896385f5481bcf",
"resource": "buyer",
"first_name": "Maria",
"last_name": "Santos",
"email": "maria.santos@email.com",
"phone_number": "11987654321",
"taxpayer_id": "12345678901",
"birthdate": "1990-07-15",
"address": {
"line1": "Rua das Palmeiras, 456",
"line2": "Apto 789",
"line3": "",
"neighborhood": "Jardins",
"city": "São Paulo",
"state": "SP",
"postal_code": "01418000",
"country_code": "BR"
},
"metadata": {},
"created_at": "2025-12-21T10:00:00Z",
"updated_at": "2025-12-21T10:00:00Z"
}
```
### Response: 404 Not Found
```json
{
"status": 404,
"detail": "Buyer not found",
"trace_id": "a1b2c3"
}
```
***
## Alterar Detalhes
### Endpoint
```
PATCH /v1/marketplaces/{marketplace_id}/buyers/{buyer_id}
```
### Request Body
Envie apenas os campos que deseja atualizar:
```json
{
"email": "maria.novo@email.com",
"phone_number": "11912345678",
"address": {
"line1": "Nova Rua, 123",
"neighborhood": "Novo Bairro",
"city": "São Paulo",
"state": "SP",
"postal_code": "01234567",
"country_code": "BR"
}
}
```
### Request
```bash
curl --location --request PATCH 'https://api.gopag.com.br/v1/marketplaces/abc123.../buyers/e4e8c5b569da48b28d896385f5481bcf' \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"email": "maria.novo@email.com",
"phone_number": "11912345678"
}'
```
### Response: 200 OK
Retorna objeto do comprador com dados atualizados.
```json
{
"id": "e4e8c5b569da48b28d896385f5481bcf",
"resource": "buyer",
"first_name": "Maria",
"last_name": "Santos",
"email": "maria.novo@email.com",
"phone_number": "11912345678",
"taxpayer_id": "12345678901",
"birthdate": "1990-07-15",
"address": {
"line1": "Nova Rua, 123",
"neighborhood": "Novo Bairro",
"city": "São Paulo",
"state": "SP",
"postal_code": "01234567",
"country_code": "BR"
},
"metadata": {},
"created_at": "2025-12-21T10:00:00Z",
"updated_at": "2025-12-21T16:45:00Z"
}
```
***
## Campos Atualizáveis
| Campo | Tipo | Descrição |
| -------------- | ------ | ------------------------------- |
| `first_name` | string | Primeiro nome |
| `last_name` | string | Sobrenome |
| `email` | string | Email válido |
| `phone_number` | string | Telefone (apenas números) |
| `birthdate` | string | Data de nascimento (YYYY-MM-DD) |
| `address` | object | Endereço completo |
| `metadata` | object | Dados customizados |
**⚠️ Campos NÃO Atualizáveis**:
* `taxpayer_id` (CPF/CNPJ) - **Não pode ser alterado**
* `id` - ID do comprador
* `resource` - Tipo do recurso
* `created_at` - Data de criação
***
## Exemplos de Uso
### Atualizar Email
```javascript
async function updateBuyerEmail(buyerId, newEmail) {
const response = await fetch(
`https://api.gopag.com.br/v1/marketplaces/${marketplaceId}/buyers/${buyerId}`,
{
method: 'PATCH',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: newEmail
})
}
);
return await response.json();
}
// Uso
const updated = await updateBuyerEmail('e4e8c5b...', 'novo@email.com');
console.log('Email atualizado:', updated.email);
```
### Atualizar Endereço Completo
```python
def update_buyer_address(buyer_id, new_address):
url = f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/buyers/{buyer_id}'
headers = {
'Authorization': f'Bearer {access_token}',
'Content-Type': 'application/json'
}
data = {
'address': new_address
}
response = requests.patch(url, json=data, headers=headers)
return response.json()
# Uso
new_address = {
'line1': 'Av. Paulista, 1000',
'line2': 'Conjunto 101',
'neighborhood': 'Bela Vista',
'city': 'São Paulo',
'state': 'SP',
'postal_code': '01310100',
'country_code': 'BR'
}
buyer = update_buyer_address('e4e8c5b...', new_address)
```
### Atualizar Múltiplos Campos
```php
'novo@email.com',
'phone_number' => '11999887766',
'metadata' => [
'customer_level' => 'gold',
'last_purchase' => '2025-12-21'
]
];
$buyer = updateBuyerData('e4e8c5b...', $updates);
?>
```
### Atualizar Metadata
```javascript
// Adicionar ou atualizar campos em metadata
async function updateBuyerMetadata(buyerId, metadataUpdates) {
// Primeiro, buscar dados atuais
const currentBuyer = await getBuyerDetails(buyerId);
// Mesclar metadata existente com novos dados
const updatedMetadata = {
...currentBuyer.metadata,
...metadataUpdates
};
// Atualizar comprador
return await updateBuyer(buyerId, {
metadata: updatedMetadata
});
}
// Uso
await updateBuyerMetadata('e4e8c5b...', {
loyalty_points: 150,
vip: true,
last_interaction: '2025-12-21T10:30:00Z'
});
```
***
## Dicas
### ✅ Boas Práticas
1. **Atualizações parciais**: Envie apenas os campos que realmente mudaram
2. **Validação prévia**: Valide email, telefone e endereço antes de enviar
3. **Preserve metadata**: Ao atualizar metadata, mescle com dados existentes
4. **Trate erros**: Implemente tratamento adequado para erros de validação
### ⚠️ Observações
* `taxpayer_id` (CPF/CNPJ) **não pode ser alterado** após criação
* Para alterar endereço parcialmente, envie o objeto completo com as mudanças
* Campos vazios ou null podem remover dados existentes
* `updated_at` é atualizado automaticamente
***
## Erros Comuns
### Comprador Não Encontrado
```json
{
"status": 404,
"detail": "Buyer not found",
"trace_id": "a1b2c3"
}
```
**Solução**: Verifique se o `buyer_id` está correto.
### Email Inválido
```json
{
"status": 400,
"detail": "Invalid email format",
"trace_id": "d4e5f6"
}
```
**Solução**: Valide formato de email antes de enviar.
### Tentativa de Alterar CPF
```json
{
"status": 400,
"detail": "Field taxpayer_id cannot be modified",
"trace_id": "g7h8i9"
}
```
**Solução**: CPF/CNPJ não pode ser alterado. Crie um novo comprador se necessário.
***
## Próximos Passos
* [Criar Novo Comprador](/developers/cadastro/compradores/criar)
* [Buscar por CPF/CNPJ](/developers/cadastro/compradores/buscar-cpf-cnpj)
* [Remover Comprador](/developers/cadastro/compradores/remover)
* [Criar Transação](/developers/transacoes/criar-transacao-sem-checkout/cartao)
# Remover Comprador
Endpoint para remover (deletar) um comprador do sistema.
## Endpoint
```
DELETE /v1/marketplaces/{marketplace_id}/buyers/{buyer_id}
```
## Request
```bash
curl --location --request DELETE 'https://api.gopag.com.br/v1/marketplaces/abc123.../buyers/e4e8c5b569da48b28d896385f5481bcf' \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
## Response: 200 OK
```json
{
"id": "e4e8c5b569da48b28d896385f5481bcf",
"resource": "buyer",
"deleted": true,
"deleted_at": "2025-12-21T15:30:00Z"
}
```
## Response: 404 Not Found
```json
{
"status": 404,
"detail": "Buyer not found",
"trace_id": "a1b2c3"
}
```
***
## ⚠️ ATENÇÃO - OPERAÇÃO IRREVERSÍVEL
### O que acontece ao remover um comprador:
✅ **É removido:**
* Cadastro do comprador
* Cartões tokenizados vinculados ao comprador
* Dados pessoais (nome, email, telefone, endereço)
* Metadata customizada
❌ **NÃO é removido:**
* Transações passadas (histórico preservado)
* Registros de auditoria
* Logs de operações
### Impacto em Transações
```
┌─────────────────┐
│ Comprador │
│ ID: e4e8c5b... │ ──┐
└─────────────────┘ │
│
┌─────────────────┐ │ ┌──────────────────┐
│ Transação 1 │───┼──→│ Histórico │
│ 2025-01-10 │ │ │ Preservado ✅ │
└─────────────────┘ │ └──────────────────┘
│
┌─────────────────┐ │
│ Transação 2 │───┤
│ 2025-02-15 │ │
└─────────────────┘ │
│
[DELETE] │
↓ │
┌─────────────────┐ │
│ Comprador │ │
│ REMOVIDO ❌ │←──┘
└─────────────────┘
```
***
## Exemplos de Uso
### Remover Comprador Simples
```javascript
async function deleteBuyer(buyerId) {
const response = await fetch(
`https://api.gopag.com.br/v1/marketplaces/${marketplaceId}/buyers/${buyerId}`,
{
method: 'DELETE',
headers: {
'Authorization': `Bearer ${accessToken}`
}
}
);
if (response.ok) {
const result = await response.json();
console.log('Comprador removido:', result.id);
return result;
} else {
throw new Error('Erro ao remover comprador');
}
}
// Uso
await deleteBuyer('e4e8c5b569da48b28d896385f5481bcf');
```
### Remover com Confirmação
```python
def delete_buyer_with_confirmation(buyer_id):
"""Remove comprador após buscar e confirmar dados"""
# 1. Buscar dados do comprador
buyer = get_buyer_details(buyer_id)
# 2. Confirmar dados
print(f"Tem certeza que deseja remover?")
print(f"Nome: {buyer['first_name']} {buyer['last_name']}")
print(f"CPF: {buyer['taxpayer_id']}")
print(f"Email: {buyer['email']}")
confirm = input("Digite 'CONFIRMAR' para prosseguir: ")
if confirm != 'CONFIRMAR':
print("Operação cancelada")
return None
# 3. Remover comprador
url = f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/buyers/{buyer_id}'
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.delete(url, headers=headers)
if response.status_code == 200:
result = response.json()
print(f"Comprador removido com sucesso em {result['deleted_at']}")
return result
else:
response.raise_for_status()
# Uso
delete_buyer_with_confirmation('e4e8c5b...')
```
### Verificar Transações Antes de Remover
```php
0) {
throw new Exception(
"Não é possível remover: existem " . count($recentTransactions) .
" transações nos últimos 30 dias"
);
}
// 2. Verificar se há transações pendentes
$pendingTransactions = getPendingTransactions($buyerId);
if (count($pendingTransactions) > 0) {
throw new Exception(
"Não é possível remover: existem transações pendentes"
);
}
// 3. Seguro para remover
return deleteBuyer($buyerId);
}
function deleteBuyer($buyerId) {
global $marketplaceId, $accessToken;
$url = "https://api.gopag.com.br/v1/marketplaces/{$marketplaceId}/buyers/{$buyerId}";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $accessToken
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
return json_decode($response, true);
} else {
throw new Exception("Erro ao remover comprador: HTTP {$httpCode}");
}
}
?>
```
### Remover em Lote (Com Cuidado!)
```javascript
/**
* Remove múltiplos compradores
* USE COM EXTREMO CUIDADO!
*/
async function bulkDeleteBuyers(buyerIds, safetyCheck = true) {
const results = {
deleted: [],
failed: [],
skipped: []
};
for (const buyerId of buyerIds) {
try {
// Verificação de segurança opcional
if (safetyCheck) {
const hasRecentActivity = await checkRecentActivity(buyerId);
if (hasRecentActivity) {
results.skipped.push({
id: buyerId,
reason: 'Atividade recente detectada'
});
continue;
}
}
// Remover comprador
const result = await deleteBuyer(buyerId);
results.deleted.push(result);
// Aguardar entre requisições para evitar rate limit
await sleep(1000);
} catch (error) {
results.failed.push({
id: buyerId,
error: error.message
});
}
}
return results;
}
// Uso (com muito cuidado!)
const buyersToDelete = ['id1', 'id2', 'id3'];
const results = await bulkDeleteBuyers(buyersToDelete, true);
console.log('Removidos:', results.deleted.length);
console.log('Falhas:', results.failed.length);
console.log('Ignorados:', results.skipped.length);
```
***
## Casos de Uso
### 1. LGPD - Direito ao Esquecimento
```javascript
/**
* Implementar requisição de exclusão de dados (LGPD)
*/
async function processDataDeletionRequest(taxpayerId, requestReason) {
try {
// 1. Buscar comprador por CPF
const buyer = await searchBuyerByCPF(taxpayerId);
if (!buyer) {
return { status: 'not_found', message: 'Comprador não encontrado' };
}
// 2. Registrar solicitação de exclusão
await logDeletionRequest({
buyer_id: buyer.id,
taxpayer_id: taxpayerId,
reason: requestReason,
requested_at: new Date().toISOString()
});
// 3. Verificar período de retenção legal
const retentionPeriod = await checkLegalRetention(buyer.id);
if (!retentionPeriod.canDelete) {
return {
status: 'retention_period',
message: `Dados devem ser mantidos até ${retentionPeriod.deleteAfter}`,
reason: retentionPeriod.reason
};
}
// 4. Remover comprador
const result = await deleteBuyer(buyer.id);
// 5. Registrar conclusão
await logDeletionCompleted({
buyer_id: buyer.id,
deleted_at: result.deleted_at
});
return {
status: 'deleted',
message: 'Dados removidos com sucesso',
deleted_at: result.deleted_at
};
} catch (error) {
await logDeletionError(taxpayerId, error);
throw error;
}
}
```
### 2. Limpeza de Dados de Teste
```python
def cleanup_test_buyers():
"""Remove compradores de teste criados durante desenvolvimento"""
# Buscar compradores com metadata indicando ambiente de teste
test_buyers = get_buyers_by_metadata({'environment': 'test'})
deleted_count = 0
for buyer in test_buyers:
try:
delete_buyer(buyer['id'])
deleted_count += 1
print(f"Removido comprador de teste: {buyer['id']}")
except Exception as e:
print(f"Erro ao remover {buyer['id']}: {str(e)}")
print(f"\nTotal de compradores de teste removidos: {deleted_count}")
return deleted_count
```
***
## Dicas
### ✅ Boas Práticas
1. **Confirme sempre**: Peça confirmação do usuário antes de deletar
2. **Verifique transações**: Confira se há transações pendentes
3. **Registre a ação**: Mantenha log de quem e quando deletou
4. **Considere inativação**: Em vez de deletar, considere marcar como inativo
5. **LGPD**: Implemente processo adequado para direito ao esquecimento
### ⚠️ Cuidados
* **Operação irreversível**: Não há como recuperar dados deletados
* **Cartões removidos**: Tokens de cartão vinculados serão deletados
* **Transações preservadas**: Histórico de transações não é afetado
* **Sem cascade**: Não remove automaticamente recursos relacionados
### 💡 Alternativa: Soft Delete
Em vez de remover permanentemente, considere implementar "soft delete":
```javascript
// Em vez de DELETE, use PATCH para marcar como inativo
async function deactivateBuyer(buyerId) {
return await updateBuyer(buyerId, {
metadata: {
active: false,
deactivated_at: new Date().toISOString(),
deactivation_reason: 'User request'
}
});
}
```
***
## Erros Comuns
### Comprador Não Encontrado
```json
{
"status": 404,
"detail": "Buyer not found",
"trace_id": "a1b2c3"
}
```
**Solução**: Verifique se o `buyer_id` está correto ou se o comprador já foi removido.
### Sem Permissão
```json
{
"status": 403,
"detail": "Insufficient permissions to delete buyer",
"trace_id": "d4e5f6"
}
```
**Solução**: Verifique se o token de acesso tem permissão de escrita.
***
## Próximos Passos
* [Criar Novo Comprador](/developers/cadastro/compradores/criar)
* [Buscar por CPF/CNPJ](/developers/cadastro/compradores/buscar-cpf-cnpj)
* [Atualizar Detalhes](/developers/cadastro/compradores/detalhes)
* [Documentação LGPD](/developers/cadastro/compradores/remover) (em breve)
# Terminais
# Visão Geral
## Introdução
A API de Terminals do GoPag permite gerenciar dispositivos de pagamento (mPOS, PINPAD, Tap to Pay) vinculados aos vendedores. Com esta API você pode:
* **Parear novos terminais** a um vendedor
* **Listar terminais** associados a um vendedor
* **Consultar detalhes** de terminais específicos
* **Monitorar status** e metadados dos dispositivos
## Pré-requisitos
Antes de começar, certifique-se de ter:
1. **Credenciais de API** (Client ID e Client Secret)
2. **Token de Autenticação** OAuth2 válido
3. **Marketplace ID** configurado
4. **Seller ID** do vendedor que receberá os terminais
## Tipos de Terminais
A API suporta os seguintes tipos de terminais:
| Tipo | Descrição | Exemplos |
| -------------- | ---------------------------------------- | ---------------------------------- |
| `mpos` | Máquina de cartão móvel | PAX A920, Gertec GPOS700 |
| `pinpad` | Terminal fixo tradicional | Ingenico MOVE 5000, Verifone VX520 |
| `tap_to_pay` | Pagamento por aproximação via smartphone | iPhone com NFC, Android com NFC |
| `link_payment` | Link de pagamento via web/app | Interface web, QR Code |
## Status dos Terminais
| Status | Descrição |
| ---------- | -------------------------------------------- |
| `active` | Terminal ativo e operacional |
| `inactive` | Terminal desativado temporariamente |
| `pending` | Aguardando ativação |
| `blocked` | Terminal bloqueado por violação de segurança |
## Fluxo de Integração
1. [**Autenticação**](/developers/introducao/autenticacao) - Obter token OAuth2
2. [**Parear Terminal**](/developers/cadastro/terminais/parear) - Vincular novo dispositivo ao vendedor
3. [**Listar Terminais**](/developers/cadastro/terminais/listar) - Consultar todos os terminais do vendedor
4. [**Buscar Terminal**](/developers/cadastro/terminais/buscar) - Obter detalhes de um terminal específico
## Estrutura do Objeto Terminal
```json
{
"id": "a1b2c3d4e5f6789012345678901234ab",
"resource": "terminal",
"seller": "00771bc0349847108f54e200dbc6c325",
"serial_number": "PAX-SN-123456",
"status": "active",
"type": "mpos",
"metadata": {
"device_model": "PAX A920",
"firmware_version": "1.0.5",
"manufacturer": "PAX Technology",
"last_connection": "2025-12-29T15:45:00+00:00"
},
"created_at": "2025-12-01T10:30:00+00:00",
"updated_at": "2025-12-29T15:45:00+00:00"
}
```
## Segurança
* Todos os endpoints requerem autenticação OAuth2
* Apenas o partner que possui o seller pode acessar seus terminais
* Tokens de pareamento são de uso único e expiram em 24 horas
* Logs de auditoria são mantidos para todas as operações
## Próximos Passos
Comece pela [autenticação](/developers/introducao/autenticacao) e depois siga para [parear seu primeiro terminal](/developers/cadastro/terminais/parear).
# Listar Terminais
## Visão Geral
Lista todos os terminais associados a um vendedor específico. Suporta paginação.
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/sellers/{seller_id}/terminals
```
## Autenticação
Requer token OAuth2 do tipo `partner`.
```
Authorization: Bearer {access_token}
```
## Parâmetros da URL
| Parâmetro | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | ------------------------------------------- |
| `marketplace_id` | string | Sim | ID do marketplace (ex: HOMOLOG, PROD) |
| `seller_id` | string | Sim | ID do vendedor (32 caracteres hexadecimais) |
## Parâmetros de Query (Opcionais)
| Parâmetro | Tipo | Padrão | Descrição |
| --------- | ------- | ------ | -------------------------------------------- |
| `limit` | integer | 20 | Número de registros por página (1-100) |
| `offset` | integer | 0 | Número de registros a pular (para paginação) |
## Exemplos de Requisição
### cURL - Listagem Básica
```bash
curl -X GET "https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/00771bc0349847108f54e200dbc6c325/terminals" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
```
### cURL - Com Paginação
```bash
curl -X GET "https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/00771bc0349847108f54e200dbc6c325/terminals?limit=50&offset=0" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
```
### JavaScript
```javascript
async function listTerminals(sellerId, options = {}) {
const params = new URLSearchParams({
limit: options.limit || 20,
offset: options.offset || 0
});
const response = await fetch(
`https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/${sellerId}/terminals?${params}`,
{
headers: {
'Authorization': `Bearer ${accessToken}`
}
}
);
if (!response.ok) {
throw new Error(`Erro: ${response.status}`);
}
return await response.json();
}
// Uso: Listar terminais com paginação
listTerminals('00771bc0349847108f54e200dbc6c325', {
limit: 50,
offset: 0
})
.then(data => {
console.log(`Total: ${data.total}`);
data.items.forEach(terminal => {
console.log(`- ${terminal.serial_number} (${terminal.type})`);
});
})
.catch(error => console.error('Erro:', error));
```
### Python
```python
import requests
def list_terminals(seller_id, access_token, limit=20, offset=0):
"""Lista terminais de um vendedor"""
url = f"https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/{seller_id}/terminals"
headers = {
"Authorization": f"Bearer {access_token}"
}
params = {
"limit": limit,
"offset": offset
}
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
return response.json()
# Uso: Listar terminais com paginação
try:
result = list_terminals(
seller_id="00771bc0349847108f54e200dbc6c325",
access_token="eyJ0eXAiOiJKV1Qi...",
limit=50,
offset=0
)
print(f"Total de terminais: {result['total']}")
print(f"Retornados nesta página: {result['query_count']}")
print(f"Há mais páginas: {result['has_more']}")
for terminal in result['items']:
print(f"\n- ID: {terminal['id']}")
print(f" Número de Série: {terminal['serial_number']}")
print(f" Tipo: {terminal['type']}")
print(f" Status: {terminal['status']}")
except requests.exceptions.HTTPError as e:
print(f"Erro HTTP: {e}")
print(f"Detalhes: {e.response.json()}")
```
### PHP
```php
$filters['limit'] ?? 20,
'offset' => $filters['offset'] ?? 0
]);
$url = "https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/{$sellerId}/terminals?{$queryParams}";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer {$accessToken}"
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
return json_decode($response, true);
} else {
throw new Exception("Erro ao listar terminais: HTTP {$httpCode}");
}
}
// Uso: Listar terminais com paginação
try {
$result = listTerminals(
"00771bc0349847108f54e200dbc6c325",
"eyJ0eXAiOiJKV1Qi...",
[
'limit' => 100,
'offset' => 0
]
);
echo "Total de terminais: " . $result['total'] . "\n";
foreach ($result['items'] as $terminal) {
echo "- " . $terminal['serial_number'] . " (" . $terminal['type'] . ")\n";
}
} catch (Exception $e) {
echo "Erro: " . $e->getMessage() . "\n";
}
```
## Resposta de Sucesso
**Status:** `200 OK`
```json
{
"items": [
{
"resource": "terminal",
"id": 25,
"unique_id": "C73D9704-766C-43AB-BFF8-0244829F0EDD",
"type": "ttpIos",
"description": "Paulo - iPhone15,2",
"status": "unpaired",
"os": "iOS",
"device_model": "iPhone15,2",
"app_version": "1.0.1+48",
"latitude": null,
"longitude": null,
"serial_number": null,
"metadata": null,
"created_at": "2025-12-22 15:37:39",
"updated_at": "2025-12-29 17:18:47"
},
{
"resource": "terminal",
"id": 30,
"unique_id": "69375802",
"type": "paxs920",
"description": "POS s920",
"status": "paired",
"os": null,
"device_model": null,
"app_version": null,
"latitude": null,
"longitude": null,
"serial_number": null,
"metadata": null,
"created_at": "2026-01-02 23:36:51",
"updated_at": "2026-01-02 23:37:11"
}
],
"resource": "terminal",
"has_more": false,
"limit": 20,
"offset": 0,
"total": 2,
"uri": "/v1/marketplaces/HOMOLOG/sellers/00771bc0349847108f54e200dbc6c325/terminals"
}
```
## Campos da Resposta
| Campo | Tipo | Descrição |
| ---------- | ------- | ------------------------------------- |
| `items` | array | Lista de terminais |
| `resource` | string | Sempre `"terminal"` |
| `has_more` | boolean | Indica se há mais páginas disponíveis |
| `limit` | integer | Número de registros por página |
| `offset` | integer | Número de registros pulados |
| `total` | integer | Total de terminais encontrados |
| `uri` | string | URI da requisição |
### Campos do Terminal (em items)
| Campo | Tipo | Descrição |
| --------------- | ------------ | --------------------------------------------------- |
| `id` | integer | ID interno do terminal |
| `unique_id` | string | Identificador único do dispositivo |
| `resource` | string | Sempre `"terminal"` |
| `type` | string | Tipo do terminal (`ttpIos`, `paxs920`, etc) |
| `description` | string | Descrição do terminal |
| `status` | string | Status (`paired`, `unpaired`, `active`, `inactive`) |
| `os` | string\|null | Sistema operacional (iOS, Android, etc) |
| `device_model` | string\|null | Modelo do dispositivo |
| `app_version` | string\|null | Versão do aplicativo |
| `latitude` | number\|null | Latitude da última localização |
| `longitude` | number\|null | Longitude da última localização |
| `serial_number` | string\|null | Número de série do dispositivo |
| `metadata` | object\|null | Metadados adicionais |
| `created_at` | string | Data de criação (Y-m-d H:i:s) |
| `updated_at` | string | Data da última atualização (Y-m-d H:i:s) |
## Paginação
### Exemplo: Buscar Todas as Páginas
```javascript
async function getAllTerminals(sellerId) {
const allTerminals = [];
let offset = 0;
const limit = 50;
let hasMore = true;
while (hasMore) {
const data = await listTerminals(sellerId, { limit, offset });
allTerminals.push(...data.items);
hasMore = data.has_more;
offset += limit;
console.log(`Carregados ${allTerminals.length} de ${data.total} terminais`);
}
return allTerminals;
}
// Uso
getAllTerminals('00771bc0349847108f54e200dbc6c325')
.then(terminals => {
console.log(`Total final: ${terminals.length} terminais`);
});
```
## Erros Comuns
### 400 - Seller ID Inválido
```json
{
"status": 400,
"title": "Bad Request",
"detail": "Seller ID is required in the route"
}
```
**Solução:** Forneça um seller\_id válido (32 caracteres hexadecimais).
### 401 - Não Autorizado
```json
{
"status": 401,
"title": "Unauthorized",
"detail": "Unauthorized to access this seller [trace_id_123]",
"trace_id": "trace_id_123"
}
```
**Solução:** Verifique se o seller pertence ao partner autenticado.
## Boas Práticas
### 1. Implementar Cache
```javascript
class TerminalsCache {
constructor(ttl = 300000) { // 5 minutos
this.cache = new Map();
this.ttl = ttl;
}
get(key) {
const item = this.cache.get(key);
if (!item || Date.now() > item.expiry) {
this.cache.delete(key);
return null;
}
return item.data;
}
set(key, data) {
this.cache.set(key, {
data,
expiry: Date.now() + this.ttl
});
}
}
const cache = new TerminalsCache();
async function listTerminalsWithCache(sellerId, options) {
const cacheKey = `terminals_${sellerId}_${JSON.stringify(options)}`;
const cached = cache.get(cacheKey);
if (cached) return cached;
const data = await listTerminals(sellerId, options);
cache.set(cacheKey, data);
return data;
}
```
### 2. Usar Retry com Backoff
```python
import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
def get_session_with_retry():
session = requests.Session()
retry = Retry(
total=3,
backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry)
session.mount("https://", adapter)
return session
# Uso
session = get_session_with_retry()
response = session.get(url, headers=headers, params=params)
```
### 3. Logging e Monitoramento
```php
$startTime = microtime(true);
try {
$terminals = listTerminals($sellerId, $token, $filters);
$duration = microtime(true) - $startTime;
error_log(sprintf(
"Terminais listados com sucesso - Seller: %s, Total: %d, Tempo: %.2fms",
$sellerId,
$terminals['total'],
$duration * 1000
));
} catch (Exception $e) {
error_log(sprintf(
"Erro ao listar terminais - Seller: %s, Erro: %s",
$sellerId,
$e->getMessage()
));
}
```
## Próximos Passos
* [Buscar Terminal](/developers/cadastro/terminais/buscar) - Obtenha detalhes de um terminal específico
* [Parear Terminal](/developers/cadastro/terminais/parear) - Adicione novos terminais ao vendedor
* [Criar Transação](/developers/transacoes/criar-transacao-maquininhas-e-celular/mpos) - Processe pagamentos
# Buscar Terminal
## Visão Geral
Retorna os detalhes completos de um terminal específico, incluindo metadados, status e informações do dispositivo.
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/sellers/{seller_id}/terminals/{terminal_id}
```
## Autenticação
Requer token OAuth2 do tipo `partner`.
```
Authorization: Bearer {access_token}
```
## Parâmetros da URL
| Parâmetro | Tipo | Obrigatório | Descrição |
| ---------------- | ------- | ----------- | ------------------------------------------- |
| `marketplace_id` | string | Sim | ID do marketplace (ex: HOMOLOG, PROD) |
| `seller_id` | string | Sim | ID do vendedor (32 caracteres hexadecimais) |
| `terminal_id` | integer | Sim | ID numérico do terminal |
## Exemplos de Requisição
### cURL
```bash
curl -X GET https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/00771bc0349847108f54e200dbc6c325/terminals/30 \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
```
### JavaScript
```javascript
async function getTerminal(sellerId, terminalId) {
const response = await fetch(
`https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/${sellerId}/terminals/${terminalId}`,
{
headers: {
'Authorization': `Bearer ${accessToken}`
}
}
);
if (!response.ok) {
const error = await response.json();
throw new Error(error.detail || `Erro: ${response.status}`);
}
return await response.json();
}
// Uso
getTerminal(
'00771bc0349847108f54e200dbc6c325',
'30'
)
.then(terminal => {
console.log('Terminal encontrado:');
console.log(`- ID: ${terminal.id}`);
console.log(`- Unique ID: ${terminal.unique_id}`);
console.log(`- Tipo: ${terminal.type}`);
console.log(`- Status: ${terminal.status}`);
console.log(`- Descrição: ${terminal.description}`);
})
.catch(error => console.error('Erro:', error.message));
```
### Python
```python
import requests
def get_terminal(seller_id, terminal_id, access_token):
"""Busca detalhes de um terminal específico"""
url = f"https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/{seller_id}/terminals/{terminal_id}"
headers = {
"Authorization": f"Bearer {access_token}"
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
return response.json()
elif response.status_code == 404:
raise Exception("Terminal não encontrado")
elif response.status_code == 401:
raise Exception("Não autorizado a acessar este terminal")
else:
response.raise_for_status()
# Uso
try:
terminal = get_terminal(
seller_id="00771bc0349847108f54e200dbc6c325",
terminal_id="30",
access_token="eyJ0eXAiOiJKV1Qi..."
)
print(f"Terminal ID: {terminal['id']}")
print(f"Unique ID: {terminal['unique_id']}")
print(f"Status: {terminal['status']}")
print(f"Tipo: {terminal['type']}")
print(f"Descrição: {terminal['description']}")
except Exception as e:
print(f"Erro: {e}")
```
### PHP
```php
getMessage() . "\n";
}
```
### Ruby
```ruby
require 'net/http'
require 'json'
def get_terminal(seller_id, terminal_id, access_token)
uri = URI("https://app.gopag.com.br/v1/marketplaces/HOMOLOG/sellers/#{seller_id}/terminals/#{terminal_id}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{access_token}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
case response.code
when '200'
JSON.parse(response.body)
when '404'
raise "Terminal não encontrado"
when '401'
raise "Não autorizado"
else
raise "Erro: #{response.code} - #{response.body}"
end
end
# Uso
begin
terminal = get_terminal(
'00771bc0349847108f54e200dbc6c325',
'30',
'eyJ0eXAiOiJKV1Qi...'
)
puts "Terminal ID: #{terminal['id']}"
puts "Unique ID: #{terminal['unique_id']}"
puts "Status: #{terminal['status']}"
puts "Tipo: #{terminal['type']}"
puts "Descrição: #{terminal['description']}"
rescue => e
puts "Erro: #{e.message}"
end
```
## Resposta de Sucesso
**Status:** `200 OK`
```json
{
"resource": "terminal",
"id": 30,
"type": "paxs920",
"description": "POS s920",
"status": "paired",
"os": null,
"latitude": null,
"longitude": null,
"metadata": null,
"unique_id": "69375802",
"device_model": null,
"app_version": null,
"created_at": "2026-01-02 23:36:51",
"updated_at": "2026-01-02 23:37:11",
"serial_number": null
}
```
## Campos da Resposta
| Campo | Tipo | Descrição |
| --------------- | ------------ | --------------------------------------------------- |
| `resource` | string | Sempre `"terminal"` |
| `id` | integer | ID numérico do terminal |
| `unique_id` | string | Identificador único do dispositivo |
| `type` | string | Tipo do terminal (`paxs920`, `ttpIos`, etc) |
| `description` | string | Descrição do terminal |
| `status` | string | Status (`paired`, `unpaired`, `active`, `inactive`) |
| `os` | string\|null | Sistema operacional (iOS, Android, etc) |
| `device_model` | string\|null | Modelo do dispositivo |
| `app_version` | string\|null | Versão do aplicativo |
| `latitude` | number\|null | Latitude da última localização |
| `longitude` | number\|null | Longitude da última localização |
| `serial_number` | string\|null | Número de série do dispositivo |
| `metadata` | object\|null | Metadados adicionais |
| `created_at` | string | Data de criação (Y-m-d H:i:s) |
| `updated_at` | string | Data da última atualização (Y-m-d H:i:s) |
## Erros Comuns
### 404 - Terminal Não Encontrado
```json
{
"status": 404,
"title": "Not Found",
"detail": "Terminal not found [trace_id_456]",
"trace_id": "trace_id_456"
}
```
**Causas:**
* Terminal ID inválido
* Terminal não pertence ao seller especificado
* Terminal foi removido
**Solução:** Verifique o terminal\_id e seller\_id.
### 401 - Não Autorizado
```json
{
"status": 401,
"title": "Unauthorized",
"detail": "Unauthorized to access this seller [trace_id_789]",
"trace_id": "trace_id_789"
}
```
**Causa:** O seller não pertence ao partner autenticado.
**Solução:** Verifique as credenciais e o seller\_id.
### 400 - Parâmetros Inválidos
```json
{
"status": 400,
"title": "Bad Request",
"detail": "Invalid terminal ID format"
}
```
**Causa:** O terminal\_id não tem o formato correto (32 caracteres hexadecimais).
**Solução:** Valide o formato do ID antes de enviar.
## Casos de Uso
### 1. Verificar Status do Terminal
```javascript
async function checkTerminalStatus(sellerId, terminalId) {
try {
const terminal = await getTerminal(sellerId, terminalId);
if (terminal.status === 'active') {
console.log('✅ Terminal ativo e pronto para uso');
return true;
} else {
console.warn(`⚠️ Terminal não está ativo: ${terminal.status}`);
return false;
}
} catch (error) {
console.error('❌ Erro ao verificar terminal:', error.message);
return false;
}
}
```
### 2. Monitorar Última Conexão
```python
from datetime import datetime, timedelta
def check_terminal_connection(seller_id, terminal_id, access_token):
"""Verifica se o terminal conectou recentemente"""
terminal = get_terminal(seller_id, terminal_id, access_token)
if 'last_connection' in terminal['metadata']:
last_conn = datetime.fromisoformat(
terminal['metadata']['last_connection'].replace('+00:00', '')
)
now = datetime.utcnow()
diff = now - last_conn
if diff > timedelta(hours=24):
print(f"⚠️ Terminal offline há {diff.days} dias")
return False
else:
print(f"✅ Terminal conectado há {diff.seconds // 3600} horas")
return True
else:
print("⚠️ Informação de conexão não disponível")
return None
```
### 3. Dashboard de Terminais
```php
0,
'inactive' => 0,
'total' => count($terminalIds),
'by_type' => []
];
foreach ($terminalIds as $terminalId) {
try {
$terminal = getTerminal($sellerId, $terminalId, $accessToken);
// Contar por status
if ($terminal['status'] === 'active') {
$dashboard['active']++;
} else {
$dashboard['inactive']++;
}
// Contar por tipo
$type = $terminal['type'];
if (!isset($dashboard['by_type'][$type])) {
$dashboard['by_type'][$type] = 0;
}
$dashboard['by_type'][$type]++;
} catch (Exception $e) {
error_log("Erro ao buscar terminal {$terminalId}: " . $e->getMessage());
}
}
return $dashboard;
}
```
## Boas Práticas
### 1. Cache de Terminais
```javascript
const terminalCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutos
async function getTerminalCached(sellerId, terminalId) {
const cacheKey = `${sellerId}_${terminalId}`;
const cached = terminalCache.get(cacheKey);
if (cached && Date.now() < cached.expiry) {
return cached.data;
}
const terminal = await getTerminal(sellerId, terminalId);
terminalCache.set(cacheKey, {
data: terminal,
expiry: Date.now() + CACHE_TTL
});
return terminal;
}
```
### 2. Tratamento Robusto de Erros
```python
def get_terminal_safe(seller_id, terminal_id, access_token, retries=3):
"""Busca terminal com retry e tratamento de erros"""
for attempt in range(retries):
try:
return get_terminal(seller_id, terminal_id, access_token)
except requests.exceptions.ConnectionError:
if attempt < retries - 1:
wait = 2 ** attempt # Exponential backoff
time.sleep(wait)
continue
raise
except requests.exceptions.HTTPError as e:
if e.response.status_code in [404, 401]:
# Não faz retry para estes erros
raise
elif attempt < retries - 1:
time.sleep(2 ** attempt)
continue
raise
```
### 3. Logging e Auditoria
```php
function getTerminalWithLogging($sellerId, $terminalId, $accessToken) {
$startTime = microtime(true);
try {
error_log(sprintf(
"[TERMINAL_GET] Buscando terminal - Seller: %s, Terminal: %s",
$sellerId,
$terminalId
));
$terminal = getTerminal($sellerId, $terminalId, $accessToken);
$duration = (microtime(true) - $startTime) * 1000;
error_log(sprintf(
"[TERMINAL_GET] Sucesso - Terminal: %s, Status: %s, Tempo: %.2fms",
$terminal['serial_number'],
$terminal['status'],
$duration
));
return $terminal;
} catch (Exception $e) {
$duration = (microtime(true) - $startTime) * 1000;
error_log(sprintf(
"[TERMINAL_GET] Erro - Seller: %s, Terminal: %s, Erro: %s, Tempo: %.2fms",
$sellerId,
$terminalId,
$e->getMessage(),
$duration
));
throw $e;
}
}
```
## Próximos Passos
* [Listar Terminais](/developers/cadastro/terminais/listar) - Veja todos os terminais do vendedor
* [Parear Terminal](/developers/cadastro/terminais/parear) - Adicione novos terminais
* [Criar Transação](/developers/transacoes/criar-transacao-maquininhas-e-celular/mpos) - Processe pagamentos com o terminal
# Parear Terminal
## Visão Geral
O pareamento vincula um novo terminal (mPOS, PINPAD, Tap to Pay) a um vendedor específico. Este processo é necessário antes que o terminal possa processar transações.
## Endpoint
```
POST /v1/marketplaces/{marketplace_id}/terminals/pairing
```
## Autenticação
Requer token OAuth2 do tipo `partner`.
```
Authorization: Bearer {access_token}
```
## Parâmetros da URL
| Parâmetro | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | ------------------------------------- |
| `marketplace_id` | string | Sim | ID do marketplace (ex: HOMOLOG, PROD) |
## Corpo da Requisição
| Campo | Tipo | Obrigatório | Descrição |
| ---------------- | ------- | ----------- | ------------------------------------------------ |
| `seller` | string | Sim | ID do vendedor (32 caracteres hexadecimais) |
| `marketplace_id` | boolean | Sim | Deve ser `true` para validação |
| `token` | string | Sim | Token de pareamento do terminal |
| `isStaging` | boolean | Não | `true` para ambiente de testes (padrão: `false`) |
## Exemplo de Requisição
### cURL
```bash
curl -X POST https://app.gopag.com.br/v1/marketplaces/HOMOLOG/terminals/pairing \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
-H "Content-Type: application/json" \
-d '{
"seller": "00771bc0349847108f54e200dbc6c325",
"marketplace_id": true,
"token": "MPOS_TOKEN_ABC123XYZ",
"isStaging": false
}'
```
### JavaScript
```javascript
const pairTerminal = async (sellerId, pairingToken) => {
try {
const response = await fetch(
'https://app.gopag.com.br/v1/marketplaces/HOMOLOG/terminals/pairing',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
seller: sellerId,
marketplace_id: true,
token: pairingToken,
isStaging: false
})
}
);
if (!response.ok) {
const error = await response.json();
throw new Error(error.detail || 'Erro ao parear terminal');
}
return await response.json();
} catch (error) {
console.error('Erro no pareamento:', error.message);
throw error;
}
};
// Uso
pairTerminal('00771bc0349847108f54e200dbc6c325', 'MPOS_TOKEN_ABC123XYZ')
.then(terminal => console.log('Terminal pareado:', terminal.id))
.catch(error => console.error('Erro:', error));
```
### Python
```python
import requests
def pair_terminal(seller_id, pairing_token, access_token):
"""Pareia um terminal a um vendedor"""
url = "https://app.gopag.com.br/v1/marketplaces/HOMOLOG/terminals/pairing"
headers = {
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json"
}
payload = {
"seller": seller_id,
"marketplace_id": True,
"token": pairing_token,
"isStaging": False
}
response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
return response.json()
# Uso
try:
terminal = pair_terminal(
seller_id="00771bc0349847108f54e200dbc6c325",
pairing_token="MPOS_TOKEN_ABC123XYZ",
access_token="eyJ0eXAiOiJKV1Qi..."
)
print(f"Terminal pareado com sucesso: {terminal['id']}")
print(f"Número de série: {terminal['serial_number']}")
print(f"Status: {terminal['status']}")
except requests.exceptions.HTTPError as e:
print(f"Erro HTTP: {e}")
print(f"Detalhes: {e.response.json()}")
except Exception as e:
print(f"Erro: {e}")
```
### PHP
```php
$sellerId,
'marketplace_id' => true,
'token' => $pairingToken,
'isStaging' => false
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer {$accessToken}",
"Content-Type: application/json"
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 201) {
return json_decode($response, true);
} else {
$error = json_decode($response, true);
throw new Exception($error['detail'] ?? "Erro ao parear terminal");
}
}
// Uso
try {
$terminal = pairTerminal(
"00771bc0349847108f54e200dbc6c325",
"MPOS_TOKEN_ABC123XYZ",
"eyJ0eXAiOiJKV1Qi..."
);
echo "Terminal pareado: " . $terminal['id'] . "\n";
echo "Tipo: " . $terminal['type'] . "\n";
echo "Status: " . $terminal['status'] . "\n";
} catch (Exception $e) {
echo "Erro: " . $e->getMessage() . "\n";
}
```
## Resposta de Sucesso
**Status:** `201 Created`
```json
{
"id": "a1b2c3d4e5f6789012345678901234ab",
"resource": "terminal",
"seller": "00771bc0349847108f54e200dbc6c325",
"serial_number": "PAX-SN-123456",
"status": "active",
"type": "mpos",
"metadata": {
"device_model": "PAX A920",
"firmware_version": "1.0.5",
"manufacturer": "PAX Technology"
},
"created_at": "2025-12-29T10:30:00+00:00",
"updated_at": "2025-12-29T10:30:00+00:00"
}
```
## Erros Comuns
### 400 - Token Inválido
```json
{
"status": 400,
"title": "Bad Request",
"detail": "Invalid pairing token [trace_id_abc]",
"trace_id": "trace_id_abc"
}
```
**Causa:** O token de pareamento é inválido ou já foi usado.
**Solução:** Obtenha um novo token de pareamento do terminal.
### 401 - Não Autorizado
```json
{
"status": 401,
"title": "Unauthorized",
"detail": "Unauthorized to access this seller [trace_id_def]",
"trace_id": "trace_id_def"
}
```
**Causa:** O seller não pertence ao partner autenticado.
**Solução:** Verifique se o seller\_id está correto e pertence ao seu partner.
### 409 - Terminal Já Pareado
```json
{
"status": 409,
"title": "Conflict",
"detail": "Terminal already paired to another seller [trace_id_ghi]",
"trace_id": "trace_id_ghi"
}
```
**Causa:** O terminal já está vinculado a outro vendedor.
**Solução:** Remova o terminal do vendedor atual antes de parear novamente.
## Validações
* **Seller ID**: Deve ter exatamente 32 caracteres hexadecimais
* **Token**: Obrigatório e de uso único
* **Marketplace ID**: Deve ser `true`
* **Partner**: Deve ter permissão `allowPos`, `allowPinpad` ou `allowTapToPay` dependendo do tipo de terminal
## Boas Práticas
1. **Valide o token antes de enviar**: Certifique-se de que o token é válido e não expirou
2. **Trate erros adequadamente**: Implemente retry logic para erros temporários (5xx)
3. **Armazene o terminal\_id**: Guarde o ID retornado para futuras consultas
4. **Monitore o status**: Verifique se o terminal ficou ativo após o pareamento
5. **Use logging**: Registre todas as tentativas de pareamento para auditoria
## Próximos Passos
* [Listar Terminais](/developers/cadastro/terminais/listar) - Consulte todos os terminais do vendedor
* [Buscar Terminal](/developers/cadastro/terminais/buscar) - Obtenha detalhes de um terminal específico
* [Criar Transação](/developers/transacoes/criar-transacao-maquininhas-e-celular/mpos) - Processe pagamentos com o terminal
# Transações
# Listar Transações
Lista todas as transações de um vendedor específico.
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/sellers/{seller_id}/transactions
```
## Parâmetros de Query
| Parâmetro | Tipo | Obrigatório | Descrição |
| -------------- | ------- | ----------- | --------------------------------------------------------------- |
| `limit` | integer | Não | Quantidade de resultados por página (padrão: 100, máximo: 100) |
| `offset` | integer | Não | Número de registros a pular (padrão: 0) |
| `sort` | string | Não | Campo para ordenação (`created_at`, `-created_at`) |
| `status` | string | Não | Filtrar por status (ver lista abaixo) |
| `payment_type` | string | Não | Filtrar por tipo: `credit`, `debit`, `boleto`, `bolepix`, `pix` |
## Status de Transação
| Status | Descrição |
| ---------------- | ------------------------------------ |
| `pending` | Aguardando processamento |
| `pre_authorized` | Pré-autorizada (cartão não presente) |
| `succeeded` | Aprovada e capturada |
| `failed` | Falhou |
| `canceled` | Cancelada |
| `refunded` | Estornada |
## Request
### cURL
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers/seller456.../transactions?limit=10&status=succeeded' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
### PHP
```php
"https://api.gopag.com.br/v1/marketplaces/{$marketplaceId}/sellers/{$sellerId}/transactions?limit=10&offset=0",
CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$accessToken}"
]
]);
$response = curl_exec($ch);
$transactions = json_decode($response, true);
curl_close($ch);
?>
```
### Python
```python
import requests
response = requests.get(
f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/sellers/{seller_id}/transactions',
params={'limit': 10, 'status': 'succeeded'},
headers={'Authorization': f'Bearer {access_token}'}
)
transactions = response.json()
```
## Response
### Status: 200 OK
```json
{
"resource": "list",
"uri": "/v1/marketplaces/abc123.../sellers/seller456.../transactions",
"limit": 10,
"offset": 0,
"has_more": false,
"query_count": 2,
"total": 2,
"items": [
{
"id": "0009462369b14ee596aabfd27faa97f7",
"status": "succeeded",
"resource": "transaction",
"amount": "150.00",
"original_amount": "150.00",
"currency": "BRL",
"description": "Compra produto XYZ",
"payment_type": "credit",
"transaction_number": "W-12343124",
"sales_receipt": "00d5ce5086c84c0f824cf660b020881a",
"on_behalf_of": "seller456...",
"statement_descriptor": "MINHA LOJA",
"payment_method": {
"id": "2f008ac254964e658be566241cc87c1a",
"resource": "card",
"card_brand": "Visa",
"first4_digits": "4111",
"last4_digits": "1111",
"expiration_month": "12",
"expiration_year": "2026",
"holder_name": "MARIA SANTOS"
},
"refunded": false,
"voided": false,
"captured": true,
"fees": "5.25",
"expected_on": "2025-12-22T00:00:00Z",
"created_at": "2025-12-21T14:30:00Z",
"updated_at": "2025-12-21T14:30:15Z"
},
{
"id": "1110573480c25ff607bbcbe38efba08g8",
"status": "pending",
"resource": "transaction",
"amount": "50.00",
"currency": "BRL",
"description": "Pagamento PIX",
"payment_type": "pix",
"on_behalf_of": "seller456...",
"qr_code": "00020126...",
"qr_code_url": "https://...",
"created_at": "2025-12-21T15:00:00Z",
"updated_at": "2025-12-21T15:00:00Z"
}
]
}
```
## Paginação
```bash
# Primeira página
GET /v1/marketplaces/{id}/sellers/{id}/transactions?limit=100&offset=0
# Segunda página
GET /v1/marketplaces/{id}/sellers/{id}/transactions?limit=100&offset=100
# Terceira página
GET /v1/marketplaces/{id}/sellers/{id}/transactions?limit=100&offset=200
```
## Filtros
### Por Status
```bash
# Apenas transações aprovadas
GET .../transactions?status=succeeded
# Apenas pendentes
GET .../transactions?status=pending
# Apenas estornadas
GET .../transactions?status=refunded
```
### Por Tipo de Pagamento
```bash
# Apenas cartão de crédito
GET .../transactions?payment_type=credit
# Apenas PIX
GET .../transactions?payment_type=pix
# Apenas boleto
GET .../transactions?payment_type=boleto
```
### Ordenação
```bash
# Mais recentes primeiro (padrão)
GET .../transactions?sort=-created_at
# Mais antigas primeiro
GET .../transactions?sort=created_at
```
## Próximos Passos
* [Detalhes de Transação](/developers/transacoes/detalhes)
* [Capturar Transação](/developers/transacoes/capturar)
* [Tokenizar Cartão](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/transacoes/tokenizar.md)
* [Criar Transação](/developers/transacoes/criar-transacao-sem-checkout/cartao)
# Detalhes da Transação
Recupera informações completas de uma transação específica pelo ID.
## Endpoint
```
GET /v1/marketplaces/{marketplace_id}/transactions/{transaction_id}
```
## Parâmetros de Path
| Parâmetro | Tipo | Descrição |
| ---------------- | ------ | --------------------- |
| `marketplace_id` | string | ID do marketplace |
| `transaction_id` | string | ID único da transação |
## Request
### cURL
```bash
curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../transactions/0009462369b14ee596aabfd27faa97f7' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```
### PHP
```php
"https://api.gopag.com.br/v1/marketplaces/{$marketplaceId}/transactions/{$transactionId}",
CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$accessToken}"
]
]);
$response = curl_exec($ch);
$transaction = json_decode($response, true);
curl_close($ch);
?>
```
### Python
```python
import requests
response = requests.get(
f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/transactions/{transaction_id}',
headers={'Authorization': f'Bearer {access_token}'}
)
transaction = response.json()
```
## Response
### Status: 200 OK - Transação de Cartão
```json
{
"id": "0009462369b14ee596aabfd27faa97f7",
"status": "succeeded",
"resource": "transaction",
"amount": "150.00",
"original_amount": "150.00",
"currency": "BRL",
"description": "Compra produto XYZ",
"payment_type": "credit",
"transaction_number": "W-12343124",
"sales_receipt": "00d5ce5086c84c0f824cf660b020881a",
"on_behalf_of": "1e5ee2e290d040769806c79e6ef94ee1",
"statement_descriptor": "MINHA LOJA",
"payment_method": {
"id": "2f008ac254964e658be566241cc87c1a",
"resource": "card",
"description": "Cartão Visa",
"card_brand": "Visa",
"first4_digits": "4111",
"last4_digits": "1111",
"expiration_month": "12",
"expiration_year": "2026",
"holder_name": "MARIA SANTOS",
"is_active": true,
"is_valid": true,
"is_verified": true,
"customer": "e4e8c5b569da48b28d896385f5481bcf",
"fingerprint": "9f2843f0c1b08d6018927b4e5e884a869ae49",
"uri": "/v1/marketplaces/abc123.../cards/2f008ac254964e658be566241cc87c1a",
"metadata": {},
"created_at": "2025-12-20T10:00:00Z",
"updated_at": "2025-12-20T10:00:00Z"
},
"point_of_sale": {
"entry_mode": "chip",
"identification_number": "4b7d03e6aa01463bb5673f04a7717db9"
},
"installment_plan": {
"number_installments": 3,
"installment_amount": "50.00"
},
"refunded": false,
"voided": false,
"captured": true,
"fees": "5.25",
"reference_id": "PED-12345",
"uri": "/v1/marketplaces/abc123.../transactions/0009462369b14ee596aabfd27faa97f7",
"metadata": {
"order_id": "ORDER-12345",
"customer_ip": "203.0.113.42"
},
"expected_on": "2025-12-22T00:00:00Z",
"created_at": "2025-12-21T14:30:00Z",
"updated_at": "2025-12-21T14:30:15Z"
}
```
### Status: 200 OK - Transação PIX
```json
{
"id": "abc123def456ghi789jkl012",
"status": "succeeded",
"resource": "transaction",
"amount": "50.00",
"original_amount": "50.00",
"currency": "BRL",
"description": "Pagamento PIX",
"payment_type": "pix",
"on_behalf_of": "1e5ee2e290d040769806c79e6ef94ee1",
"qr_code": "00020126580014br.gov.bcb.pix...",
"qr_code_url": "https://api.gopag.com.br/qr/abc123...",
"pix_expiration_date_time": "2025-12-22T23:59:59Z",
"pix_details": {
"end_to_end_id": "E12345678202512211435...",
"paid_at": "2025-12-21T14:35:00Z"
},
"fees": "1.50",
"reference_id": "PIX-67890",
"created_at": "2025-12-21T14:30:00Z",
"updated_at": "2025-12-21T14:35:00Z"
}
```
### Status: 200 OK - Transação Boleto
```json
{
"id": "def456ghi789jkl012mno345",
"status": "pending",
"resource": "transaction",
"amount": "300.00",
"original_amount": "300.00",
"currency": "BRL",
"description": "Pedido #12345",
"payment_type": "boleto",
"on_behalf_of": "1e5ee2e290d040769806c79e6ef94ee1",
"customer": "e4e8c5b569da48b28d896385f5481bcf",
"fees": "3.90",
"reference_id": "BOL-11111",
"created_at": "2025-12-21T10:00:00Z",
"updated_at": "2025-12-21T10:00:00Z"
}
```
## Campos da Resposta
### Campos Comuns
| Campo | Tipo | Descrição |
| ----------------- | ------ | ------------------------------------ |
| `id` | string | ID único da transação |
| `status` | string | Status atual (ver tabela abaixo) |
| `resource` | string | Sempre `"transaction"` |
| `amount` | string | Valor da transação (formato decimal) |
| `original_amount` | string | Valor original antes de descontos |
| `currency` | string | Moeda (sempre `"BRL"`) |
| `description` | string | Descrição da transação |
| `payment_type` | string | Tipo de pagamento |
| `on_behalf_of` | string | ID do vendedor |
| `fees` | string | Taxa cobrada |
| `reference_id` | string | Identificador externo (opcional) |
| `created_at` | string | Data/hora de criação |
| `updated_at` | string | Data/hora da última atualização |
### Status da Transação
| Status | Descrição |
| ---------------- | ------------------------------------- |
| `pending` | Aguardando processamento |
| `pre_authorized` | Pré-autorizada (cartão não capturado) |
| `succeeded` | Aprovada e capturada |
| `failed` | Falhou/Negada |
| `canceled` | Cancelada |
| `refunded` | Estornada total ou parcialmente |
### Campos Específicos por Tipo
#### Cartão (`payment_type: credit/debit`)
| Campo | Descrição |
| ------------------ | ------------------------------------- |
| `payment_method` | Objeto com dados do cartão tokenizado |
| `installment_plan` | Plano de parcelamento (se crédito) |
| `point_of_sale` | Dados do terminal (se presencial) |
| `captured` | Indica se foi capturada |
| `refunded` | Indica se foi estornada |
| `voided` | Indica se foi cancelada |
#### PIX (`payment_type: pix`)
| Campo | Descrição |
| -------------------------- | ------------------------------- |
| `qr_code` | String do QR Code |
| `qr_code_url` | URL da imagem do QR Code |
| `pix_expiration_date_time` | Data/hora de expiração |
| `pix_details` | Detalhes do pagamento (se pago) |
#### Boleto (`payment_type: boleto/bolepix`)
| Campo | Descrição |
| ------------------------ | ----------------------------- |
| `boleto.barcode` | Código de barras (44 dígitos) |
| `boleto.digitable_line` | Linha digitável formatada |
| `boleto.url` | URL do PDF do boleto |
| `boleto.expiration_date` | Data de vencimento |
## Casos de Uso
### 1. Verificar Status de Pagamento
```php
```
### 2. Exibir Comprovante
```javascript
async function exibirComprovante(transactionId) {
const transaction = await getTransactionDetails(transactionId);
const comprovante = {
id: transaction.id,
valor: transaction.amount,
data: transaction.created_at,
status: transaction.status,
forma_pagamento: transaction.payment_type
};
if (transaction.payment_type === 'credit' || transaction.payment_type === 'debit') {
comprovante.cartao = {
bandeira: transaction.payment_method.card_brand,
final: transaction.payment_method.last4_digits
};
}
return comprovante;
}
```
## Erros
### 404 Not Found
```json
{
"status": 404,
"detail": "Transaction not found",
"trace_id": "a1b2c3"
}
```
**Solução**: Verifique se o `transaction_id` está correto.
## Próximos Passos
* [Listar Transações](/developers/transacoes/listar)
* [Capturar Transação](/developers/transacoes/capturar)
* [Criar Transação](/developers/transacoes/criar-transacao-sem-checkout/cartao)
* [Tokenizar Cartão](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/transacoes/tokenizar.md)
# Capturar Transação
Captura uma transação pré-autorizada de cartão de crédito (card-not-present).
## Quando Usar
Use este endpoint quando você criou uma transação com `capture: false` e agora deseja capturar o valor pré-autorizado.
**Fluxo típico:**
1. Cliente faz pedido → Cria transação com `capture: false`
2. Produto é separado/confirmado → Captura a transação
3. Pagamento é processado → Cliente é cobrado
**⚠️ IMPORTANTE**:
* Apenas transações com status `pre_authorized` podem ser capturadas
* Prazo para captura: 5 dias corridos após pré-autorização
* Após o prazo, a pré-autorização é cancelada automaticamente
## Endpoint
```
POST /v1/marketplaces/{marketplace_id}/transactions/{transaction_id}/capture
```
## Parâmetros de Path
| Parâmetro | Tipo | Descrição |
| ---------------- | ------ | ------------------------------ |
| `marketplace_id` | string | ID do marketplace |
| `transaction_id` | string | ID da transação pré-autorizada |
## Request Body (Opcional)
Você pode capturar um valor diferente do pré-autorizado (menor):
```json
{
"amount": 12000,
"on_behalf_of": "SELLER_ID"
}
```
| Campo | Tipo | Obrigatório | Descrição |
| -------------- | ------- | ----------- | -------------------------------------------------------------- |
| `amount` | integer | Não | Valor a capturar em centavos (deve ser ≤ valor pré-autorizado) |
| `on_behalf_of` | string | Sim | ID do vendedor |
## Request
### Captura Total (Valor Completo)
#### cURL
```bash
curl --location --request POST 'https://api.gopag.com.br/v1/marketplaces/abc123.../transactions/0009462369b14ee596aabfd27faa97f7/capture' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"on_behalf_of": "1e5ee2e290d040769806c79e6ef94ee1"
}'
```
#### PHP
```php
$sellerId
];
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://api.gopag.com.br/v1/marketplaces/{$marketplaceId}/transactions/{$transactionId}/capture",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$accessToken}",
'Content-Type: application/json'
]
]);
$response = curl_exec($ch);
$transaction = json_decode($response, true);
curl_close($ch);
?>
```
### Captura Parcial (Valor Menor)
```bash
curl --location --request POST 'https://api.gopag.com.br/v1/marketplaces/abc123.../transactions/0009462369b14ee596aabfd27faa97f7/capture' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"amount": 12000,
"on_behalf_of": "1e5ee2e290d040769806c79e6ef94ee1"
}'
```
#### Python
```python
import requests
# Captura parcial
data = {
'amount': 12000, # R$ 120,00 (de R$ 150,00 pré-autorizados)
'on_behalf_of': seller_id
}
response = requests.post(
f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/transactions/{transaction_id}/capture',
json=data,
headers={'Authorization': f'Bearer {access_token}'}
)
transaction = response.json()
```
## Response
### Status: 200 OK - Captura Total
```json
{
"id": "0009462369b14ee596aabfd27faa97f7",
"status": "succeeded",
"resource": "transaction",
"amount": "150.00",
"original_amount": "150.00",
"currency": "BRL",
"description": "Compra produto XYZ",
"payment_type": "credit",
"transaction_number": "W-12343124",
"sales_receipt": "00d5ce5086c84c0f824cf660b020881a",
"on_behalf_of": "1e5ee2e290d040769806c79e6ef94ee1",
"statement_descriptor": "MINHA LOJA",
"payment_method": {
"id": "2f008ac254964e658be566241cc87c1a",
"resource": "card",
"card_brand": "Visa",
"first4_digits": "4111",
"last4_digits": "1111",
"expiration_month": "12",
"expiration_year": "2026",
"holder_name": "MARIA SANTOS"
},
"refunded": false,
"voided": false,
"captured": true,
"fees": "5.25",
"fee_details": {
"amount": "5.25",
"currency": "BRL",
"type": "transaction_fee",
"description": "Taxa de transação"
},
"uri": "/v1/marketplaces/abc123.../transactions/0009462369b14ee596aabfd27faa97f7",
"metadata": {},
"expected_on": "2025-12-22T00:00:00Z",
"created_at": "2025-12-21T14:30:00Z",
"updated_at": "2025-12-21T14:35:00Z"
}
```
### Status: 200 OK - Captura Parcial
```json
{
"id": "0009462369b14ee596aabfd27faa97f7",
"status": "succeeded",
"resource": "transaction",
"amount": "120.00",
"original_amount": "150.00",
"currency": "BRL",
"captured": true,
"captured_amount": "120.00",
"pre_authorized_amount": "150.00",
"released_amount": "30.00",
"created_at": "2025-12-21T14:30:00Z",
"updated_at": "2025-12-21T14:35:00Z"
}
```
**Observações sobre captura parcial:**
* `amount`: Valor efetivamente capturado
* `original_amount`: Valor pré-autorizado original
* `released_amount`: Valor liberado de volta ao limite do cartão
## Casos de Uso
### 1. E-commerce - Captura Após Separação
```php
'credit',
'amount' => 15000,
'capture' => false, // Apenas pré-autoriza
// ... outros campos
]);
salvarTransactionId($pedidoId, $transaction['id']);
// 2. Produto é separado e confirmado
separarProduto($pedidoId);
// 3. Captura o pagamento
$transactionId = getTransactionId($pedidoId);
$captured = captureTransaction($transactionId, $sellerId);
if ($captured['status'] === 'succeeded') {
liberarParaEnvio($pedidoId);
}
}
?>
```
### 2. Marketplace - Captura com Ajuste de Valor
```javascript
async function capturarComDesconto(transactionId, descontoAplicado) {
const transaction = await getTransactionDetails(transactionId);
const valorOriginal = parseFloat(transaction.amount) * 100; // Converter para centavos
const valorFinal = valorOriginal - descontoAplicado;
// Captura apenas o valor com desconto
const captured = await captureTransaction(transactionId, {
amount: valorFinal,
on_behalf_of: transaction.on_behalf_of
});
return captured;
}
// Uso: Cliente tinha cupom de desconto de R$ 30,00
await capturarComDesconto('abc123...', 3000);
```
### 3. Reserva de Hotel - Captura Diferenciada
```python
def processar_check_out(reserva_id):
# Pré-autorização: R$ 500,00 (valor estimado)
# Check-out: R$ 450,00 (valor real após consumo)
reserva = get_reserva(reserva_id)
transaction_id = reserva['transaction_id']
valor_final = calcular_valor_final(reserva_id) # R$ 450,00
# Captura apenas valor consumido
captured = capture_transaction(
transaction_id=transaction_id,
amount=valor_final * 100, # Converter para centavos
on_behalf_of=reserva['seller_id']
)
# Diferença de R$ 50,00 é liberada automaticamente
return captured
```
## Erros
### 400 Bad Request - Já Capturada
```json
{
"status": 400,
"detail": "Transaction already captured",
"trace_id": "a1b2c3"
}
```
**Solução**: Esta transação já foi capturada anteriormente.
### 400 Bad Request - Status Inválido
```json
{
"status": 400,
"detail": "Transaction status must be pre_authorized to capture",
"trace_id": "d4e5f6"
}
```
**Solução**: Apenas transações com status `pre_authorized` podem ser capturadas.
### 400 Bad Request - Valor Maior
```json
{
"status": 400,
"detail": "Capture amount cannot exceed pre-authorized amount",
"trace_id": "g7h8i9"
}
```
**Solução**: O valor de captura deve ser menor ou igual ao pré-autorizado.
## Boas Práticas
### ✅ Recomendado
* Capture assim que possível após confirmação
* Use captura parcial quando valor final for menor
* Configure webhooks para monitorar expiração
* Cancele explicitamente se não for capturar
### ❌ Evite
* Deixar pré-autorizações sem ação por dias
* Tentar capturar valores maiores que o pré-autorizado
* Capturar sem verificar disponibilidade de estoque
* Ignorar erros de captura
## Próximos Passos
* [Criar Transação com Pré-autorização](/developers/transacoes/criar-transacao-sem-checkout/cartao)
* [Detalhes da Transação](/developers/transacoes/detalhes)
* [Listar Transações](/developers/transacoes/listar)
# Criar Transação (Checkout GoPag)
# Link de Pagamento
Crie um link de pagamento com interface pronta para compartilhar com seus clientes via WhatsApp, email, SMS ou redes sociais.
## Endpoint
```
POST /v1/marketplaces/{marketplace_id}/transactions
```
## Visão Geral
O Link de Pagamento gera uma URL única com interface completa para que o cliente finalize o pagamento sem necessidade de integração frontend. Ideal para:
* 🛍️ **E-commerce**: Checkout rápido
* 💬 **WhatsApp**: Vendas por mensagem
* 📧 **Email**: Cobranças personalizadas
* 📱 **SMS**: Links diretos para pagamento
* 🔗 **Redes Sociais**: Compartilhamento fácil
## Como Funciona
```
1. Você cria a transação com payment_locale: "link_payment"
2. API retorna um link de pagamento único
3. Cliente acessa o link
4. Interface pronta para pagamento (cartão, PIX, boleto)
5. Cliente finaliza o pagamento
6. Você recebe webhook de confirmação
```
***
## Requisição
```http
POST /v1/marketplaces/{marketplace_id}/transactions HTTP/1.1
Host: api.gopag.com.br
Authorization: Bearer {access_token}
Content-Type: application/json
```
```json
{
"payment_locale": "link_payment",
"payment_type": "credit",
"on_behalf_of": "54f5445fd4544b454654fdf46545465g",
"description": "Cobrança produto XYZ",
"notification": "Você tem um pagamento pendente",
"amount": 15000,
"currency": "BRL",
"installment_plan": {
"number_installments": 3
},
"reference_id": "pedido-12345"
}
```
***
## Parâmetros
### Obrigatórios
| Campo | Tipo | Descrição |
| ---------------- | ------- | ----------------------------- |
| `payment_locale` | string | Deve ser `link_payment` |
| `payment_type` | string | `credit`, `debit` ou `pix` |
| `on_behalf_of` | string | ID do vendedor (32 chars hex) |
| `description` | string | Descrição do pagamento |
| `amount` | integer | Valor em centavos |
### Opcionais
| Campo | Tipo | Descrição |
| -------------------------------------- | ------- | ----------------------------------- |
| `currency` | string | Moeda (padrão: `BRL`) |
| `notification` | string | Mensagem exibida para o cliente |
| `installment_plan` | object | Parcelamento (apenas para `credit`) |
| `installment_plan.number_installments` | integer | Número de parcelas (1-12) |
| `reference_id` | string | Seu identificador único |
***
## Tipos de Pagamento Suportados
### 1. Cartão de Crédito
```json
{
"payment_locale": "link_payment",
"payment_type": "credit",
"on_behalf_of": "54f5445fd4544b454654fdf46545465g",
"description": "Compra parcelada",
"amount": 30000,
"installment_plan": {
"number_installments": 6
},
"reference_id": "pedido-001"
}
```
**Interface gerada:**
* ✅ Formulário de cartão de crédito
* ✅ Seletor de parcelas
* ✅ Validação em tempo real
* ✅ 3D Secure automático
### 2. PIX
```json
{
"payment_locale": "link_payment",
"payment_type": "pix",
"on_behalf_of": "54f5445fd4544b454654fdf46545465g",
"description": "Pagamento via PIX",
"amount": 10000,
"reference_id": "pedido-003"
}
```
**Interface gerada:**
* ✅ QR Code PIX
* ✅ Código PIX copia e cola
* ✅ Confirmação automática
* ✅ Timer de expiração
## Parâmetro `notification`
Mensagem personalizada exibida para o usuário
```json
{
"notification": "Olá João! Complete seu pagamento aqui 😊"
}
```
**Boas práticas:**
* Use o nome do cliente
* Seja claro e objetivo
* Inclua emojis para humanizar
* Máximo 200 caracteres
***
## Resposta de Sucesso
```json
{
"id": "e7f8g9h0i1j2k3l4m5n6o7p8q9r0s1t2",
"status": "pending",
"payment_locale": "link_payment",
"payment_type": "credit",
"amount": 15000,
"currency": "BRL",
"description": "Cobrança produto XYZ",
"on_behalf_of": "54f5445fd4544b454654fdf46545465g",
"payment_link": {
"url": "https://app.gopag.com.br/u/?uuid=cc378516-4a29-11f0-8331-xxxxxx",
"expires_at": "2025-12-28T23:59:59Z"
},
"created_at": "2025-12-21T14:30:00Z",
"trace_id": "a1b2c3"
}
```
### Campos da Resposta
* **payment\_link.url**: URL do link de pagamento a ser compartilhado
* **payment\_link.expires\_at**: Data de expiração do link (padrão: 7 dias)
* **status**: Status inicial sempre `pending`
***
## Exemplo Completo
```bash
curl -X POST https://api.gopag.com.br/v1/marketplaces/abc123.../transactions \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"payment_locale": "link_payment",
"payment_type": "credit",
"on_behalf_of": "54f5445fd4544b454654fdf46545465g",
"description": "Compra de produto XYZ",
"notification": "Complete seu pagamento em até 24h",
"amount": 15000,
"currency": "BRL",
"installment_plan": {
"number_installments": 3
},
"reference_id": "pedido-12345"
}'
```
***
## Segurança
### Links Únicos
Cada link é gerado com ID único e não pode ser reutilizado.
### Expiração
Links expiram após 7 dias (configurável).
### HTTPS Obrigatório
Todas as páginas de pagamento usam HTTPS.
### Segurança dos Dados
Dados de cartão são processados diretamente pelo gateway e nunca passam por seus servidores.
***
## Erros Comuns
### Campo obrigatório ausente
```json
{
"status": 400,
"detail": "Field description is required",
"trace_id": "d4e5f6"
}
```
### Seller não autorizado
```json
{
"status": 401,
"detail": "Unauthorized to access this seller [j1k2l3]",
"trace_id": "j1k2l3"
}
```
***
## Recursos do Link de Pagamento
O link de pagamento gerado possui os seguintes recursos:
* ✅ **Link único e seguro**: Cada transação gera um link exclusivo
* ✅ **Interface responsiva**: Funciona em desktop, mobile e tablet
* ✅ **Múltiplos métodos**: Suporte a cartão de crédito, débito e PIX
* ✅ **QR Code**: Compartilhamento rápido via QR Code
* ✅ **Expiração configurável**: Controle de validade do link
***
## Webhooks
Após processamento na interface de link de pagamento:
### Sucesso
```json
{
"event": "transaction.succeeded",
"transaction_id": "abc123...",
"payment_locale": "payment_link",
"payment_type": "credit",
"status": "succeeded",
"amount": "150.00",
"terminal": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"card": {
"brand": "Visa",
"last4": "1111",
},
"reference_id": "pedido-12345",
"approved_at": "2025-12-21T14:35:00Z"
}
```
### Falha
```json
{
"event": "transaction.failed",
"transaction_id": "abc123...",
"payment_locale": "payment_link",
"status": "failed",
"error_code": "card_declined",
"error_message": "Cartão recusado",
"reference_id": "pedido-12345",
"failed_at": "2025-12-21T14:35:00Z"
}
```
## Próximos Passos
* [MPOS](/developers/transacoes/criar-transacao-maquininhas-e-celular/mpos)
* [Tap to Pay](/developers/transacoes/criar-transacao-maquininhas-e-celular/tap-to-pay)
* [PINPAD](/developers/transacoes/criar-transacao-maquininhas-e-celular/pinpad)
* [Transações via API](/developers/transacoes/criar-transacao-sem-checkout/cartao)
---
[Next Page](/llms-full.txt/1)