Formulário de Pagamento

Nesta seção, você aprenderá como enviar dados de transação para o gateway de pagamento da PayU. Este documento fornece as informações necessárias para criar um formulário HTML com os detalhes exigidos da transação e enviá-lo para o nosso sistema usando o método HTTP POST.

Observações

  • Verifique se você tem merchantId, accountId e apiKey corretos.
  • Use um código de referência de pagamento único para cada transação.
  • Evite incluir espaços nos valores dos parâmetros.
  • Limite os valores decimais a duas casas.
  • Exclua caracteres especiais do parâmetro referenceCode.

Parâmetros

Você pode incluir os seguintes parâmetros no formulário de pagamento.

Parâmetros no formulário de pagamento
Campo Tipo Tamanho Descrição Obrigatório
merchantId Número 12 Número de identificação da sua loja no sistema PayU. Você encontrará este número no e-mail de criação de conta. Sim
referenceCode Alfanumérico 255 Referência da venda ou ordem. Deve ser exclusiva para cada transação enviada ao sistema. Normalmente, é uma forma de identificar as solicitações enviadas para a plataforma de pagamento. Sim
accountId Número 6 ID da conta do usuário para cada país associado à loja. Esta variável é usada para exibir os métodos de pagamento disponíveis para este país. Sim
description Alfanumérico 255 Descrição da venda. Sim
currency Alfanumérico 3 A respectiva moeda na qual o pagamento é feito. O processo de reconciliação é realizado em pesos na taxa representativa do dia.
Veja as moedas aceitas.		 Sim
amount Número 10 Valor total da transação. Ele pode conter dois dígitos decimais. Exemplo 10000.00 ou 10000. Sim
tax Número 10.2 Valor do IVA da transação.
Na Colômbia, se nenhum IVA for enviado, o sistema aplica 19% automaticamente. Ele pode conter dois dígitos decimais, por exemplo 19000.00.
Se o produto ou serviço for isento de IVA, atribua 0 a esta variável.		 Sim
discount Número 10.2 Discount value applied to the sale. Não
taxReturnBase Número 10.2 Valor base para cálculo do VAT.
Se o produto ou serviço for isento de IVA, atribua 0 a esta variável.		 Sim
additionalValue Número 10.2 Valor adicional da venda. Não
signature Alfanumérico 255 Assinatura digital criada para cada transação. Consultar Assinatura para forma de pagamento para aprender como gerar. Sim
algorithmSignature Alfanumérico 255 Algoritmo de criptografia da assinatura digital (campo signature). Os três algoritmos disponíveis são: MD5, SHA e SHA256. Não
test Número 1 Indica se a transação está em modo de teste ou produção. Definir 1 para teste e 0para produção. Não
lng Alfanumérico 3 Idioma no qual a plataforma de pagamento deve ser exibida.
Veja os idiomas disponíveis.		 Não
extra1 Alfanumérico 255 Campo adicional para envio de informações sobre a compra. Não
extra2 Alfanumérico 255 Campo adicional para envio de informações sobre a compra. Não
extra3 Alfanumérico 255 Campo adicional para envio de informações sobre a compra. Não
template Alfanumérico 255 Modelo para a página de pagamento. Não
responseUrl Alfanumérico 255 URL da página de resposta. Não
confirmationUrl Alfanumérico 255 URL da página de resposta. Não
sourceUrl Alfanumérico 255 URL de origem das transações do comércio. É aqui que o botão de pagamento está localizado. Não
airline Alfanumérico 4 Código da companhia aérea. Não
billingAddress Alfanumérico 255 Endereço de correspondência. Não
shippingAddress Alfanumérico 255 O endereço de entrega da mercadoria.
* Obrigatório se sua loja enviar o produto.		 Sim*
billingCity Alfanumérico 50 Cidade associada ao endereço de cobrança. Não
shippingCity Alfanumérico 50 A cidade de entrega da mercadoria.
* Obrigatório se sua loja enviar o produto.		 Sim*
zipCode Alfanumérico 20 Código postal. Não
billingCountry Alfanumérico 2 Código ISO do país associado ao endereço de cobrança. Não
shippingCountry Alfanumérico 2 O código ISO do país associado ao endereço de entrega da mercadoria.
* Obrigatório se sua loja enviar o produto.
Veja os países de processamento.		 Sim*
buyerEmail Alfanumérico 255 Campo que contém o e-mail do comprador para notificar o resultado da transação por e-mail. Recomenda-se validar se este campo foi fornecido no formulário. Sim
telephone Alfanumérico Máx. 20 O telefone residencial do comprador. Sim
officeTelephone Alfanumérico Máx. 20 O telefone do comprador em horário comercial. Não
mobilePhone Alfanumérico Máx. 20 O número do celular do comprador. Este valor será usado para preencher o formulário do cartão de crédito e será o telefone de contato. Não
buyerFullName Alfanumérico 150 O nome completo do comprador. Sim
paymentMethods Alfanumérico 255 Lista das formas de pagamento habilitadas no processo de pagamento.
Esta lista deve ser separada por vírgula e sem espaços em branco. Por exemplo: VISA,MASTERCARD.
YVocê pode incluir parcelas para as formas de pagamento adicionando-as usando hifens. Exemplo: VISA-1-3,MASTERCARD-3-5-9.
Veja os métodos de pagamento disponíveis para seu país na coluna Parâmetro paymentMethod.		 Não
administrativeFee Número 10.2 Valor da taxa administrativa. Não
taxAdministrativeFee Número 10.2 Valor do imposto da taxa administrativa. Não
taxAdministrativeFeeReturnBase Número 10.2 Valor base para cálculo do imposto da taxa administrativa. Não
payerEmail Alfanumérico 255 E-mail do pagador. Sim
payerPhone Alfanumérico Máx. 20 Número de telefone do pagador. Sim
payerOfficePhone Alfanumérico Máx. 20 Número de telefone do local de trabalho do pagador. Não
payerMobilePhone Alfanumérico Máx. 20 Número do celular do pagador. Não
expirationDate Alfanumérico 19 Prazo de validade das transações de pagamentos da Dinheiro. Formato: YYYY-MM-DD HH:mm:ss.
Este valor deve ser inferior ao número padrão de dias para o pagamento à vista (15 dias para a Argentina e 7 dias para os demais países).		 -
payerFullName Alfanumérico 50 O nome do pagador. Este valor será usado para preencher o formulário do cartão de crédito. Sim
payerDocument Alfanumérico 25 O número de identificação do comprador. Este valor será usado para preencher o formulário do cartão de crédito. Sim
payerDocumentType Alfanumérico 25 O tipo de identificação do comprador. Este valor será usado para preencher o formulário do cartão de crédito. Sim
iin Alfanumérico 2048 Lista de Bins admitidos durante o processo de pagamento (separados por vírgula).
Este parâmetro só pode ser utilizado por estabelecimentos que validem assinatura.		 Não
paymentMethodsDescription Alfanumérico 255 Descrição dos meios de pagamento e Caixas admitidas durante o processo de pagamento. Não
pseBanks Alfanumérico 255 Lista de códigos bancários habilitados no processo de pagamento via PSE.
Esta lista deve ser separada por vírgula e sem espaços em branco.		 Não

Considerações sobre os Parâmetros

  • O parâmetro tax representa o IVA, aplicável em certos países, enquanto taxReturnBase é o valor base para calcular o IVA. Se o seu produto é isento de impostos, defina ambas as variáveis como 0 (tax=0, taxReturnBase=0)
  • Quando alguns produtos são tributados e outros não, calcule e defina os valores conforme mostrado na tabela abaixo para garantir o envio correto para a plataforma de pagamento.

Exemplo de Cálculo de IVA:

Produto taxReturnBase tax Valor
A 84.033 15.966 (19%) 100.000
B 181.818 18.181 (10%) 200.000
C 0 0 (0%) 150.000
Total 268.851 34.147 450.000
  • Para empresas na Colômbia registradas sob o Régimen Común, se o tax não for informado, a PayU o calcula automaticamente em 19%. Para empresas sob o Régimen Simplificado, se o tax, não for especificado, a PayU atribui um valor de zero (0).

Exemplo de Campos em HTML

A seguir, um exemplo dos campos obrigatórios para um formulário de pagamento no formato HTML, apontando a solicitação para o ambiente sandbox (modo de teste).

 <form method="post" action="https://sandbox.checkout.payulatam.com/ppp-web-gateway-payu/">
  <input name="merchantId"      type="hidden"  value="508029"   >
  <input name="accountId"       type="hidden"  value="512321" >
  <input name="description"     type="hidden"  value="Test PAYU"  >
  <input name="referenceCode"   type="hidden"  value="TestPayU" >
  <input name="amount"          type="hidden"  value="20000"   >
  <input name="tax"             type="hidden"  value="3193"  >
  <input name="taxReturnBase"   type="hidden"  value="16806" >
  <input name="currency"        type="hidden"  value="COP" >
  <input name="signature"       type="hidden"  value="7ee7cf808ce6a39b17481c54f2c57acc"  >
  <input name="test"            type="hidden"  value="0" >
  <input name="buyerEmail"      type="hidden"  value="test@test.com" >
  <input name="responseUrl"     type="hidden"  value="http://www.test.com/response" >
  <input name="confirmationUrl" type="hidden"  value="http://www.test.com/confirmation" >
  <input name="Submit"          type="submit"  value="Enviar" >
</form>

Se a sua loja faz o envio dos produtos, você deve incluir os seguintes valores:

  <input name="shippingAddress"    type="hidden"  value="calle 93 n 47 - 65"   >
  <input name="shippingCity"       type="hidden"  value="Bogotá" >
  <input name="shippingCountry"    type="hidden"  value="CO"  >

A URL configurada em action depende do ambiente:

Teste: https://sandbox.checkout.payulatam.com/ppp-web-gateway-payu/
Produção: https://checkout.payulatam.com/ppp-web-gateway-payu/

Exemplo de Formulário de Pagamento

Este exemplo de formulário de pagamento dinâmico é projetado para testes em nosso ambiente sandbox. Ele oferece uma visão dos campos e funcionalidades que você pode incorporar em seus próprios formulários de pagamento. Abaixo está uma visão geral de suas principais funcionalidades:

  • Geração de Assinatura de Transação: O formulário calcula uma string de assinatura usando a chave da API PayU LATAM, o ID do comerciante e várias entradas do usuário, como método de pagamento e informações bancárias. Esta assinatura é criptografada usando um algoritmo especificado (MD5, SHA ou SHA256) para garantir transações seguras. Para mais detalhes, consulte Assinatura para Formulário de Pagamento.

  • Preenchimento Dinâmico do Formulário: Com base no país e na conta selecionados, o formulário preenche automaticamente vários campos, como tipos de documento, informações de cobrança (por exemplo, cidade, estado, CEP) e informações do pagador. Isso permite que o formulário se ajuste aos requisitos de dados específicos da região (por exemplo, CPF para o Brasil ou CUIT para a Argentina).

  • Gestão de Visibilidade: Várias funções são incluídas para mostrar ou ocultar campos dinamicamente, com base no tipo de conta selecionado. Isso é particularmente útil para lidar com casos específicos, como bancos PSE na Colômbia ou campos adicionais para companhias aéreas e agências de viagens.

  • Tratamento das Informações de Envio: O formulário permite que o usuário use as informações de cobrança como endereço de envio ou especifique detalhes de envio separados. Se o usuário não selecionar uma opção de envio alternativa, as informações de cobrança são usadas por padrão.

  • Ouvintes de Eventos e Envio de Formulário: A página pode usar ouvintes de eventos para atualizar os campos do formulário quando certos valores de entrada (por exemplo, ID da conta) mudam e garante que o processo de envio do formulário respeite as entradas do usuário, com opções alternativas configuradas (por exemplo, uso das informações de cobrança se nenhuma opção de envio for selecionada).

PayU LATAM WebCheckout

Payment Form Example

1. Select a value from the accountId field according to the country where you want to run the tests.

2. Click the button:

3. Click the button: ⓘ :

Remember that you can edit or add additional fields as needed. If you modify or enter values in the paymentMethods, iin, or pseBanks fields after generating a signature, it will be necessary to generate it again.

4. Click the button:





Assinatura para Formulário de Pagamento

A assinatura é uma forma de validar os pagamentos efetuados na plataforma e garantir a sua autenticidade. Consiste em uma string criptografada usando MD5, SHA1 ou SHA256. A string é criada da seguinte maneira:

"ApiKey~merchantId~referenceCode~amount~currency"

Por exemplo, com os seguintes dados:

merchantId: 508029
ApiKey: 4Vj8eK4rloUd272L48hsrarnUA
referenceCode: TestPayU
amount: 20000
currency: COP
accountId: 512326
buyerEmail: test@test.com

A assinatura é:

"4Vj8eK4rloUd272L48hsrarnUA~508029~TestPayU~20000~COP"

Criptografado usando MD5:

"7ee7cf808ce6a39b17481c54f2c57acc"

Criptografado usando SHA1:

"fa890d3f94e12b5cdb62e8771453b99b78e7ccdc"

Criptografado usando SHA256:

"af3899a22336b79db46006491d15813158826f944599bf3bf601e2327f898022"

Gerar uma Assinatura

Este calculador permite que você gere a assinatura usando qualquer um dos métodos de criptografia disponíveis.

Algoritmo:  

 ( ~ ~ ~ ~ )


Resultado: 
Última modificação 28 de novembro de 2024: Documentation Updates (d002e8d69)