DOCUMENTO DE INTEGRAÇÃO

VIA API GATEWAY PAYER

Junho/2023 – Versão 2.5
Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

1-Diagrama da Solução de Meios de Pagamento e Serviços Financeiros via API

Gateway Payer

2-Componentes da Solução Integrada via API Gateway Payer

COMPONENTE DESCRIÇÃO
Sistema Automação Comercial É o Sistema de Venda integrado que faz
pagamento integrado com a Payer
Aplicação Checkout Desktop Payer É o Sistema de Meio de Pagamento,
Serviço Financeiro, Gestão de Pagamento
e Fechamento de Caixa
Aplicação Checkout POS Payer É o Sistema de Meio de Pagamento,
Serviço Financeiro, Gestão de Pagamento
e Fechamento de Caixa
API Gateway Payer É a Plataforma Cloud Payer na AWS
CallBack de Requisição de Transação É o CallBack de retorno de requisição de
transação para o Sistema de Automação
Comercial
API´s da Industria de Meios de São as API´s dos parceiros da Payer
Pagamento e Serviços Financeiros
Serviços da Industria de Meios de São os Serviços dos parceiros da Payer
Pagamento e Serviços Financeiros
Pinpad Dispositivo Pinpad Modelo PPC-930 com
suporte a imagem para personalização e
pagamento com QR Code
 Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

Impressora Não Fiscal Impressora não fiscal conectada ao

Sistema de Automação Comercial para
impressão da Nota Fiscal e Comprovante
de Pagamento
Computador Máquina com Sistema Operação
Windows para o funcionamento do
Sistema de Automação Comercial e da
Aplicação Payer
SmartPOS Dispositivo SMARTPOS Modelo GPOS-700
da GERTEC Partnumber Payer

3-Configuração da Aplicação Checkout Payer no Modo via API Gateway Payer

O pré-requisito do processamento da requisição da ordem de pagamento ou serviço é

ativar a configuração do Modo de Integração API Gateway nos Parâmetros Desktop do
Checkout Payer para escutar a entrada de requisição de ordem de pagamento ou
serviço.

Modo Integração: O TEF Dial O API LOCALHOST O API GATEWAY O NENHUM

4-Autenticação do Sistema de Automação Comercial via API Gateway Payer

É requerido o username (e-mail do usuário) e password (senha do usuário), para

executar o endpoint de autenticação e obter o IdToken para usar na autenticação dos
endpoints dos micros serviços da API Gateway Payer.

POST de Autenticação na API Gateway

https://bk07exvx19.execute-api.us-east-1.amazonaws.com/dev-stage/oauth/login

O formato do payload do JSON é:

{
"clientId": "3veb9e18d50ceqes38o1i8mlph",
"username": "<<seu_usuario>>",
"password": "<<sua_senha>>"
}

CAMPO DESCRIÇÃO
clientId É uma chave fixa fornecida pela Payer
Username É o e-mail do Usuário ou do Sistema de Automação Comercial
password É a senha do Usuário ou do Sistema de Automação Comercial
 Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

5-Requisição de Ordem de Pagamento ou Serviço via API Gateway Payer

A requisição de ordem de pagamento ou serviço é enviada com os dados necessários ao

processamento do comando de pagamento ou serviço pelo Checkout Payer.

POST de Requisição de Ordem de Pagamento na API Gateway

https://yw4usl44fg.execute-api.us-east-1.amazonaws.com/dev-stage/cloud-
notification/create

Headers:
Authorization: {{idtoken-token-cognito}}

Exemplo de requisição de ordem de pagamento ou serviço.

{
"type": "INPUT",
"origin": "PDV",
"data": {
"correlationId": "4af40e08-e5a0-42fa-83b6-e939ec074bc2",
"flow": "SYNC",
"automationName": “NOME_SISTEMA”,
"receiver": {
"companyId": "000001",
"storeId": "0001",
"terminalId": "98"
},
"message": {
"command": "payment",
"value": 100
"paymentMethod": "CARD",
"paymentType": "CREDIT",
"paymentMethodSubType": " FINANCED_NO_FEES",
"installments": 3
}
}
}

CAMPO DESCRIÇÃO
type É o tipo da mensagem INPUT referente a entrada de
requisição de ordem de pagamento ou serviço.
origin É o campo texto para identificar a origem da requisição de
ordem de pagamento ou serviço.
Exemplos: Pedido, Comanda, Mesa, Bomba, etc
data É o objeto com as informações do Terminal Payer que
recebe a notificação da requisição de pagamento ou
serviço para o processamento. O Terminal Payer
Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

referenciado nesse objeto está configurado ativo no Modo

Integrado API Gateway.
data.correlationId É o NSU informado pelo Sistema de Automação Comercial
para vincular a entrada da requisição com o retorno via
WebHook
data.flow É o tipo de transação Síncrona (inicial em operação) ou
Assíncrona (a liberar em breve).
data.receiver.companyId É o ID da Empresa Payer que recebe os dados da requisição
de pagamento ou serviço para o processamento.
data.receiver.storeId É o ID da Loja Payer que recebe os dados da requisição de
pagamento ou serviço para processamento.
data.receiver.terminalId É ID do Terminal Payer que recebe os dados da requisição
de pagamento para o processamento.
data.automationName É o nome do Sistema de Automação que faz a requisição
da ordem de pagamento ou serviço. O Sistema de
Automação Comercial deve estar habilitada para enviar
requisição para o Checkout Payer.
data.message São os campos necessários ao Checkout Payer processar a
requisição da ordem de pagamento ou serviço. Esse
objeto é preenchido com os dados das opções do item:
7 – Modelo de Parâmetros de Transação da API Gateway
Payer.
Exemplo:
Comando de pagamento no valor de R$ 100,00 com cartão
de crédito parcelado lojista em 3 parcelas
"command": "payment",
"value": 100,
"paymentMethod": "CARD",
"paymentType": "CREDIT",
"paymentMethodSubType": " FINANCED_NO_FEES",
"installments": 3
data.callbackUrl É a Url usada para o retorno do processamento da
requisição da ordem de pagamento ou serviço após o fluxo
de pagamento ser concluído

6-WebHook de Retorno de Requisição de Ordem de Pagamento ou Serviço via API

Gateway Payer

A notificação do retorno da requisição de ordem de pagamento ou serviço ocorre ao

finalizar o processamento da transação no Checkout Payer com resultado aprovado ou
rejeitado pela API Gateway Payer usando a URL informada no campo callbackUrl pelo
Sistema de Automação Comercial.
 Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

Exemplo de retorno de requisição de ordem de pagamento ou serviço

{
"type": "INPUT",
"origin": "PDV",
"data": {
"correlationId": "4af40e08-e5a0-42fa-83b6-e939ec074bc2",
"flow": "SYNC",
"receiver": {
"companyId": "000001",
"storeId": "0001",
"terminalId": "98"
},
"message": {
"idPayer":"20230208165636",
"operationType":"PAYMENT",
"companyId":"000001",
"storeId":"0001",
"terminalId":"98",
"transactionDateTime":"2023-02-08T16:56:38.89",
"value":1,
"paymentType":"CASH",
"paymentMethod":"CASH",
"paymentMethodSubType":null,
"installments":null,
"statusTransaction":"APPROVED",
"rejectionInfo":null,
"acquirer":"CASH",
"flag":"CASH",
"thirdPartyId":"20230208165636",
"authorizerId":null,
"documentNumber":null,
"service":null,
"shopTextReceipt":" ",
"reducedShopPaymentReceipt":" ",
"reducedCustomerPaymentReceipt":" " }
}
}

7-Validação de Requisição de Ordem de Pagamento ou Serviço via API Gateway Payer

Através desse endpoint, é possível enviar a mesma requisição da ordem de pagamento,

a fim de validar se o conteúdo dos campos estão de acordo com o previsto.

https://yw4usl44fg.execute-api.us-east-1.amazonaws.com/dev-stage/cloud-
notification/api/v1/webhook/validate
Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

8-Modelos de Parâmetros de Transação via API Gateway Payer

Os parâmetros descritos a seguir são usado no preenchimento do comando desejado de

pagamento ou serviços que é enviado pela Sistema de Automação Comercial e recebido
e processado pelo Checkout Payer.

8-1-Comandos de Transação
command {
payment string example: Operação de Pagamento
admin string example: Operação Administrativa
cancellment string example: Operação de Cancelamento
service string example: Operação Meus Serviços}

8-2-Tipos de Operação
operationType {
PAYMENT string Example: Pagamento
CANCELLATION string example: Cancelamento
SERVICE string example: Serviço}

8-3-Status de Transação
statusTransaction {
APPROVED string example: Operação aprovada
REJECTED string example: Operação rejeitada
PENDING string example: Operação pendente
CANCELLED string example: Operação cancelada
ABORTED string example: Operação abortada
DONE string example: Operação finalizada
UNAUTHORIZED string example: Operação não autorizada}

8-4-Métodos de Pagamento
paymentMethod {
CARD string example: Cartão
CASH string example: Dinheiro
PIX string example: PIX
WALLET string example: Carteira Digital
TYPED string example: E-Commerce Digitado
LINK string example: E-Commerce Link
RECURRENT string example: E-Commerce Recorrência
PIX_LINK string example: E-Commerce Link PIX
CREDIARY string example: Crediário}

Observação:
-O método de pagamento é opção. Na ausência, é apresentado o menu com todos os
métodos para seleção do operador de caixa.
Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

-O método de pagamento CARD ao ser usado deve ser combinado com os tipos de
pagamento CREDIT, DEBIT e VOUCHER porque não há menu específico CARD para tornar
a jornada do operador mais rápida.

8-5-Tipos de Pagamento
paymentType {
CASH string example: Dinheiro
CREDIT string example: Crédito
DEBIT string example: Débito
VOUCHER string example: Voucher}

Observação:
-O tipo de pagamento é opção. Na ausência, é apresentado o menu de tipos de
pagamentos do método selecionado para seleção do operador de caixa.

8-6-Subtipos de Pagamento
paymentMethodSubType {
FULL_PAYMENT string example: À vista
PREDATED_DEBIT string example: Pré-Datado
FINANCED_DEBIT string example: Parcelado
FINANCED_NO_FEES string example: Parcelado Lojista
FINANCED_WITH_FEES string example: Parcelado Administradora
RECURRENT string example: Recorrente}

Observação:
-O sub-tipo de pagamento é opção. Na ausência, é apresentado o menu de sub-tipos de
pagamentos do método e tipo selecionados para seleção do operador de caixa.

8-6-1Parcelas do pagamento
installments: Número de parcelas do pagamento, deve ser enviado como um valor
inteiro. example: 2

Observação:
-As parcelas do pagamento é opção. Na ausência, é apresentado o menu de parcelas de
pagamentos do método selecionado para seleção do operador de caixa.

8-7-Tipo de Serviços - Recarga de Celular

Service {
MOBILE_CREDIT string example: Serviço de Recarga de Celular}

9-Roteiro de Homologação da Integração com API Gateway Payer

 Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

A homologação da integração com a API Gateway Payer requer a execução de testes

básicos com o seguinte escopo:

9-1-Comandos de Requisições de Pagamentos e Cancelamentos

São executados testes de pagamento com Cartão e PIX aprovadas, cancelamento de

pagamento com Cartão e PIX aprovadas, e por fim, tentativas de pagamento com Cartão
e PIX abortadas.

Os testes com os resultados de status aprovados e abortados tem o objetivo de garantir

o Sistema de Automação Comercial validar o retorno dos status para a finalização da
venda com emissão da Nota Fiscal exclusivamente quando a requisição for aprovada.

command {
payment string example: Operação de Pagamento
cancellment string example: Operação de Cancelamento}

statusTransaction {
APPROVED string example: Operação aprovada
CANCELLED string example: Operação cancelada
ABORTED string example: Operação abortada}

paymentMethod {
CARD string example: Cartão
PIX string example: PIX}

paymentType {
CREDIT string example: Crédito
DEBIT string example: Débito}

9-2-Casos de Testes de Requisições de Pagamentos e Cancelamentos

Seguem os testes de pagamento aprovado, cancelamento de pagamento aprovado, e os

testes de tentativas de pagamentos abortados.

9-2-1-Pagamento com Cartão Crédito, Cartão Débito e PIX Aprovado

{
"command": "payment",
"value": 10,
"paymentMethod": "CARD",
 Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

"paymentType": "CREDIT"
}

{
"command": "payment",
"value": 20,
"paymentMethod": "CARD",
"paymentType": "DEBIT"
}

{
"command": "payment",
"value": 1,
"paymentMethod": "PIX"
}

9-2-2-Cancelamento de Pagamento com Cartão Crédito, Cartão Débito e PIX Aprovado

{
"command": "cancellment",
"idPayer": "string"
}
Observação: Preencher “string” com o ID Payer do pagamento cartão crédito aprovado.

{
"command": "cancellment",
"idPayer": "string"
}
Observação: Preencher “string” com o ID Payer do pagamento cartão débito aprovado.

{
"command": "cancellment",
"idPayer": "string"
}
Observação: Preencher “string” com o ID Payer do pagamento PIX aprovado.

9-2-3-Tentativas de Pagamento com Cartão Crédito, Cartão Débito e PIX Abortado

{
"command": "payment",
"value": 10,
"paymentMethod": "CARD",
"paymentType": "CREDIT"
}

{
 Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

"command": "payment",
"value": 10,
"paymentMethod": "CARD",
"paymentType": "DEBIT"
}

{
"command": "payment",
"value": 10,
"paymentMethod": "PIX"
}

Observação: O teste de tentativa de pagamento abortado requer ao estar na tela do

Checkout o acionamento do comando ESC para interromper e abortar o fluxo de
pagamento, onde o Checkout comanda o response com o status ABORTED.

9-3-Evidências dos Testes de Requisições de Pagamentos e Cancelamentos

Após finalizar a execução dos testes com sucesso, deve ser compartilhado com o Time
de Suporte Payer o arquivo com os registros das evidências dos testes.

C: > Payer > Logs > CheckoutPC-AAAA-MM-DD

Esse é o arquivo geral de LOG do Checkout Desktop onde todos os eventos executados
no Checkout Desktop são registrados na ordem cronológica.

E por fim, após a validação das evidências, o Time de Suporte Payer responde a
aprovação para seguir com a operacionalização em produção.

10-Checklist da integração entre o Sistema de Automação Comercial Parceiro com o

Sistema Checkout Desktop ou POS Payer

1-Baixar o Payer App nas lojas Apple ou Google para fazer o Onboarding da Empresa
Parceiro para criar o laboratório de desenvolvimento e testes da integração entre os
sistemas do Parceiro e da Payer.

Responsável: Parceiro
Integração Sistema de Automação Comercial e Checkout Payer via API Gateway Payer

2-Fazer o Onboarding da Empresa Parceiro para informar os dados de contato da pessoa

da Empresa Parceiro e os dados da Empresa Parceiro para criação de Id Conta Payer com
Id Empresa, Id Loja e Id Terminal.

Responsável: Parceiro

3-Configurar os parâmetros da Empresa, Loja e Terminal do Parceiro com as credenciais

básicas de pagamentos compartilhadas pela Payer para viabilizar o desenvolvimento e
testes de variados pagamentos da integração.

Responsável: Payer – Suporte Técnico

4-Instalar e implantar o Checkout Desktop ou POS Payer em uma ou mais máquinas

windows ou android do Parceiro para suportar o desenvolvimento e testes de
pagamento da integração.

Responsável: Payer – Suporte Técnico

5-Desenvolver a integração de pagamentos entre o Sistema de Automação Comercial

Parceiro com o Sistema Checkout Desktop ou POS Payer.

Responsável: Parceiro

6-Prestar o suporte técnico ao desenvolvimento e testes da integração entre o Sistema

de Automação Comercial Parceiro com o Sistema Checkout Desktop ou POS Payer.

Responsável: Payer – Suporte Técnico

7-Homologar a integração do Sistema Automação Comercial Parceiro com o Sistema

Checkout Desktop ou POS Payer.

Responsável: Parceiro e Payer