Skip to content

GitLab

Switch branch/tag
Find file BlameHistoryPermalink
README.md 8.40 KiB
Open in Web IDE

Integração de Pagamentos

Projeto desenvolvido com APIs para integração de sistemas com o gateway de pagamentos Iugu, Pagarme e Vindi.

A Seguir na Documentação

Ambientes

Elemento Ambiente URL/Descrição
API Docs DEV http://gtiserver02:8081/gtisolutiongatewaypagamentosapi/swagger
API Docs HOMOLOG http://54.233.69.28/gtisolutiongatewaypagamentosapi/
API Docs PROD https://portal.pingseguro.com.br/PingGatewayPagamentosAPI/
Banco de dados DEV/HOMOLOG/PROD PingControlePagamento

IMPORTANTE: Pode haver divergência da documentação em relação aos ambientes. A princípio, a versão mais atualizada é sempre a de DEV, sendo a de PROD a última a ser atualizada. Portanto, sempre consulte a documentação do ambiente em que está trabalhando.

Fluxo de Criação de uma Fatura

Antes de efetivamente criarmos uma fatura na Iugu, os dados são criados em nossa base de dados para que em um eventual problema, possamos regerar se necessário.

sequenceDiagram    
    App->>+API: 1. Criar Fatura    
    API->>+API: 2. Grava Cliente
    API->>+API: 3. Grava Fatura
    API->>+Iugu: 4. Criar Cliente
    Iugu-->>-API: 5. Retorna Id
    API->>+Iugu: 6. Criar Fatura
    Iugu-->>-API: 7. Rerorna Fatura
    API->>+API: 8. Atualiza Id da Fatura
    API-->>-App: 9. Retorna Fatura

Operações Comuns

As operações abaixo são comuns a todos os gateways de pagamentos, pois apenas realizam consulta na nossa base de dados, sem acesso a nenhum gateway específico.

Consulta de Fatura

GET /pagamentos/v1/fatura/{id}

Recupera os dados gerais da fatura, bem como parcelas e splits de pagamento, caso existam.

Parcelas são geradas após a execução do gatilho Fatura Criada e os Splits de pagamento (apenas Iugu), após a execução do gatilho Fatura Paga.

Consulta de Parcelas

GET /pagamentos/v1/fatura/{id}/parcelas

Recupera os dados das parcelas de uma fatura.

Parcelas são geradas após a execução do gatilhos Fatura Criada.

Criação de Fatura no Banco de Dados

Esta operação é utilizada para os casos em que a fatura é criada diretamente no provedor de pagamentos por outra aplicação, como por exemplo, quando o API de criação de fatura do provedor é chamada direto pela aplicação web e não por esse gateway de pagamentos.

Este endpoit cria a estrutura de Fatura, Itens da Fatura, Cliente da Fatura e Parcelas da Fatura.

POST /pagamentos/v1/fatura

Esta opção foi criada para atender à Accesstage que não tem a opção de criação da primeira fatura utilizando token de cartão de crédito mas, apenas com os dados do cartão.

Operações Iugu

Operações Pagarme

Operações Vindi

Gatilhos

Os gatilhos são enviados pelos gatewais de pagamento a cada evento que ocorre em uma fatura e são processamentos realizados de forma offline, abaixo os eventos que estão sendo tratados.

Evento Gateway Ação Observações
Fatura Criada Iugu, Pagarme e Vindi Criação do registro de parcelas Mesmo a fatura sendo à vista, é criada uma parcela
Fatura Paga Iugu e Vindi Marcação da data de pagamento da fatura na parcela (à vista) Para faturas parceladas, essa marcação é feita no evento de Parcela Paga. Neste momento ocorrerá a criação da configuração do split de pagamento, caso a fatura o tenha
Fatura Cancelada Iugu e Pagarme Marcação da data de cancelamento na fatura Para faturas parceladas, todas as parcelas restantes e não pagas serão marcadas como canceladas
Fatura Estornada Iugu e Pagarme Marcação da data de estorno na fatura Para faturas parceladas, todas as parcelas pagas serão marcadas como estornadas, as demais como canceladas
Parcela Paga Iugu Marcação da data de pagamento na parcela
Em Análise Iugu Criação da data de análise na fatura Evento disparado quando cobrança em duas etapas

Processos Agendados

Os processos agendados são realizados de forma offline e são executados de forma periódica, abaixo os eventos que estão sendo tratados.

Evento Gateway Ação Periodicidade Observações
Parcela Paga Pagarme Marcação da data de pagamento na parcela Diária Ver Detalhes

Notificação de Observadores dos Gatilhos e Processos Agendados

Há a possibilidade de cadastrar observadores para cada gatilho e assim que o mesmo for processado com sucesso, os observadores serão notificados e poderão realizar alguma ação.

Ao processar um gatilho de Fatura Paga, a sua aplicação será notificada para que possa realizar alguma ação, como por exemplo, marcar o pagamento da mesma no seu sistema.

Modelo do Json Enviado aos Observadores

{
  "ChaveIdentExterna": "ABC123", // Chave de identificação da fatura no seu sistema
  "IdFatura": "698EB9B1D64E4901A838DB59F6E754A2",
  "IdAssinatura": null, // Caso a fatura seja de uma assinatura
  "NumeroParcela": null, // Caso a fatura seja parcelada
  "NumeroParcelas": null, // Caso a fatura seja parcelada
  "DataVencimento": "2023-03-12", 
  "DataProcessamento": "2023-03-12",
  "DataPagamento": "2023-03-12",
  "ValorParcela": null, // Caso a fatura seja parcelada
  "Status": "fatura.paga"
}

Cadastro de Observadores

Abaixo a relação de tabelas que precisam ser cadastradas.

Tabela Coluna Descrição Observações
Aplicacao Id Identificador da aplicação Formato de GUID
Aplicacao NomeAplicacao Nome da aplicação
EventoAplicacao Id Identificador do Evento Formato de GUID
EventoAplicacao TipoEvento Tipo de Evento Ex.: fatura.paga (vide relação abaixo)
GatilhoAplicacao Id Identificador do Gatilho Formato de GUID
GatilhoAplicacao IdEvento Id do Evento Da tabela EventoAplicacao
GatilhoAplicacao IdAplicacao Id da Aplicação Da tabela Aplicacao
GatilhoAplicacao Url Url que receberá os dados Deve ser POST
GatilhoAplicacao Autenticacao Token de autenticação, se necessário Será passado como Basic

Tipos de Eventos

Evento Gateway Descrição
fatura.pendente Iugu Quando ainda não foi processado o pagamento da fatura
fatura.paga Iugu, Pagarme e Vindi Quando a fatura em boleto foi paga ou quando foi aceita pela adiquirente de cartão de crédito
fatura.cancelada Iugu e Pagarme Quando solicitado o cancelamento total da fatura
fatura.estornada Iugu e Pagarme Quando solicitado o estorno/cancelamento total da fatura
fatura.parcialmente_estornada Pagarme Quando foi estornado apenas uma parte do valor do total da fatura
fatura.aguardando_captura Iugu Quando a fatura criada em duas etapas e está aguardando "efetivar" a compra
fatura.parcela_paga Iugu e Pagarme Quando uma parcela foi paga