Formulario de Pago
Consideraciones
- Asegúrate de tener el
merchantId
,accountId
yapiKey
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 |
---|---|---|---|---|
merchantId | Numérico | 12 | Identificador de tu tienda en el sistema de PayU, puedes encontrar este número en el correo de creación de tu cuenta. | Sí |
referenceCode | Alfanumérico | 255 | Referencia de la venta o la orden. Debe ser única por cada transacción enviada al sistema. Usualmente, esta es una forma de identificar las peticiones enviadas a la pasarela de pagos. | Sí |
accountId | Numérico | 6 | Identificador de la cuenta de usuario de cada país asociado con la tienda. Esta variable se utiliza para mostrar los métodos disponibles del país. | Sí |
description | Alfanumérico | 255 | Descripción de la venta. | Sí |
currency | Alfanumérico | 3 | Moneda respectiva en la que se hace el pago. El proceso de conciliación se realiza en pesos colombianos a la tasa representativa del día. Ver monedas aceptadas. |
Sí |
amount | Numérico | 10 | Valor total de la transacción. Puede tener dos cifras decimales. Ejemplo 10000.00 o 10000. | Sí |
tax | Numérico | 10.2 | Valor del impuesto al valor agregado de la transacción. En Colombia, si no se envía el IVA. el sistema aplica automáticamente el 19%. Puede tener dos dígitos decimales, por ejemplo 19000.00. Si el producto o servicio es exento de impuesto al valor agregado, asigne 0 a esta variable. |
Sí |
discount | Numérico | 10.2 | Valor del descuento sobre la venta. | No |
taxReturnBase | Numérico | 10.2 | Valor base para la devolución de impuestos. Si el producto o servicio es exento de impuesto al valor agregado, asigne 0 a esta variable. |
Sí |
additionalValue | Numérico | 10.2 | Valor adicional no comisionable de la venta. | No |
signature | Alfanumérico | 255 | Firma digital creada por cada transacción. Consulta Firma para el formulario de pago para aprender a generarla. | Sí |
algorithmSignature | Alfanumérico | 255 | Algoritmo de encriptación de la firma digital (campo signature ). Los tres algoritmos disponibles son: MD5 , SHA y SHA256 . |
No |
test | Numérico | 1 | Indica si la transacción es en modo pruebas o en producción. Asigna 1 para pruebas y 0 para producción. |
No |
lng | Alfanumérico | 3 | Idioma en el que se quiere mostrar la pasarela de pagos. Ver idiomas soportados. |
No |
extra1 | Alfanumérico | 255 | Campo adicional para enviar información relacionada con la compra. | No |
extra2 | Alfanumérico | 255 | Campo adicional para enviar información relacionada con la compra. | No |
extra3 | Alfanumérico | 255 | Campo adicional para enviar información relacionada con la compra. | No |
template | Alfanumérico | 255 | Plantilla para la página de pagos. | No |
responseUrl | Alfanumérico | 255 | URL de la página de respuesta. | No |
confirmationUrl | Alfanumérico | 255 | URL de la página de confirmación. | No |
sourceUrl | Alfanumérico | 255 | URL de origen de las transacciones del comercio. Aquí es donde se encuentra ubicado el botón de pago. | No |
airline | Alfanumérico | 4 | Código de la aerolínea. | No |
billingAddress | Alfanumérico | 255 | Dirección de facturación. | No |
shippingAddress | Alfanumérico | 255 | Dirección de entrega de la mercancía. * Obligatorio si tu tienda envía el producto. |
Sí* |
billingCity | Alfanumérico | 50 | Ciudad asociada con la dirección de facturación. | No |
shippingCity | Alfanumérico | 50 | Ciudad de entrega de la mercancía * Obligatorio si tu tienda envía el producto. |
Sí* |
zipCode | Alfanumérico | 20 | Postal code. | No |
billingCountry | Alfanumérico | 2 | Código ISO del país asociado con la dirección de facturación. | No |
shippingCountry | Alfanumérico | 2 | Código ISO del país de entrega de lla mercancía. * Obligatorio si tu tienda envía el producto. Ver los paises de pago. |
Sí* |
buyerEmail | Alfanumérico | 255 | Campo que contiene el correo electrónico del comprador para notificar el resultado de la transacción por medio de correo electrónico. Se recomienda validar que se haya ingresado este campo en el formulario. | Sí |
telephone | Alfanumérico | Máx. 20 | Teléfono de residencia del comprador. | Sí |
officeTelephone | Alfanumérico | Máx. 20 | Teléfono diurno del comprador. | No |
mobilePhone | Alfanumérico | Máx. 20 | Número del móvil del comprador. Este valor será utilizado para diligenciar el formulario de la tarjeta de crédito y será el número de teléfono de contacto. | No |
buyerFullName | Alfanumérico | 150 | Nombre completo del comprador. | Sí |
paymentMethods | Alfanumérico | 255 | Lista de métodos de pago habilitados en el proceso de pago. Esta lista debe estar separada por comas y sin espacios en blanco. Por ejemplo: VISA,MASTERCARD .Puedes incluir cuotas para los métodos de pago añadiéndolas mediante guiones. Ejemplo: VISA-1-3,MASTERCARD-3-5-9 .Consulta los métodos de pago disponibles para tu país en la columna parámetro de método de pago . |
No |
administrativeFee | Numérico | 10.2 | Valor de la tarifa administrativa. | - |
taxAdministrativeFee | Numérico | 10.2 | Valor del impuesto de la tarifa administrativa. | - |
taxAdministrativeFeeReturnBase | Numérico | 10.2 | Valor base para calcular el impuesto de la tarifa administrativa. | - |
payerEmail | Alfanumérico | 255 | Dirección de correo electrónico del pagador. | Sí |
payerPhone | Alfanumérico | Máx. 20 | Número de teléfono del pagador. | Sí |
payerOfficePhone | Alfanumérico | Máx. 20 | Número de teléfono de oficina del pagador. | No |
payerMobilePhone | Alfanumérico | Máx. 20 | Número de teléfono móvil del pagador. | No |
expirationDate | #N/A | 19 | Fecha de vencimiento de las transacciones para pagos en efectivo. Formato: YYYY-MM-DD HH:mm:ss .Este valor debe ser menor que el número de días predeterminado para el pago en efectivo (15 días para Argentina y 7 días para el resto de países). |
- |
payerFullName | Alfanumérico | 50 | Nombre del pagador. Este valor será utilizado para diligenciar el formulario de la tarjeta de crédito. | Sí |
payerDocument | Alfanumérico | 25 | Número de identificación del pagador. Este valor será utilizado para diligenciar el formulario de la tarjeta de crédito. | Sí |
payerDocumentType | Alfanumérico | 25 | El número de identificación del comprador. Este valor se tomará para completar el formulario de la tarjeta de crédito. | Sí |
iin | Alfanumérico | 2048 | Lista de Bins admitidos durante el proceso de pago (separados por coma). Este parámetro solo lo pueden utilizar los comercios que validan la firma. |
No |
PaymentMethodsDescription | Alfanumérico | 255 | Descripción de los métodos de pago y Bins admitidos durante el proceso de pago. | No |
pseBanks | Alfanumérico | 255 | Listado de códigos bancarios habilitados en el proceso de pago a través de PSE. Este listado debe estar separado por coma y sin espacios en blanco. |
No |
Consideraciones para los Parámetros
- El parámetro
tax
representa el IVA, aplicable en ciertos países, mientras quetaxReturnBase
es el monto base para calcular el IVA. Si tu producto está exento de impuestos, establece ambas variables en0
(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 |
Importante
La suma detax
y taxReturnBase
no debe exceder el valor total de cada producto.
- 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íastax
, 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).
Ejemplo de Formulario de Pago
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".
Nota
Si tu formulario de pago incluye las variables paymentMethods
, iin
o pseBanks
, debes concatenarlas en dicho orden:
"ApiKey~merchantId~referenceCode~amount~currency~paymentMethods~iin~pseBanks"
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.