DOCUMENTO DE INTEGRAÇÃO

VIA API LOCALHOST PAYER

Setembro/2023 – Versão 2.8
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

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

Localhost Payer

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

COMPONENTE
Sistema Automação Comercial
Aplicação Checkout Desktop Payer
Aplicação Checkout POS Payer
API Localhost Payer
API Gateway Payer
API´s da Industria de Meios
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
Impressora Não Fiscal
DESCRIÇÃO
É o Sistema de Venda integrado que faz
pagamento integrado com a Payer
É o Sistema de Meio de Pagamento,
Serviço Financeiro, Gestão de Pagamento
e Fechamento de Caixa
É o Sistema de Meio de Pagamento,
Serviço Financeiro, Gestão de Pagamento
e Fechamento de Caixa
É a API Localhost embarcado no Checkout
Payer
É a Plataforma Cloud Payer na AWS
de São as API´s dos parceiros da Payer
Dispositivo Pinpad Modelo PPC-930 com
suporte a imagem para personalização e
pagamento com QR Code
Impressora não fiscal conectada ao
Sistema de Automação Comercial para
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

impressão da Nota Fiscal e Comprovante

de Pagamento
Computador Desktop Máquina com Sistema Operação
Windows 10 ou superior para o
funcionamento do Sistema de
Automação Comercial e da Aplicação
Checkout Payer
SmartPOS Dispositivo SMARTPOS Modelo GPOS-700
da GERTEC Part Number Payer

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

O pré-requisito do processamento da requisição da ordem de pagamento é ativar a

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

4-Requisição via API Localhost Payer

4.1-Ordem de Pagamento, Estorno ou Serviço

4.2-Retorno de Ordem de Pagamento, Estorno ou Serviço
4.3-Consulta de Transação
4.4-Login de Usuário
4.5-Logoff de Usuário
4.6-Status de Login de Usuário

4.1-Requisição de Ordem de Pagamento, Cancelamento ou Serviço via API Localhost

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.

Base URL: POST http://localhost:6060/Client/request

Modelo Transação de Pagamento

{
"command": "payment",
"value": 1,
"idPayer": "string",
"paymentMethod": "string",
"paymentType": "string",
"paymentMethodSubType": "string",
"installments": 0,
"documentNumber": "string",
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

"service": "string"
}

Modelo de Transação de Cancelamento de Pagamento

{
"command": "cancellment",
"idPayer": "string"
}

Modelo de Transação de Serviço Recarga de Celular

{
"command": "service"
}

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

Localhost Payer

A requisição retorno da requisição de ordem de pagamento ou serviço ocorre de forma

intermitente com intervalo de 300 ms para retorno da transação detalhada com
respectivo status após finalizado o processamento da transação no Checkout Payer.

Base URL: GET http://localhost:6060/Client/response

4.3-Requisição de Consulta de Transação via API Localhost Payer

A requisição de consulta de transação é sob demanda para obter os dados detalhados

com o respectivo status para recuperação dos dados da transação com os
comprovantes.

Base URL: GET http://localhost:6060/Client/transaction/

{
idPayer,
}

4.4-Requisição de Login do Usuário via API Localhost Payer

A requisição de login usuário tem o objetivo de automatizar a entrada do usuário no

Checkout diretamente pelo Sistema de Automação Comercial.

Base URL: POST http://localhost:6060/Client/login/

{
“email”: “exemplo@exemplo.com”,
“password”: “string”
}
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

4.5-Requisição de Logoff do Usuário via API Localhost Payer

A requisição de logoff usuário tem o objetivo de automatizar a saída do usuário do

Checkout diretamente pelo Sistema de Automação Comercial.

Base URL: POST http://localhost:6060/Client/logoff/

4.6-Requisição de Consulta de Login via API Localhost Payer

A requisição de consulta de login é sob demanda para obter os dados do e-mail e status
do login.

Base URL: GET http://localhost:6060/Client/login/

O objeto de resposta contém o e-mail e o status do login

{
"status": "string",
"email": "string"
}

4.7-Payload de Retorno de Transação

{
"request": {
"command": "payment",
"value": 1
},
"idPayer": "20230628112156",
"operationType": "PAYMENT",
"companyId": "000001",
"storeId": "0002",
"terminalId": "01",
"transactionDateTime": "2023-06-28T11:22:40.031Z",
"value": 1,
"paymentType": "CREDIT",
"paymentMethod": "CARD",
"paymentMethodSubType": "FULL_PAYMENT",
"installments": "1",
"statusTransaction": "APPROVED",
"rejectionInfo": null,
"acquirer": "STONE",
"flag": "MASTERCARD",
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

"thirdPartyId": "27933241803824",
"authorizerId": "060894",
"authorizerUsn": "27933241803824",

"documentNumber": null,
"service": null,
"shopTextReceipt": "",
"customerTextReceipt": "",
"reducedShopPaymentReceipt": "",
"reducedCustomerPaymentReceipt": ""
}

Observação: Os comprovantes completo e reduzido em formato texto da transação

foram suprimidos do exemplo.

Exemplo:
{"request":{"command":"payment","value":1},"statusTransaction":"PENDING"}

Detalhamento do Payload de Retorno de Requisição de Ordem de Pagamento ou Serviço

via API Localhost Payer

CÓDIGO CAMPO CONTEÚDO CAMPO NOME CAMPO

{ {
"request": { "request": {
"command": "payment"
"value": 1
}, },

"idPayer": "20230628112156", NSU Payer

"operationType": "PAYMENT", Tipo Operação
"companyId": "000001", ID Empresa Payer
"storeId": "0002", ID Loja Payet
"terminalId": "01", ID Terminal Payer
"transactionDateTime": "2023-06- Dt, hr, min e seg da transação
28T11:22:40.031Z",
"value": 1, Valor transação
"paymentType": "CREDIT", Tipo Pagamento
"paymentMethod": "CARD", Método Pagamento
"paymentMethodSubType": "FULL_PAYMENT", Sub-tipo Pagamento
"installments": "1", Qtd. Parcelas Pagamento
"statusTransaction": "APPROVED", Status Transação
"rejectionInfo": null, Código e Motivo Rejeição
"acquirer": "STONE", Nome Adquirente
"flag": "MASTERCARD", Nome Bandeira Cartão

"thirdPartyId": "27933241803824", NSU Serviço Cartão

"authorizerId": "060894", Código Autorização ADQ
"authorizerUsn": "27933241803824", NSU Adquirente

"documentNumber": null, ID de Referência Pagamento

"service": null, Serviço Vinculado Pagamento
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

"shopTextReceipt": " ", Comprovante Transação Loja

"customerTextReceipt": " ", Comprovante Transação Cliente
"reducedShopPaymentReceipt": " ", Comprovante Reduzido Loja
"reducedCustomerPaymentReceipt": "" Comprovante Reduzido Cliente
} }

5-Modelos de Parâmetros de Transação via API Localhost Payer

Os parâmetros descritos a seguir são usado na composição do comando desejado e

pagamento ou serviços que é recebido e processado pelo Checkout Payer.

5-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}

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

5-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}

5-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}
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

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

5-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}

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

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

6-Roteiro de Homologação da Integração com 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:

6-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
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

PIX string example: PIX}

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

6-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.

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

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

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

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

6-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.
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

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

6-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"
}

{
"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.

6-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 da Payer os seguintes arquivos 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.

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

Esse é o arquivo específico de LOG da integração API Localhost com o Checkout Desktop
onde todos os eventos de request e response são registrados na ordem cronológica.
Integração Sistema de Automação Comercial e Checkout Payer via API Localhost Payer

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.

7-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

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 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