Getnet DocsGetnet Docs

Processar Pagamentos em Etapa Única

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Este guia detalha como implementar o fluxo de pagamento padrão (Venda). Neste fluxo, você envia uma única requisição para a API, e o terminal lida com a interação com o portador do cartão.

Como as interações com o terminal físico levam tempo, este processo é assíncrono. Você iniciará o pagamento por meio de uma chamada direta à API e receberá o resultado final via uma notificação de webhook.

O Ciclo de Vida da Transação

  1. Requisição: Seu servidor envia uma requisição POST para o endpoint /pago.
  2. Reconhecimento: A API retorna um 200 OK síncrono indicando que o terminal recebeu o comando.
  3. Interação: O terminal solicita que o cliente insira o cartão e digite o PIN.
  4. Notificação: Assim que a transação for concluída (Aprovada, Negada ou Cancelada), a API envia um payload JSON para a sua urlNotificacion.

Passo 1: Enviar a Requisição de Pagamento

Para iniciar uma venda, envie uma requisição POST para o endpoint /pago.

  • Endpoint de Teste: https://tpvpc-i.redsys.es:27443/TPV_PC/services/rest/tpvpcwss/v1/pago
  • Endpoint de Produção: https://tpvpc.redsys.es/TPV_PC/services/rest/tpvpcwss/v1/pago

Payload da Requisição

O payload deve incluir o valor, sua referência interna de fatura e a URL de notificação onde você deseja receber o resultado final.

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 111217",
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/payment-results",
      "correoNotificacion": "[email protected]"
    },
    "datosOperacion": {
      "importe": "25.50",
      "factura": "ORD-2025-001"
    }
  },
  "signature": "YOUR_CALCULATED_SIGNATURE"
}

Certifique-se de que o importe esteja formatado como XXXXXXXXX.XX (ex.: 25.50 ou 0.01). Não utilize vírgulas.

Passo 2: Tratar a Resposta Síncrona

Imediatamente após enviar a requisição, a API retornará uma resposta.

Resposta Esperada:

{
  "info": {
    "resultado": {
      "codigo": "0"
    }
  },
  "signature": "SERVER_SIGNATURE"
}
  • codigo: "0": Sucesso. O terminal agora está processando o pagamento.
  • Qualquer outro código: A requisição falhou (ex.: erro de validação, terminal offline). Consulte a referência do Catálogo de Códigos de Erro e Negação.

NÃO libere os produtos/serviços ainda. Um código 0 aqui significa apenas “Requisição Aceita”. Isso não significa que o pagamento foi pago ou autorizado.

Passo 3: Receber a Notificação Assíncrona

Quando o cliente finaliza (ou cancela) a transação, a API Cloud envia uma requisição POST para a sua urlNotificacion.

Exemplo de Notificação de Sucesso

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 111500",
    "datosRespuesta": {
      "tipoPago": "PAGO",
      "importe": "25.50",
      "moneda": "978",
      "factura": "ORD-2025-001",
      "resultado": "Autorizada",
      "codigoRespuesta": "998877",
      "estado": "F",
      "tarjetaClienteRecibo": "************1234",
      "marcaTarjeta": "1"
    }
  },
  "signature": "SERVER_SIGNATURE"
}

Campos Principais para Validação

Você deve inspecionar campos específicos em datosRespuesta para confirmar o status do pagamento:

CampoValor para SucessoDescrição
resultadoAutorizadaDeclara explicitamente que a transação foi aprovada.
estadoFIndica que a operação está “Finalizada” (Finalized).
codigoRespuesta(Código de Autorização)O código de autorização do banco. Se a transação foi negada, conterá um código de negação (ex.: 101, 117).
importe(Seu Valor)Verifique se o valor autorizado corresponde ao valor que você solicitou.

Tratamento de Negações e Erros

Se o pagamento falhar, a notificação refletirá a falha:

  • resultado: Denegada
  • codigoRespuesta: Um código de negação (ex.: 117 para PIN Incorreto).
  • estado: Pode ser G (Negada), A (Cancelada) ou T (Falha Técnica).

Próximos Passos