Formulario de Pago

En esta sección, aprenderás a enviar datos de transacción al gateway de pagos de PayU. Este documento proporciona la información necesaria para crear un formulario HTML con los detalles de la transacción y enviarlo a nuestro sistema mediante el método HTTP POST.

Consideraciones

  • Asegúrate de tener el merchantId, accountId y apiKey correctos.
  • Usa un código de referencia de pago único para cada transacción.
  • Evita incluir espacios en los valores de los parámetros.
  • Limita los valores decimales a dos cifras.
  • Excluye caracteres especiales en el parámetro referenceCode.

Parameters

Puedes incluir los siguientes parámetros en el formulario de pago.

Parámetros en el formulario de pago
Campo Tipo Tamaño Descripción Obligatorio
lng Alfanumérico 3 El idioma para la pasarela de pago.
Ver idiomas soportados.		 No
merchantId Numérico 12 El número de ID único asignado a tu tienda en el sistema de PayU. Puedes encontrar este número en el correo electrónico de creación de la cuenta. Sí
accountId Numérico 6 El ID asociado a la cuenta de usuario en cada país. Determina los métodos de pago disponibles para el país correspondiente. Sí
algorithmSignature Alfanumérico 255 El algoritmo de encriptación utilizado para la firma digital (campo signature). Las opciones disponibles son: MD5, SHA o SHA256. No
signature Alfanumérico 255 Una firma digital para la transacción. Consulta Firma para el formulario de pago para obtener instrucciones. Sí
sourceUrl Alfanumérico 255 La URL de origen donde se encuentra el botón de pago del comerciante. No
responseUrl Alfanumérico 255 La URL para la página de respuesta. No
confirmationUrl Alfanumérico 255 La URL para la página de confirmación. No
expirationDate Alfanumérico 19 La fecha de expiración para los pagos en efectivo en el formato YYYY-MM-DD HH:mm:ss. Debe estar dentro del rango permitido para los pagos en efectivo (15 días para Argentina, 7 días para otros). -
paymentMethods Alfanumérico 255 La lista de métodos de pago habilitados para la transacción.
Esta lista debe estar separada por comas y sin espacios en blanco, por ejemplo: VISA,MASTERCARD.
Puedes incluir cuotas usando guiones, por ejemplo: VISA-1-3,MASTERCARD-3-5-9.
Consulta los Métodos de pago disponibles para tu país en la columna paymentMethod parameter.		 No
selectedPaymentMethod Alfanumérico 255 Un método de pago preseleccionado cuando el usuario accede al enlace de pago. No
paymentMethodsDescription Alfanumérico 255 Una descripción de los métodos de pago y Bins aceptados para la transacción. No
iin Alfanumérico 2048 Una lista de Bins admitidos durante el proceso de pago, separados por comas. Solo los comerciantes que validan firmas pueden usar este parámetro. No
pseBanks Alfanumérico 255 Una lista de códigos de bancos habilitados para pagos a través de PSE. No
partnerId Alfanumérico 255 Un campo opcional para especificar el nombre del socio (por ejemplo, ZOOZ). No
template Alfanumérico 255 La plantilla que se utilizará para la página de pago. No
extra1 Alfanumérico 255 Campo adicional para enviar información extra sobre la compra. No
extra2 Alfanumérico 255 Campo adicional para enviar información extra sobre la compra. No
extra3 Alfanumérico 255 Campo adicional para enviar información extra sobre la compra. No
extra4 Alfanumérico 255 Campo adicional para enviar información extra sobre la compra. No
displayShippingInformation Numérico 1 Establecer en 1 para solicitar información de envío, o 0 para deshabilitarlo. No
additionalDeliveryDays Numérico 5 Días adicionales para la entrega del pedido, que aparecerán en la respuesta de la consulta API como result.payload.transactions.extraParameters.ADDITIONAL_DELIVERY_DAYS. No
displayBuyerComments Numérico 1 Establecer en 1 para habilitar los comentarios del comprador, o 0 para deshabilitarlo. Esto aparece en la respuesta de la API como result.payload.transactions.extraParameters.DISPLAY_BUYER_COMMENTS. No
buyerCommentsLabel Alfanumérico 255 La etiqueta para los comentarios del comprador, que aparece en la respuesta de la API como result.payload.transactions.extraParameters.BUYER_COMMENTS_LABEL. No
isCashOnDeliveryApply Numérico 1 Establecer en 1 para habilitar el pago contra entrega para la transacción, o 0 para deshabilitarlo. No
test Numérico 1 Indica si la transacción está en modo de prueba (1) o modo de producción (0). No
description Alfanumérico 255 Una descripción de la venta. Sí
referenceCode Alfanumérico 255 Una referencia única para la venta o el pedido. Debe ser única para cada transacción enviada al sistema, normalmente utilizada para el seguimiento de las solicitudes. Sí
amount Numérico 10 El importe total de la transacción, que puede incluir dos dígitos decimales. Ej. 10000.00 o 10000. Sí
tax Numérico 10.2 El valor del IVA para la transacción. En Colombia, si no se proporciona IVA, el sistema aplica el 19% automáticamente. Si el IVA está exento, establecer en 0. Sí
taxReturnBase Numérico 10.2 El valor base utilizado para calcular el IVA. Si el producto está exento de IVA, establecer en 0. Sí
administrativeFee Numérico 10.2 La tarifa administrativa para la transacción. No
taxAdministrativeFee Numérico 10.2 El impuesto aplicado a la tarifa administrativa. No
taxAdministrativeFeeReturnBase Numérico 10.2 El valor base para calcular el impuesto de la tarifa administrativa. No
discount Numérico 10.2 El descuento aplicado a la venta. No
currency Alfanumérico 3 La moneda utilizada para el pago. En Colombia, las conciliaciones se realizan en pesos colombianos a la tasa representativa del día.
Ver monedas aceptadas.		 Sí
airline Alfanumérico 4 El código de la aerolínea para las transacciones de aerolíneas. No
additionalValue Numérico 10.2 Cualquier valor adicional agregado a la venta. No
payerFullName Alfanumérico 50 El nombre completo del pagador, utilizado para rellenar el formulario de la tarjeta de crédito. Sí
payerEmail Alfanumérico 255 La dirección de correo electrónico del pagador. Sí
payerOfficePhone Alfanumérico Máx. 20 El número de teléfono del lugar de trabajo del pagador. No
payerPhone Alfanumérico Máx. 20 El número de teléfono del pagador. Sí
payerMobilePhone Alfanumérico Máx. 20 El número de teléfono móvil del pagador. No
payerDocumentType Alfanumérico 25 El tipo de documento de identificación utilizado por el pagador. Ejemplos: CC, DNI. NIT, Pasaporte. Sí
payerDocument Alfanumérico 25 El número de identificación del pagador, utilizado para rellenar el formulario de la tarjeta de crédito. Sí
billingCountry Alfanumérico 2 El código de país ISO para la dirección de facturación. No
payerState Alfanumérico N/A El estado de facturación del pagador en código ISO 3166 (por ejemplo, SP para São Paulo, AR-C para Buenos Aires). No
billingCity Alfanumérico 50 La ciudad asociada a la dirección de facturación. No
billingAddress Alfanumérico 255 La dirección de facturación para la transacción. No
billingAddress2 Alfanumérico 255 La línea de dirección secundaria para la dirección de facturación del pagador. No
billingAddress3 Alfanumérico 255 La línea de dirección terciaria para la dirección de facturación del pagador. No
zipCode Alfanumérico 20 El código postal para la dirección de facturación o envío. No
buyerFullName Alfanumérico 150 El nombre completo del comprador. Sí
buyerEmail Alfanumérico 255 La dirección de correo electrónico del comprador, utilizada para las notificaciones de la transacción. Sí
buyerDocumentType Alfanumérico 25 El tipo de documento de identificación utilizado por el comprador. Ejemplos: CC, DNI. NIT, Pasaporte. Sí
buyerDocument Alfanumérico 25 El número de identificación del comprador. Sí
officeTelephone Alfanumérico Máx. 20 El número de teléfono diurno del comprador. No
telephone Alfanumérico Máx. 20 El número de teléfono de residencia del comprador. Sí
mobilePhone Alfanumérico Máx. 20 El número de teléfono móvil del comprador, utilizado para rellenar el formulario de la tarjeta de crédito y como teléfono de contacto. No
shippingCountry Alfanumérico 2 El código de país ISO para la dirección de envío.
*Obligatorio si la tienda envía el producto.
Ver países de procesamiento.		 Sí*
shippingState Alfanumérico N/A El estado de envío del comprador en código ISO 3166 (por ejemplo, SP para São Paulo, AR-C para Buenos Aires). No
shippingCity Alfanumérico 50 La ciudad a la que el comerciante entregará el producto o servicio.
*Obligatorio si la tienda envía el producto.		 Sí*
shippingAddress Alfanumérico 255 La dirección a la que el comerciante entregará el producto o servicio.
*Obligatorio si la tienda envía el producto.		 Sí*
shippingAddress2 Alfanumérico 255 La línea de dirección secundaria para la dirección de envío del comprador. No
shippingAddress3 Alfanumérico 255 La línea de dirección terciaria para la dirección de envío del comprador. No
payerShippingPostalCode Alfanumérico N/A El código postal de envío del comprador. No

Consideraciones para los Parámetros

  • El parámetro tax representa el IVA, aplicable en ciertos países, mientras que taxReturnBase es el monto base para calcular el IVA. Si tu producto está exento de impuestos, establece ambas variables en 0 (tax=0, taxReturnBase=0).
  • Cuando algunos productos tienen impuestos y otros no, calcula y establece los valores como se muestra en la tabla a continuación para asegurar un envío preciso a la plataforma de pagos.

Ejemplo de Cálculo de IVA:

Producto 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 comercios registrados en Colombia bajo el Régimen Común, si no envías tax, PayU lo calcula automáticamente utilizando el 19%. Para comercios bajo el Régimen Simplificado, si no envías tax, PayU asigna cero (0) automáticamente al valor del impuesto.

Ejemplo de Campos HTML

A continuación, se muestra un ejemplo de los campos obligatorios para un formulario de pago en formato HTML, apuntando la solicitud al entorno sandbox (modo de prueba).

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

Si tu tienda envía los productos, necesitas incluir los siguientes campos:

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

La URL configurada en el campo action depende del ambiente:

Pruebas: https://sandbox.checkout.payulatam.com/ppp-web-gateway-payu/
Producción: https://checkout.payulatam.com/ppp-web-gateway-payu/

Ejemplo de Formulario de Pago

Este ejemplo de formulario de pago dinámico está diseñado para realizar pruebas en nuestro entorno sandbox. Ofrece una visión de los campos y características que puedes incorporar en tus propios formularios de pago. A continuación, se presenta un resumen de sus características clave:

  • Generación de Firma de Transacción: El formulario calcula una cadena de firma utilizando la clave API de PayU LATAM, el ID del comercio y varios datos ingresados por el usuario, como el método de pago y la información bancaria. Esta firma se encripta con un algoritmo especificado (MD5, SHA o SHA256) para asegurar las transacciones. Para más detalles, consulta Firma para Formulario de Pago.

  • Diligenciamiento Dinámico del Formulario: Según el país y la cuenta seleccionados, el formulario completa automáticamente varios campos, como tipos de documentos, información de facturación (por ejemplo, ciudad, estado, código postal) e información del pagador. Esto permite que el formulario se ajuste a los requisitos específicos de cada región (por ejemplo, CPF para Brasil o CUIT para Argentina).

  • Gestión de Visibilidad: Se incluyen varias funciones para mostrar u ocultar campos dinámicamente según el tipo de cuenta seleccionado. Esto es especialmente útil para manejar casos específicos como bancos PSE en Colombia o campos adicionales para aerolíneas y agencias de viajes.

  • Gestión de Información de Envío: El formulario permite que el usuario utilice la información de facturación como dirección de envío o especifique detalles de envío separados. Si el usuario no selecciona una opción de envío alternativa, se utiliza la información de facturación de forma predeterminada.

  • Listeners de Eventos y Envío del Formulario: La página puede utilizar listeners de eventos para actualizar campos del formulario cuando cambian ciertos valores de entrada (por ejemplo, el ID de cuenta) y asegura que el proceso de envío del formulario respete la información ingresada por el usuario, con opciones de respaldo (por ejemplo, usar la información de facturación si no se selecciona una opción de envío).

PayU LATAM WebCheckout

Ejemplo de Formulario de Pago

1. Selecciona un id de cuenta en el campo accountId de acuerdo con el país donde deseas realizar pruebas.

2. Haz clic en el botón:

3. Haz clic en el botón ⓘ :

Recuerda que puedes editar o agregar campos adicionales según sea necesario. Si modificas o ingresas valores en los campos *paymentMethods*, *iin* o *pseBanks* después de haber generado una firma, será necesario generarla.

4. Haz clic en el botón:





Firma para el Formulario de Pago

La firma es un método para validar los pagos realizados a través de la plataforma asegurando su autenticidad. Consiste en un string encriptado utilizando MD5, SHA1 o SHA256. El string creado es así:

"ApiKey~merchantId~referenceCode~amount~currency".

Por ejemplo, con los siguientes datos:

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

La firma es:

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

Encriptada utilizando MD5:

"7ee7cf808ce6a39b17481c54f2c57acc"

Encriptada utilizando SHA1:

"fa890d3f94e12b5cdb62e8771453b99b78e7ccdc"

Encriptada utilizando SHA256:

"af3899a22336b79db46006491d15813158826f944599bf3bf601e2327f898022"

Genera una Firma

Esta calculadora te permite generar la firma utilizando alguno de los métodos de cifrado disponibles.

Algoritmo:  

 ( ~ ~ ~ ~ )


Resultado: 
Última modificación 30 de enero de 2025: Documentation Updates (e6f7f9ba4)