Integrando com o ControlPay
Esta documentação está desatualizada.
Para informações sempre atualizadas, acesse https://paygodev.readme.io/docs.
A integração
Uma transação cadastrada no ControlPay pode ser completada utilizando as plataformas acima descritas sem que seja preciso interagir individualmente com as diferentes respostas de cada sistema. O ControlPay cria uma camada de abstração destas integrações, fazendo com que você somente precise considerar as diferenças entre os “Fluxos de pagamento”. Fluxos de pagamento são compostos por workflows (ou processos, sequência de etapas) para realização de uma cobrança. Cada uma das diferentes plataformas usa um fluxo de pagamento. Diferentes plataformas, que usem o mesmo fluxo, podem ser utilizadas sem nenhuma mudança no fluxo e na integração com o Control Pay uma vez criada. Diferentes fluxos de pagamento exigirão diferentes ações, mas, como veremos adiante, nada muito complexo. Os fluxos de pagamento hoje disponíveis na plataforma são:
- Pagamento sem confirmação;
- TEF;
- Gateway.
Para se integrar ao ControlPay e utilizar-se de suas funcionalidades você deve inicialmente compreender três coisas:
- Os objetos;
- As APIs;
- Os processos.
Vamos passo a passo.
Os objetos
Objetos são capazes de armazenar informações através de seus atributos e reagir a mensagens enviadas a ele, assim como se relacionar e enviar mensagens a outros objetos. No ControlPay, há centenas de diferentes tipos de objetos, mas poucos são relevantes para a integração de pagamentos. Para se integrar a todas as plataformas disponibilizadas através do ControlPay nós precisaremos de apenas 2 objetos. A “intenção de venda” e o “pagamento externo”. Todavia, estes objetos recebem outros objetos menores, mas importantes ao seu funcionamento. Eles são: a “forma de pagamento”, o “fluxo de pagamento”, o “terminal”, o “produto” e o “status”. Vamos analisar cada um destes objetos individualmente.
Intenção de venda (intencaoVenda)
É o mais importante objeto da nossa integração. Podemos considerar que ele é “a venda”. Toda vez que uma solicitação de operação financeira é enviada ao ControlPay, uma “intenção de venda” é criada (e um objeto intencaoVenda gerado no sistema). Vamos observar um exemplo de um objeto intencaoVenda e na sequência o avaliaremos.
Como pode ser visto no exemplo acima, um objeto intencaoVenda possui mais de 20 atributos, cada um contendo uma parte de informação relevante, referente à operação de venda criada na plataforma Control Pay. Rapidamente podemos reparar: identificador único da transação na plataforma ControlPay (id), valor (valorOriginal), valor em aberto (valorFinal), data e hora da criação da intenção de venda (data) e os objetos formaPagamento, terminal, pagamentoExterno, intencaoVendaStatus e produto.
É através do objeto intencaoVendaStatus, por exemplo, que identificamos o status atual da venda, ou, como chamamos, da “intenção de venda”.
| Campo | Descrição | Tipo |
|---|---|---|
| id | O identificador único da intenção de venda no ControlPay | Inteiro |
| referencia | Referência da transação enviada pela automação | Texto |
| token | Token reduzido de 6 dígitos gerado pelo ControlPay a cada venda. Tokens são únicos para transações em pagamento | Inteiro |
| data | Data da criação da intenção de venda. Formato: dd/mm/aaaa hh:MM:ss.ffff | Data/hora |
| hora | Horário da criação da intenção de venda. Formato: hh:MM:ss | Hora |
| quantidade | Quantidade de produtos da venda | Inteiro |
| valorOriginal | Valor total da intenção de venda, sem formatação | Inteiro |
| valorOriginalFormat | Valor total da intenção de venda, formatado para padrão brasileiro, com centavos após a vírgula | Texto |
| valorAcrescimo | Valor do acréscimo adicionado ao pagamento, utilizado para casos onde deseja-se separar um acréscimo à venda. Exemplo: 10% do garçom | inteiro |
| valorAcrescimoFormat | Valor do acréscimo, formatado para padrão brasileiro, com centavos após a vírgula | Texto |
| valorDesconto | Valor do desconto adicionado ao pagamento, utilizado para casos onde deseja-se separar o desconto à venda. Exemplo: 10% de desconto de alguma promoção específica | Inteiro |
| valorDescontoFormat | Valor do desconto, formatado para padrão brasileiro, com centavos após a vírgula | Texto |
| valorFinal | Valor final da intenção de venda | Inteiro |
| valorFinalFormat | Valor final, formatado para padrão brasileiro, com centavos após a vírgula | Texto |
| gate2allToken | Token gerado pelo GATE2all, retornado em casos de transação e-commerce. Representa a venda na plataforma GATE2all | Texto |
| quantidadeParcelas | Quantidade de parcelas da intenção de venda | Inteiro |
| urlPagamento | Em intenções de venda do tipo e-commerce, a transação deve ser completada utilizando a URL retornada pelo GATE2all. O usuário deverá ser redirecionado para essa URL, onde ele informará os dados do cartão. Este ambiente é PCI-DSS e pode obter esses dados de forma segura | Texto |
| formaPagamento | Objeto que representa a forma de pagamento. Abaixo detalhes sobre esse objeto | Objeto |
| terminal | Objeto com informações do terminal. Nele são retornados o Id do terminal e uma descrição em texto | Objeto |
| pagamentosExternos | Lista de Pagamentos externos associados a essa intenção de venda. Abaixo descrição desse objeto | Lista de Objeto |
| intencaoVendaStatus | Objeto com informações do status da intenção de venda. Nele são retornados o Id do status e uma descrição em texto | Objeto |
| cliente | Id do cliente associado à venda. O cliente (portador do cartão que completará a venda) pode ser cadastrado e associado à intenção de venda. Mandatório para transações de boleto e cartão de crédito digitado com cartão salvo na plataforma para ser utilizado na venda - forma de pagamento 51 e iniciarTransacaoAutomaticamente True | Inteiro |
| produtos | Lista de produtos associados à venda. Produtos podem ser cadastrado no ControlPay para que ele faça a gestão de prdoutos do estabelecimento, caso desejado | Lista de Objeto |
| pedido | Pedido no sistema ControlPay pai da intenção de venda. Um pedido pode ter várias intenções de venda. Uma intenção de venda pode ter apenas um pedido (ou nenhum) associado a ela | Inteiro |
Vamos seguir adiante e entender os demais objetos.
Pagamento Externo (pagamentoExterno)
É, sem dúvidas, o segundo mais importante objeto desta integração. Para entender o que é um objeto pagamentoExterno devemos entender o que é um autorizador. Autorizador é a entidade que valida e verifica as informações enviadas na operação de pagamento. É do autorizador a responsabilidade de autorizar ou negar uma transação financeira. Uma intenção de venda precisa ser processada por um autorizador para que seja completada. O status de uma intenção venda é diretamente afetado pela resposta de um autorizador. Caso a transação seja processada por um adquirente (Bin, Cielo, Getnet, Rede e etc) o autorizador deste adquirente enviará informações relevantes sobre esta transação. Tais informações serão registradas num objeto pagamentoExterno e vinculado ao objeto intencaoVenda correspondente. Não é necessário interpretar o objeto pagamentoExterno para verificar se uma transação foi aprovada ou negada, o Control Pay fará isso pra você e refletirá tal status na intencaoVenda, mas se você precisa de informações retornadas pelo autorizador externo (como comprovante da transação, motivo de não aprovação da transação, dentre outros), você as encontrará neste objeto. Abaixo está um exemplo de pagamentoExterno.
Importante ressaltar que o atributo “respostaAdquirente” sempre refletirá a mensagem completa recebida do adquirente, logo, nenhuma informação é perdida ao utilizar-se a camada de abstração do Control Pay.
| Campo | Tipo | Descrição |
|---|---|---|
| id | Inteiro | Identificador único do Pagamento Externo |
| nsuTid | Alfanumérico | É o código de NSU ou TID retornado pelo autorizador externo |
| autorizacao | Alfanumérico | É o código de autorização retornado pelo autorizador externo |
| adquirente | Alfanumérico | É o nome do autorizador externo |
| codigoRespostaAdquirente | Alfanumérico | É o código de resposta da transação, recebido do autorizador externo |
| mensagemRespostaAdquirente | Alfanumérico | É o texto a ser exibido ao operador, recebido do autorizador externo |
| dataAdquirente | DataHora | É a data e hora recebida do autorizador externo |
| respostaAdquirente | Alfanumérico | É a mensagem completa, recebida do autorizador externo, pela solução de captura |
| comprovanteAdquirente | Alfanumérico | É o comprovante da transação, recebido do autorizador externo (Comprovante "via única") |
| comprovanteEstabelecimento | Alfanumérico | É a via do estabelecimento do comprovante |
| comprovanteCliente | Alfanumérico | É a via do cliente do comprovante |
| bandeira | Alfanumérico | É o nome da bandeira do cartão utilizado na transação (quando aplicável) |
| nomeTitularCartao | Alfanumérico | Nome impresso no cartão utilizado na transação (quando aplicável) |
Status (intencaoVendaStatus / pagamentoExternoStatus)
O objeto status dispensa apresentações. Seu propósito é informar o status do objeto no qual ele está inserido. O objeto status sempre terá dois atributos: id e nome. O “id” é um inteiro, usado para programação do workflow e o “nome” é um texto, para indicação visual do status. Abaixo estão exemplos de status tanto da intencaoVenda como do pagamentoExterno.
Forma de pagamento (formaPagamento)
Como o nome sugere, objetos formaPagamento armazenam as configurações da operação financeira a ser realizada. De todos os atributos existentes na forma de pagamento, um dos mais relevantes para a integração é o “fluxoPagamento”. É através dele que identificamos um diferente fluxo de operação. Embora você não tenha que interagir com cada uma das plataformas de pagamento e suas especificidades, há diferenças entre os fluxos de operação que devem ser administradas pela aplicação que se integra com o ControlPay. São opções válidas de uma forma de pagamento:
Estes diferentes fluxos são identificados como “fluxos de pagamento”. Um objeto formaPagamento tem "fluxoPagamento" como um de seus atributos. Objetos fluxoPagamento têm estrutura idêntica ao objeto status: id e nome.
Assim como no objeto status, o “id” é um inteiro, usado para programação do workflow e o “nome” é um texto, para indicação visual.
Abaixo tabela descrevendo os campos retornados pelo objeto FormaPagamento
| Campo | Descrição | Tipo |
|---|---|---|
| id | O identificador da forma de pagamento | Inteiro |
| nome | Nome da forma de pagamento | Texto |
| Modalidade | Dentro de uma forma de pagamento podemos ter algumas modalidades diferentes. Abaixo lista de formas de pagamento e descrição | Texto |
| permiteParcelamento | Indica se a forma de pagamento permite parcelamento ou não | Booleano |
| solicitaObs | Indica se a forma de pagamento exige observação | Booleano |
| quantidadeMaximaParcelas | Quantidade máxima de parcelas permitida | Inteiro |
| isentoDeTarifa | Indica se a forma de pagamento possui ou não tarifa. Apenas formas de pagamento onde o ControlPay realiza a liquidação do pagamento não são isentas de tarifa. A tarifa é aplicada ao gerar o arquivo de pagamento ao estabelecimento. Isso ocorre quando o ControlPay faz a gestão de pré-pagos, por exemplo, onde ele é responsável pelo pagamento ao lojista referente às vendas processadas no ControlPay | Booleano |
| fluxoPagamento | Objeto que informa o fluxo de pagamento. Nele há o Id do fluxo e um nome descritivo. | Objeto |
Formas de pagamento existentes no ControlPay
Id: 1
PAY2all - Gerar Token: Forma de pagamento do módulo de pré-pagos. Estabelecimento cria a intenção de venda e informa o token ao usuário, que o insere em seu aplicativo ControlPay e confirma o pagamento. Esta forma de pagamento não é mais utilizada devido à extinção do módulo pré-pago no ControlPay.
Id: 2
PAY2all - Enviar venda: Também referente ao módulo de pré-pagos, mas nesse caso o estabelecimento deve selecionar o usuário específico a quem ele deseja enviar a venda. Esta forma de pagamento não é mais utilizada devido à extinção do módulo pré-pago no ControlPay.
Id: 11
POS - Crédito: Utilizado apenas para registro, em caso de venda com POS não integrado. O sistema apenas registra a venda e depois fera um relatório gerencial.
Id: 12
POS - Débito: Idem à forma acima, mas para débito.
Id: 13
POS - Voucher: Meramente informativo para vendas com POS na modalidade Voucher refeição/alimentação.
Id: 41
Dinheiro: Também meramente informativo para vendas feitas com dinheiro.
Id: 21
TEF - Crédito: Transação integrada à plataforma de pagamentos da PayGo. A transação transporta a modalidade até a plataforma de pagamento - Crédito.
Id: 22
TEF - Débito: Transação integrada, informando a modalidade Débito.
Id: 23
TEF - Voucher: Transação integrada, informando a modalidade Voucher.
Id: 24
TEF - Outros: Transação integrada, sem a modalidade transportada. A modalidade deverá ser informada no terminal de pagamento. Importante para modalidades diferentes de Crédtio, Débito e Voucher. Exemplo: QR Code, Private Label, etc.
Id: 25
TEF - Carteira Digital: Transação integrada, informando a modalidade Pix.
Id: 32
TEF - Crédito*: Transação integrada, porém, ela gera pagamento ao estabelecimento. Utilizada para operação de sub-adquirência, onde o ControlPay realiza a liquidação.
Id: 33
TEF - Débito*: Idem à forma acima, mas para débito.
Id: 51
Link de pagamento Crédito: Transação de e-commerce, integrada ao GATE2all, na modalidade crédito. Uma URL é gerada e disponibilizada no retorno da Intenção de venda. Caso o cartão esteja tokenizado e solicitado o parâmetro iniciarTransacaoAutomaticamente como true, a transação é processada automaticamente já retornando o resultado - aprovada ou negada.
Id: 52
Link de pagamento Débito: Transação integrada ao GATE2all, na modalidade débito. Sempre será retornada a URL para o usuário finalizar a transação nela, de forma segura. Não é possível tokenizar um cartão de débito no momento.
Id: 53
Boleto: Também integrado ao GATE2all, onde uma URL é retornada com o boleto a ser disponibilizado ao usuário.
Os processos
O ControlPay pode trabalhar de duas diferentes maneiras gerindo o fluxo transacional: de modo ativo ou de modo receptivo.
Ambos os modos funcionam através do mesmo conjunto de API. Isso significa que quando um sistema se integra ao ControlPay, encontra-se pronto para utilizar tanto o modo ativo como o receptivo.
A seleção de modo depende apenas do valor ("true" ou "false") do campo "aguardaTEFinicartransacao", no web service "Venda/Vender". Caso este campo receba o valor "true", o ControlPay estará operando no modo ativo; caso o valor enviado seja "false", o modo receptivo é acionado.
Modo ATIVO
Neste modo as transações enviadas ao ControlPay (via web service "Venda/Vender") são automaticamente "empurradas" ao TEF instalado no PDV correspondente. Caso o TEF não possa ser acionado, o objeto "intencaoVenda" expirará automaticamente. O tempo total de espera para que o TEF possa receber essa transação é de 20 segundos, logo, quando esta API é acionada desta forma, o tempo de resposa (caso o TEF não esteja ativo) pode chegar a este valor.
Abaixo podemos ver o fluxo de mensagens deste modelo:
PayGo Windows
No desenho acima, o ControlPay Cliente foi substituído pelo PayGo Windows, mas ainda funciona exatamente da mesma maneira.
Neste modo, o parâmetro iniciarTransacaoAutomaticamente deve ser enviado como True, que fará com que o ControlPay envie a transação até o terminal indicado e retornará o status da intenção de venda, que indicará o sucesso ou não do acionamento no terminal
Modo RECEPTIVO
No modo receptivo as transações cadastradas no ControlPay são armazenadas, mas nenhum sistema de pagamento é automaticamente acionado. Para que a transação seja iniciada, esta deve ser consultada pelo terminal de pagamentos.
O fluxo abaixo demonstra este processo:
PayGo Windows
No desenho acima, o ControlPay Cliente foi substituído pelo PayGo Windows, mas ainda funciona exatamente da mesma maneira.
Updated 4 months ago