Pagamento com antifraude e Postman

🔐

Mantenha as credenciais no Postman

Use somente dados de homologação. Configure a autenticação no Postman e cole nesta página apenas a chave pública. O Postman faz as chamadas que, em uma integração real, ficam no seu backend.

Quem faz o quê?

O navegador prepara os dados. O Postman envia as requisições. A API devolve o resultado do pagamento.

Postman / backendObtém a chave públicaVocê autentica na API e consulta /v1/cards/public-key.

NavegadorPrepara o checkoutA biblioteca inicia a sessão antifraude e criptografa o número do cartão.

Postman / backendCria o pagamentoVocê copia o JSON da página e envia para POST /v1/payments.

ResultadoInterpreta a respostaA página lê o status HTTP, returnCode e paymentId que você informar.

Preparar a biblioteca

Obtenha a chave pública pelo Postman. Depois, use essa chave para preparar a biblioteca nesta página.

Navegador

Comece pela autenticação e pela chave pública.

A chave pública permite criptografar o número do cartão no navegador. Para obtê-la:

Importe no Postman a coleção incluída na pasta postman.
Execute POST /api/auth/token com as credenciais de homologação.
Configure a autorização das próximas requisições no Postman. Não compartilhe o valor da credencial.
Execute GET /v1/cards/public-key.
Copie o campo key da resposta para Chave pública RSA, abaixo.

Base de homologação: https://api-hmg.sopague.com.br/gateway.

Chave pública RSA Cole a chave no formato recebido pela API. Você pode usar o conteúdo Base64 ou a chave PEM completa, com BEGIN PUBLIC KEY e END PUBLIC KEY.

Identificador único da sessão antifraude A página já gerou este UUID para identificar a sessão antifraude da compra. Use um UUID diferente em cada nova tentativa. O botão de reiniciar gera outro.

Ver o código desta etapa

// Postman: autenticar e obter GET /v1/cards/public-key.
// Navegador: configurar SOMENTE a chave pública.
Sopague.setEncryptPublicKey(toPem(key));
const antiFraudId = crypto.randomUUID();
Sopague.initAntiFraud(antiFraudId);
// Como na POC original, enviar o UUID sem o prefixo interno da biblioteca.
const codeAntiFraud = antiFraudId;

Proteger o cartão e preparar a compra

Preencha os dados da compra. Ao clicar em Proteger e preparar dados, a biblioteca criptografa o número do cartão e monta o JSON.

Navegador

Envie o pagamento em até cinco minutos após gerar o JSON.

O cartão criptografado tem validade de cinco minutos. Prepare os dados quando estiver pronto para enviar pelo Postman. Não armazene o conteúdo criptografado. Se o prazo terminar, gere um novo JSON antes de enviar.

Número do cartão

Nome impresso

Código de segurança

Mês de validade

Ano de validade

Valor total em centavos

Número de parcelas Escolha de 1 a 12 parcelas. Com 1 parcela, o JSON usa avista. De 2 a 12, usa lojista. O valor acima é o total da compra, sem dividir pelas parcelas.

Dados do cliente

Preencha com os dados de homologação usados no seu teste. Os campos começam vazios. Telefone e celular são opcionais nesta POC.

Nome

Sobrenome

Documento

E-mail

Telefone

Celular

Endereço

Cidade

Estado

CEP

País Informe o código do país com duas letras. Para Brasil, use BR.

Dados de Rede

IP do usuário Nesta POC, informe o IP usado no teste. Em produção, o backend deve identificar o IP da requisição, sem depender apenas do valor informado pelo navegador.

Ver o código desta etapa

const encryptedCard = await Sopague.encryptCard(cardNumber);
// cardInfo.encryptedCard recebe o resultado da criptografia.
// sellerInfo.codeAntiFraud recebe o mesmo UUID da preparação.
// payment: credit; installments recebe o número de parcelas.
// productType: avista para 1 parcela; lojista para mais de 1.
// amount continua sendo o valor total da compra em centavos.
// Não há code3DS, urlSite3DS ou deviceInfo neste fluxo.

Criar o pagamento

O JSON abaixo é o corpo da requisição, também chamado de payload. Copie esse conteúdo para enviar pelo Postman.

Postman / backend

Agora, envie a requisição no Postman.

Clique em Copiar payload, abaixo.
No Postman, abra a requisição 03 — Criar pagamento.
Confira o endereço: POST https://api-hmg.sopague.com.br/gateway/v1/payments.
Confira a autorização configurada no Postman.
Em Body → raw → JSON, substitua todo o corpo pelo conteúdo copiado.
Envie a requisição antes de completar cinco minutos da geração do JSON.

A prévia abaixo oculta o cartão criptografado e o código de segurança (CVV). O botão copia o JSON completo, com esses campos. O número do cartão sem criptografia não faz parte do corpo.

Não salve a requisição com os dados preenchidos. Esta página prepara o JSON, mas o envio do pagamento acontece no Postman.

Conclua as etapas 1 e 2 para visualizar o corpo da requisição.

Ver o exemplo de envio pelo Postman

// O Postman representa o backend nesta demonstração.
// POST {{gatewayUrl}}/v1/payments
// Content-Type: application/json
// Configure a autorização somente no Postman.
// Cole o corpo gerado em Body > raw > JSON.
// Em produção, seu backend deve controlar valor, pedido e IP.

Interpretar a resposta

Depois de enviar o pagamento, copie do Postman o status HTTP e o corpo da resposta. A página usa esses dados para explicar o resultado.

Sopague / emissor

Confira o resultado do pagamento junto com o status HTTP.

Um HTTP 200, sozinho, não confirma a aprovação. Esta POC também verifica se returnCode é 0 e se paymentId está preenchido.

Se a requisição terminar por timeout ou retornar erro 5xx, consulte a transação antes de tentar cobrar novamente.

Status HTTP retornado

Resposta do Postman Cole somente o JSON da resposta do pagamento. Não cole a resposta de autenticação nem credenciais.

✅

Pagamento aprovado

A resposta que você colou contém returnCode 0 e paymentId preenchido. A página interpreta esse conteúdo, mas não consulta a transação. Para confirmar o estado atual, consulte a API.

Os dados preenchidos e a resposta continuam nesta página após a interpretação, mesmo quando o prazo de envio termina. Para começar outro teste e limpar os campos, use o botão abaixo. Recarregar a página também descarta os dados.