Será preciso implementar e expor os endpoints “Authorization” e “ Adjustments” em seu backend para que possamos nos comunicar.

Fluxo do processador de pagamentos:#

Vamos consumir seus endpoints nestes momentos:#

Durante o fluxo on-line

Toda vez que um usuário usa seu cartão em qualquer loja ou e-commerce.

Durante a conciliação#

Quando a rede (Mastercard, Visa etc.) solicita a reconciliação de todos os pagamentos apresentados pelos estabelecimentos.

Considerações#

Se houver diferença na reconciliação, solicitaremos uma correção de sua API. Precisaremos que seus endpoints respondam o mais rápido possível para garantir uma boa experiência do usuário. Se a resposta demorar, recusaremos a transação.

Idempotência#

Como uma solicitação HTTP pode expirar, precisamos garantir que, ao tentar novamente, seja processada apenas uma vez. Para isso, em cada solicitação, enviaremos um header x-idempotency-key com uma ID única que deve ser processada com um cache na memória (por exemplo: redis).

No início de cada transação, você terá de verificar se a chave de idempotência que lhe enviamos já está no cache na memória e, dependendo se estiver ou não, você terá de fazer o seguinte:

O header de idempotência não existe no cache.

Será preciso armazenar em cache na memória a relação chave de idempotência → solicitação com um estado em trânsito com um TTL de 3 minutos.

Ao aprovar ou rejeitar a transação, você deverá armazenar em cache o resultado e atualizar o estado da chave de idempotência para concluído.

O header de idempotência existe no cache

Em caso de solicitação duplicada, será necessário verificar o status da transação no cache.

• Se estiver com status concluído, você deve responder com um código HTTP 200 com o corpo esperado para o endpoint e completá-lo com o resultado do cache.
• Se o status for em trânsito, você deverá responder com um código HTTP 425 (Too Early: RFC 8470) com o corpo esperado para o endpoint. Voltaremos a verificar a resposta a esta solicitação alguns milissegundos depois.

Requests em andamento#

Se você receber uma segunda solicitação com o mesmo ID de idempotencia e a primeira ainda estiver em andamento, você deve responder com um status HTTP 425 e um corpo vazio.

Segurança#

A comunicação entre nossos backends deve ser estritamente segura, pois os endpoints permitirão que os recursos sejam carregados e deduzidos.

Para isso, exigimos que três medidas sejam implementadas:

• Expor endpoint HTTPS
• Whitelist dos IPs da Pomelo
• Assinatura hmac-sha256 da solicitação e a resposta

Expor endpoint HTTPS#

Toda comunicação conosco deve ser via HTTPS, independentemente de quem emite o certificado.

Estes são alguns dos fornecedores mais reconhecidos

• https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-client-side-ssl-authentication.html
• https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html
• https://cloud.google.com/load-balancing/docs/ssl-certificates/google-managed-certs

Whitelist dos IPs da Pomelo#

Sempre nos comunicaremos com seu backend a partir de IPs específicos. Recomendamos que você só aceite solicitações dos IPs abaixo e recuse quaisquer outras solicitações:

IPs da Pomelo:

• Ambiente de testing/staging:

34.226.254.178            
44.198.3.59
34.223.185.46
100.20.205.117

• Ambiente de produção:

34.206.159.176            
52.0.20.124
35.84.78.117
52.43.46.111

Assinatura hmac-sha256 da solicitação e a resposta#

Para garantir que os únicos participantes da comunicação sejam nossos backends (Pomelo e o Cliente), no momento da integração, forneceremos uma api-key e uma api-secret para assinar digitalmente o conteúdo da comunicação.

O processo será mais ou menos assim:

1. Na integração, trocaremos as chaves api-key e api-secret.

2.

No momento de uma autorização de pagamento, assinamos com hmac-sha256 cada solicitação de autorização com api-secret.

4. Você valida a assinatura hmac-sha256 com sua api-secret que corresponde à api-key da solicitação.

5. Você autoriza a solicitação, debita os recursos do usuário e assina a resposta com hmac-sha256, usando a api-secret.

6. Verificamos a assinatura hmac-sha256 e finalizamos o processamento de pagamento.

Processo de troca de chaves#

Durante o processo de integração, criaremos uma api-key e uma api-secret específicas para você.

Também é possível usar gpg ou algum plugin de e-mail (como https://flowcrypt.com/).

Vejamos um exemplo usando openssl na linha de comando.

1. Criamos a api-key e a api-secret:

$ echo -e 'api-key=$(openssl rand -base64 32)\napi-secret=$(openssl rand -base64 32)' > api-credentials.txt

$ cat api-credentials.txt
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=

2. Você cria sua chave público-privada:

$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem

3. Você nos envia sua chave pública public.pem por e-mail ou slack.

4. Criptografamos o arquivo de credenciais com a chave pública que você nos fornecer:

$ openssl rsautl -encrypt -in api-credentials.txt -out api-credentials.txt.enc -inkey public.pem -pubin

5. Enviamos o arquivo api-credentials.txt.enc por e-mail ou slack

6. Você descriptografa o arquivo api-credentials.txt.enc com sua chave privada private.pem:

$ openssl rsautl -decrypt -in api-credentials.txt.enc -inkey private.pem
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=

7. Você mantém a api-secret em um local seguro e acessível somente pelo aplicativo de autorização de pagamentos associado à api-key.

Processo de assinatura da solicitação#

Juntamente com a solicitação de autorização ou ajuste, enviaremos headers HTTP com a assinatura, o carimbo de data e hora da assinatura e a api -key para que você possa verificar se a assinatura está correta.

Os headers HTTP que enviamos são:

• x-api-key : este header permitirá identificar qual api-secret deve-se usar, caso vários pares de api-key e api-secret tenham sido configurados.

• x-signature : Este header contém a assinatura digital (body + timestamp + endpoint) que deve ser verificada para garantir a integridade da solicitação. Se a assinatura não corresponder, você deve rejeitar a solicitação.

• x-timestamp : este header contém a hora em que a solicitação foi assinada no formato unix-epoch para que você possa verificar se a assinatura não expirou.

• x-endpoint : o endpoint para o qual a solicitação é realizada. Use este header para gerar novamente a assinatura a ser validada, e compare-o com o endpoint do seu serviço para verificar se eles correspondem.

Importante: além de verificar a assinatura que lhe enviamos, ao gerar a resposta você deve assinar o corpo junto com o carimbo de data/hora e o endpoint de resposta com seu api-secret depois de impactar a operação. Observe que validaremos a assinatura e recusaremos a transação se a assinatura não corresponder ou tiver expirado.

Como testar sua implementação e o código de exemplo#

Você pode testar a implementação do seu back-end com algumas operações típicas que enviaremos com uma coleção Postman incluída em nosso [repositório de exemplos públicos] (https://github.com/pomelo-la/cards-transactions-examples). Você poderá importar a coleção para uma instância do Postman e dessa forma simular pedidos reais para o seu back-end, incluindo o algoritmo de geração e verificação de assinatura.

No repositório você também encontrará exemplos de implementação do algoritmo de geração e validação de assinaturas em vários idiomas.

Liquidação#

Esse é um processo opcional, mas recomendamos executá-lo diariamente.

No servidor SFTP que disponibilizaremos, você encontrará os seguintes arquivos:

• Arquivo de transações
• Arquivo de apresentação

Arquivo de transações#

Contém as informações de cada transação que geramos no dia anterior.

El nombre del archivo tiene el siguiente formato: transaction_yyyy-mm-dd_<nombre cliente>_<pais>.csv

Estrutura do arquivo de transações#

*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.

Tabela de STATUS_DETAIL#

Conciliação do arquivo de transações#

Caso você esteja tentando ajustar um crédito a um usuário final que não tenha fundo suficientes na conta, você deve continuar tentando obter os fundos desse usuário.

Torna-se uma dívida entre o cliente e o usuário final.

Arquivo de apresentação#

Contém as informações de cada transação apresentada pelos estabelecimentos no dia anterior.

El nombre del archivo tiene el siguiente formato: presentment_yyyy-mm-dd_<nombre cliente>_<pais>.csv

Estrutura do arquivo de apresentação#

*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.

Conciliação do arquivo de apresentação#

Nossa equipe financeira enviará uma notificação diariamente com a dívida a ser paga. Essa notificação terá todas as apresentações que recebemos no arquivo de apresentação.

Obtenção dos arquivos de Transações e Apresentações#

Forneceremos um servidor SFTP de onde será possível baixar os arquivos de Transações e Apresentações.

Dispomos de dois ambientes para osw servidores SFTP, um de produção e outro de desenvolvimento.

Para se conectar aos servidores SFTP, precisaremos que você nos envie uma chave pública para gerar um usuário.

Aqui estão os dados para se conectar a cada ambiente:

Produção:#

Host: sftp.pomelo.la
Porta: 22
Usuário: <tu_usuario> # aquele que geramos a partir de suas chaves públicas.

Desenvolvimento:#

Host: sftp-dev.pomelo.la
{Puerto}: 22
Usuário: <tu_usuario> # aquele que geramos a partir de suas chaves públicas.

Para gerar a chave pública, você terá de usar o comando de acordo com seu sistema operacional:

Linux / MacOs:#

1. Crie um par de chaves RSA, alterando a variável $Cliente pelo nome próprio

ssh-keygen -t rsa -b 2048 -C $Cliente

O comando criará um par de chaves RSA de 2048 bits por padrão. ​Você também pode criar uma chave maior, de 4096 bits, inserindo -b 4096.

O comando produz a seguinte saída:

Generating public/prive rsa key pair.
Digite um arquivo onde salvar a chave (/your_home/.ssh/id_rsa):

Pressione Enter para salvar o par de chaves em .ssh /, ou especifique outro local.

2. Crie uma senha para sua chave SSH.

Pressione Enter para deixá-la em branco e use apenas a chave para estabelecer conexões SSH. Insira uma senha para uma camada extra de segurança.

3. Obtenha a chave pública gerada, lendo o conteúdo do arquivo público

cat ~/.ssh/id_rsa.pub

A chave gerada começará com ssh-rsa.

Agora, você pode copiar e colar sua chave SSH pública em seu console Shell ou em qualquer servidor para estabelecer uma conexão segura.

Windows#

Gere chaves SSH, usando PuTTY. Instale o PuTTY na página do desenvolvedor: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

1. Gere chaves SSH, usando PuTTY

Instale o PuTTY na página do desenvolvedor: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

2. Execute o gerador de chaves PuTTY SSH

• Pressione a tecla Windows.
• Escreva puttygen.
• Clique com o botão direito do mouse em PuTTYgen.
• Clique em Executar como administrador.
• ​Clique em Sim se o sistema gerar a seguinte consulta: Deseja permitir que este aplicativo faça alterações em seu dispositivo?

3. Use PuTTY para criar um par de chaves SSH

Embora a ferramenta de geração de chaves PuTTY ofereça vários outros algoritmos, mostraremos como gerar chaves RSA, uma das mais usadas:

• Na janela do gerador de chaves PuTTY, clique em Gerar.
• Mova o cursor na caixa cinza para preencher a barra verde.
• Gerando um par de chaves SSH no Putty.
• Salve a chave pública, clicando no botão Salvar chave pública. Você terá, então, de escolher um local para salvar a chave e dar um nome à chave.
• Salve a chave privada:
  • Clique no menu Conversões, na parte superior da tela.
  • Clique em Exportar chave OpenSSH.
  • O sistema perguntará se você quer salvar uma chave sem uma senha. Clique em Sim.
  • Escolha um local para salvar a chave (geralmente, a mesma pasta da chave pública).
  • Nomeie a chave (por exemplo, putty_key).