API de Pagos - Colombia

La API de Pagos de Colombia le permite a tu tienda procesar diferentes tipos de transacciones con múltiples métodos de pago.

Para integrarte con la API de Pagos para Colombia, dirige tus solicitudes a las siguientes URL según el entorno correspondiente.

Métodos disponibles

La API de pagos incluye los siguiente métodos:

Enviar transacciones utilizando tarjetas de crédito o débito

Este método te permite procesar los pagos que realizan tus clientes utilizando tarjetas de crédito o débito. Para Colombia, puedes realizar los flujos de un paso (Cobro). Para más información, consulta los flujos de pago.

Parámetros para la petición y la respuesta

Petición (Request)
Nombre del campo Formato Tamaño Descripción Obligatorio
language Alfanumérico 2 Idioma utilizado en la petición, este idioma se utiliza para mostrar los mensajes de error generados. Ver idiomas soportados. Sí
command Alfanumérico Máx:32 Asigna SUBMIT_TRANSACTION. Sí
test (JSON)
isTest (XML)		 Booleano Asigna true si la petición es en modo pruebas. Si no, asigna false. Sí
merchant Objeto Este objeto contiene los datos de autenticación. Sí
merchant > apiLogin Alfanumérico Min:12 Máx:32 Usuario o login entregado por PayU. Cómo obtengo mi API Login Sí
merchant > apiKey Alfanumérico Min:6 Máx:32 Contraseña entregada por PayU. Cómo obtengo mi API Key Sí
transaction Objeto Este objeto contiene los datos de la transacción. Sí
transaction > order Objeto Este objeto contiene los datos de la orden. Sí
transaction > order > accountId Numérico Identificador de tu cuenta. Sí
transaction > order > referenceCode Alfanumérico Min:1 Máx:255 Representa el identificador de la orden en tu sistema. Sí
transaction > order > description Alfanumérico Min:1 Máx:255 Descripción de la orden. Sí
transaction > order > language Alfanumérico 2 Idioma utilizado en los correos electrónicos enviados al comprador y al vendedor. Sí
transaction > order > notifyUrl Alfanumérico Máx:2048 URL de confirmación de la orden. No
transaction > order > partnerId Alfanumérico Máx:255 ID de aliado dentro de PayUID de aliado dentro de PayU. No
transaction > order > signature Alfanumérico Máx:255 Firma asociada al formulario. Para más información, consulta Firma de autenticación. Sí
transaction > order > shippingAddress Objeto Dirección de envío. No
transaction > order > shippingAddress > street1 Alfanumérico Máx:100 Línea de dirección 1. No
transaction > order > shippingAddress > street2 Alfanumérico Máx:100 Línea de dirección 2. No
transaction > order > shippingAddress > city Alfanumérico Máx:50 Ciudad de la dirección. No
transaction > order > shippingAddress > state Alfanumérico Máx:40 Departamento de la dirección. No
transaction > order > shippingAddress > country Alfanumérico 2 País de la dirección. No
transaction > order > shippingAddress > postalCode Alfanumérico Máx:8 Código postal de la dirección. No
transaction > order > shippingAddress > phone Alfanumérico Máx:11 Número de teléfono asociado con la dirección. No
transaction > order > buyer Objeto Información del comprador. Sí
transaction > order > buyer > merchantBuyerId Alfanumérico Máx:100 Identificador del comprador en tu sistema. No
transaction > order > buyer > fullName Alfanumérico Máx:150 Nombre del comprador. Sí
transaction > order > buyer > emailAddress Alfanumérico Máx:255 Correo electrónico del comprador. Sí
transaction > order > buyer > contactPhone Alfanumérico Máx:20 Número de teléfono del comprador. Sí
transaction > order > buyer > dniNumber Alfanumérico Máx:20 Número de identificación del comprador. Sí
transaction > order > buyer > shippingAddress Objeto Dirección de envío del comprador. Sí
transaction > order > buyer > shippingAddress > street1 Alfanumérico Máx:150 Línea de dirección 1 del comprador. Sí
transaction > order > buyer > shippingAddress > city Alfanumérico Máx:50 Ciudad de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > state Alfanumérico Máx:40 Departamento de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > country Alfanumérico 2 País de la dirección del comprador en formato ISO 3166 alpha-2. Sí
transaction > order > buyer > shippingAddress > postalCode Numérico Máx:20 Código postal de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > phone Numérico Máx:20 Número de teléfono de la dirección del comprador. Sí
transaction > order > additionalValues > Objeto 64 Monto de la orden y sus valores asociados. Sí
transaction > order > additionalValues > TX_VALUE Alfanumérico 64 Monto de la transacción. Sí
transaction > order > additionalValues > TX_VALUE > value Numérico 12, 2 Especifica el monto de la transacción, este valor no puede tener decimales. Sí
transaction > order > additionalValues > TX_VALUE > currency Alfanumérico 3 Código ISO de la moneda. Ver monedas aceptadas. No
transaction > order > additionalValues > TX_TAX Alfanumérico 64 Monto del IVA (Impuesto al Valor Agregado). Sí
transaction > order > additionalValues > TX_TAX > value Numérico 12, 2 Especifica el monto del IVA.
Si no se envía este parámetro, PayU aplica el impuesto actual (19%).
Si la cantidad está exenta de IVA, envía 0.
Este valor puede tener dos dígitos decimales		 No
transaction > order > additionalValues > TX_TAX > currency Alfanumérico 3 Código ISO de la moneda. Ver monedas aceptadas. No
transaction > order > additionalValues > TX_TAX_RETURN_BASE Alfanumérico 64 Valor base para calcular el IVA.
Si la cantidad está exenta de IVA, envía 0.
Este valor puede tener dos dígitos decimales		 No
transaction > order > additionalValues > TX_TAX_RETURN_BASE > value Numérico 12, 2 Especifica el valor base de la transacción. No
transaction > order > additionalValues > TX_TAX_RETURN_BASE > currency Alfanumérico 3 Código ISO de la moneda. Ver monedas aceptadas. No
transaction > creditCardTokenId Objeto Incluye este parámetro cuando la transacción se hace con una tarjeta de crédito tokenizada; además, es obligatorio enviar el parámetro transaction.creditCard.expirationDate.
Para más información, consulte API de Tokenización.		 No
transaction > creditCard Objeto Información de la tarjeta de crédito. Este objeto y sus parámetros son obligatorios cuando el pago se realiza utilizando una tarjeta de crédito no tokenizada. No
transaction > creditCard > number Alfanumérico Min:13 Máx:20 Número de la tarjeta de crédito. No
transaction > creditCard > securityCode Alfanumérico Min:1 Máx:4 Código de seguridad de la tarjeta de crédito (CVC2, CVV2, CID). No
transaction > creditCard > expirationDate Alfanumérico 7 Fecha de expiración de la tarjeta de crédito. Formato YYYY/MM. No
transaction > creditCard > name Alfanumérico Min:1 Máx:255 Nombre del tarjetahabiente mostrado en la tarjeta de crédito. No
transaction > creditCard > processWithoutCvv2 Booleano Máx:255 Te permite procesar transacciones sin incluir el código de seguridad de la tarjeta de crédito. Tu comercio requiere autorización de PayU antes de utilizar esta funcionalidad. No
transaction > payer Objeto Información del pagador. Sí
transaction > payer > emailAddress Alfanumérico Máx:255 Correo electrónico del pagador. Sí
transaction > payer > merchantPayerId Alfanumérico Máx:100 Identificador del pagador en tu sistema. No
transaction > payer > fullName Alfanumérico Máx:150 Nombre del pagador que debe ser igual al enviado en el parámetro transaction.creditCard.name. Sí
transaction > payer > billingAddress Objeto Dirección de facturación. Sí
transaction > payer > billingAddress > street1 Alfanumérico Máx:100 Línea 1 de la dirección de facturación. Sí
transaction > payer > billingAddress > street2 Alfanumérico Máx:100 Línea 2 de la dirección de facturación. No
transaction > payer > billingAddress > city Alfanumérico Máx:50 Ciudad de la dirección de facturación. Sí
transaction > payer > billingAddress > state Alfanumérico Máx:40 Departamento de la dirección de facturación. No
transaction > payer > billingAddress > country Alfanumérico 2 País de la dirección de facturación en formato ISO 3166 Alpha-2. Sí
transaction > payer > billingAddress > postalCode Alfanumérico Máx:20 Código postal de la dirección de facturación. No
transaction > payer > billingAddress > phone Alfanumérico Máx:20 Número de teléfono de la dirección de facturación. No
transaction > payer > birthdate Alfanumérico Máx:10 Fecha de nacimiento del pagador. No
transaction > payer > contactPhone Alfanumérico Máx:20 Número de teléfono del pagador. Sí
transaction > payer > dniNumber Alfanumérico Máx:20 Número de identificación del pagador. Sí
transaction > payer > dniType Alfanumérico 2 Tipo de identificación del pagador. Ver tipos de documentos. No
transaction > type Alfanumérico 32 Asigna este valor de acuerdo con el tipo de transacción. Para Colombia, asigna AUTHORIZATION_AND_CAPTURE Sí
transaction > paymentMethod Alfanumérico 32 Selecciona un método de pago de Tarjeta de crédito valido. Ver los métodos de pago disponibles para Colombia. Sí
transaction > paymentCountry Alfanumérico 2 Asigna CO para Colombia. Sí
transaction > deviceSessionId Alfanumérico Máx:255 Identificador de la sesión del dispositivo donde el cliente realiza la transacción. Para más información, consulta esta sección. Sí
transaction > ipAddress Alfanumérico Máx:39 Dirección IP del dispositivo donde el cliente realiza la transacción. Sí
transaction > cookie Alfanumérico Máx:255 Cookie almacenada por el dispositivo donde el cliente realiza la transacción. Sí
transaction > userAgent Alfanumérico Máx:1024 User agent del navegador donde el cliente realiza la transacción. Sí
transaction > extraParameters Objeto Parámetros adicionales o datos asociados a la petición. El tamaño máximo de cada nombre de extraParameters es 64 caracteres.
En JSON, el parámetro extraParameters sigue esta estructura:
"extraParameters": {
 "INSTALLMENTS_NUMBER": 1
}

En XML, el parámetro extraParameters sigue esta estructura:
<extraParameters>
 <entry>
  <string>INSTALLMENTS_NUMBER</string>
  <string>1</string>
 </entry>
</extraParameters>		 No
transaction > threeDomainSecure Objeto Este objeto contiene la información de 3DS 2.0. No
transaction > threeDomainSecure > embedded Booleano Asigna true si quieres utilizar un MPI embebido para el proceso de Autorización. Por defecto, este valor está asignado como false. No
transaction > threeDomainSecure > eci Numérico Máx:2 Indicador de Comercio Electrónico.
Valor retornado por los servidores de directorio indicando el intento de autenticación.
Este parámetro es obligatorio cuando transaction.threeDomainSecure.embedded es false y transaction.threeDomainSecure.xid tiene un valor configurado.		 No
transaction > threeDomainSecure > cavv Alfanumérico Máx:28 Valor de verificación de autenticación del titular de la tarjeta (Cardholder Authentication Verification Value).
Código del criptograma utilizado en la autenticación de la transacción codificado en Base 64.
Dependiendo de los códigos ECI específicos establecidos por la red, este valor puede ser opcional.		 No
transaction > threeDomainSecure > xid Alfanumérico Máx:28 Identificador de la transacción enviado por el MPI codificado en Base 64.
Este parámetro es obligatorio cuando transaction.threeDomainSecure.embedded is false y transaction.threeDomainSecure.eci tiene un valor configurado.		 No
transaction > threeDomainSecure > directoryServerTransactionId Alfanumérico Máx:36 Identificador de la transacción generador por el servidor de directorio durante la autenticación. No
Respuesta (Response)
Nombre del campo Formato Tamaño Descripción
code Alfanumérico Código de respuesta de la transacción. Los valores posibles son ERROR y SUCCESS.
error Alfanumérico Máx:2048 Mensaje de error asociado cuando el código de respuesta es ERROR.
transactionResponse Objeto Datos de la respuesta.
transactionResponse > orderId Numérico Identificador generado o existente de la orden en PayU.
transactionResponse > transactionId Alfanumérico 36 Identificador de la transacción en PayU.
transactionResponse > state Alfanumérico Máx:32 Estado de la transacción.
transactionResponse > responseCode Alfanumérico Máx:64 Código de respuesta asociado con el estado.
transactionResponse > paymentNetworkResponseCode Alfanumérico Máx:255 Código de respuesta retornado por la red bancaria.
transactionResponse > paymentNetworkResponseErrorMessage Alfanumérico Máx:255 Mensaje de error retornado por la red bancaria.
transactionResponse > trazabilityCode Alfanumérico Máx:32 Código de trazabilidad retornado por la red bancaria.
transactionResponse > authorizationCode Alfanumérico Máx:12 Código de autorización retornado por la red bancaria.
transactionResponse > responseMessage Alfanumérico Máx:2048 Mensaje asociado con el código de respuesta.
transactionResponse > operationDate Fecha Fecha de creación de la respuesta en el sistema de PayU.
transactionResponse > extraParameters Objeto Parámetros adicionales o datos asociados con la respuesta.
En JSON, el parámetro extraParameters sigue esta estructura:
"extraParameters": {
 "BANK_REFERENCED_CODE": "CREDIT"
}

En XML, el parámetro extraParameters sigue esta estructura:
<extraParameters>
 <entry>
  <string>BANK_REFERENCED_CODE</string>
  <string>CREDIT</string>
 </entry>
</extraParameters>
transactionResponse > additionalInfo Objeto Información adicional de la respuesta. Este objeto tiene la misma estructura de transactionResponse.extraParameters.

Consideraciones

  • Para pagos con tókenes de tarjeta, incluya los parámetros transaction.creditCardTokenId y transaction.creditCard.securityCode (Si procesas con código de seguridad) reemplazando la información de la tarjeta de crédito. Para más información, consulta el API de Tokenización.
  • Por defecto, el procesamiento de tarjetas de crédito sin código de seguridad no está activo. Si lo quieres activar, contacta a tu representante de ventas. Luego de que esté activado, envía en la petición la variable creditCard.processWithoutCvv2 con valor true y elimina la variable creditCard.securityCode.
  • La variable transaction.threeDomainSecure no reemplaza la información de la tarjeta o ninguno de los campos obligatorios de la transacción. Este objeto es adicional y no es obligatorio.
  • La variable transaction.threeDomainSecure corresponde a un escenario Pass Through donde el comercio realiza la autenticación por su cuenta.
  • Para la tarjeta Crédito Fácil Codensa, el número de cuotas soportadas es 1 a 12, 18, 24, 36 y 48.
  • Para la tarjeta Crédito Fácil Codensa, el pagador puede escoger uno de los siguientes tipos de documento en la variable transaction.payer.dniType:
ISO Descripción
CC Cédula de ciudadanía.
CE Cédula de extranjería.
NIT Número de Identificación Tributaria (Empresas).
TI Tarjeta de identidad.
PP Pasaporte.
IDC Identificador único de cliente, para el caso de ID’s únicos de clientes/usuarios de servicios públicos.
CEL En caso de identificarse a través de la línea del móvil.
RC Registro civil de nacimiento.
DE Documento de identificación extranjero.

Llamado a la API

Los siguientes son los cuerpos de la petición y la respuesta para este método de pago.


Ejemplo de una petición:

{
   "language": "es",
   "command": "SUBMIT_TRANSACTION",
   "merchant": {
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction": {
      "order": {
         "accountId": "512321",
         "referenceCode": "PRODUCT_TEST_2021-06-23T19:59:43.229Z",
         "description": "Payment test description",
         "language": "es",
         "signature": "1d6c33aed575c4974ad5c0be7c6a1c87",
         "notifyUrl": "http://www.payu.com/notify",
         "additionalValues": {
            "TX_VALUE": {
               "value": 65000,
               "currency": "COP"
         },
            "TX_TAX": {
               "value": 10378,
               "currency": "COP"
         },
            "TX_TAX_RETURN_BASE": {
               "value": 54622,
               "currency": "COP"
         }
         },
         "buyer": {
            "merchantBuyerId": "1",
            "fullName": "First name and second buyer name",
            "emailAddress": "buyer_test@test.com",
            "contactPhone": "7563126",
            "dniNumber": "123456789",
            "shippingAddress": {
               "street1": "Cr 23 No. 53-50",
               "street2": "5555487",
               "city": "Bogotá",
               "state": "Bogotá D.C.",
               "country": "CO",
               "postalCode": "000000",
               "phone": "7563126"
            }
         },
         "shippingAddress": {
            "street1": "Cr 23 No. 53-50",
            "street2": "5555487",
            "city": "Bogotá",
            "state": "Bogotá D.C.",
            "country": "CO",
            "postalCode": "0000000",
            "phone": "7563126"
         }
      },
      "payer": {
         "merchantPayerId": "1",
         "fullName": "First name and second payer name",
         "emailAddress": "payer_test@test.com",
         "contactPhone": "7563126",
         "dniNumber": "5415668464654",
         "billingAddress": {
            "street1": "Cr 23 No. 53-50",
            "street2": "125544",
            "city": "Bogotá",
            "state": "Bogotá D.C.",
            "country": "CO",
            "postalCode": "000000",
            "phone": "7563126"
         }
      },
      "creditCard": {
         "number": "4037997623271984",
         "securityCode": "321",
         "expirationDate": "2030/12",
         "name": "APPROVED"
      },
      "extraParameters": {
         "INSTALLMENTS_NUMBER": 1
      },
      "type": "AUTHORIZATION_AND_CAPTURE",
      "paymentMethod": "VISA",
      "paymentCountry": "CO",
      "deviceSessionId": "vghs6tvkcle931686k1900o6e1",
      "ipAddress": "127.0.0.1",
      "cookie": "pt1t38347bs6jc9ruv2ecpv7o2",
      "userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0",
      "threeDomainSecure": {
         "embedded": false,
         "eci": "01",
         "cavv": "AOvG5rV058/iAAWhssPUAAADFA==",
         "xid": "Nmp3VFdWMlEwZ05pWGN3SGo4TDA=",
         "directoryServerTransactionId": "00000-70000b-5cc9-0000-000000000cb"
      }
   },
   "test": true
}

Ejemplo de una respuesta:

{
    "code": "SUCCESS",
    "error": null,
    "transactionResponse": {
        "orderId": 1400449660,
        "transactionId": "aa2f50b2-62a8-42de-b3be-c6fe08ec712f",
        "state": "APPROVED",
        "paymentNetworkResponseCode": "81",
        "paymentNetworkResponseErrorMessage": null,
        "trazabilityCode": "CRED - 666039677",
        "authorizationCode": "123238",
        "pendingReason": null,
        "responseCode": "APPROVED",
        "errorCode": null,
        "responseMessage": "Approved by the merchant",
        "transactionDate": null,
        "transactionTime": null,
        "operationDate": 1624461913704,
        "referenceQuestionnaire": null,
        "extraParameters": {
            "BANK_REFERENCED_CODE": "CREDIT"
        },
        "additionalInfo": {
            "paymentNetwork": "CREDIBANCO",
            "rejectionType": "NONE",
            "responseNetworkMessage": null,
            "travelAgencyAuthorizationCode": null,
            "cardType": "CREDIT",
            "transactionType": "AUTHORIZATION_AND_CAPTURE"
        }
    }
}

Ejemplo de una petición:

<request>
   <language>es</language>
   <command>SUBMIT_TRANSACTION</command>
   <merchant>
      <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
      <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
   </merchant>
   <transaction>
      <order>
         <accountId>512321</accountId>
         <referenceCode>PRODUCT_TEST_2021-06-23T19:59:43.229Z</referenceCode>
         <description>Payment test description</description>
         <language>es</language>
         <signature>1d6c33aed575c4974ad5c0be7c6a1c87</signature>
         <notifyUrl>http://www.payu.com/notify</notifyUrl>
         <additionalValues>
            <entry>
               <string>TX_VALUE</string>
               <additionalValue>
                  <value>65000</value>
                  <currency>COP</currency>
               </additionalValue>
               <string>TX_TAX</string>
               <additionalValue>
                  <value>10378</value>
                  <currency>COP</currency>
               </additionalValue>
               <string>TX_TAX_RETURN_BASE</string>
               <additionalValue>
                  <value>54622</value>
                  <currency>COP</currency>
               </additionalValue>
            </entry>
         </additionalValues>
         <buyer>
            <merchantBuyerId>1</merchantBuyerId>
            <fullName>First name and second buyer name</fullName>
            <emailAddress>buyer_test@test.com</emailAddress>
            <contactPhone>7563126</contactPhone>
            <dniNumber>123456789</dniNumber>
            <shippingAddress>
               <street1>Cr 23 No. 53-50</street1>
               <street2>5555487</street2>
               <city>Bogotá</city>
               <state>Bogotá D.C.</state>
               <country>CO</country>
               <postalCode>000000</postalCode>
               <phone>7563126</phone>
            </shippingAddress>
         </buyer>
         <shippingAddress>
            <street1>Cr 23 No. 53-50</street1>
            <street2>5555487</street2>
            <city>Bogotá</city>
            <state>Bogotá D.C.</state>
            <country>CO</country>
            <postalCode>0000000</postalCode>
            <phone>7563126</phone>
         </shippingAddress>
      </order>
      <payer>
         <merchantPayerId>1</merchantPayerId>
         <fullName>First name and second payer name</fullName>
         <emailAddress>payer_test@test.com</emailAddress>
         <contactPhone>7563126</contactPhone>
         <dniNumber>5415668464654</dniNumber>
         <billingAddress>
            <street1>Cr 23 No. 53-50</street1>
            <street2>5555487</street2>
            <city>Bogotá</city>
            <state>Bogotá D.C.</state>
            <country>CO</country>
            <postalCode>000000</postalCode>
            <phone>7563126</phone>
         </billingAddress>
      </payer>
      <creditCard>
         <number>4037997623271984</number>
         <securityCode>321</securityCode>
         <expirationDate>2030/12</expirationDate>
         <name>APPROVED</name>
      </creditCard>
      <extraParameters>
         <entry>
            <string>INSTALLMENTS_NUMBER</string>
            <string>1</string>
         </entry>
      </extraParameters>
      <type>AUTHORIZATION_AND_CAPTURE</type>
      <paymentMethod>VISA</paymentMethod>
      <paymentCountry>CO</paymentCountry>
      <deviceSessionId>vghs6tvkcle931686k1900o6e1</deviceSessionId>
      <ipAddress>127.0.0.1</ipAddress>
      <cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
      <userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
      <threeDomainSecure>
         <embedded>false</embedded>
         <eci>01</eci>
         <cavv>AOvG5rV058/iAAWhssPUAAADFA==</cavv>
         <xid>Nmp3VFdWMlEwZ05pWGN3SGo4TDA=</xid>
         <directoryServerTransactionId>00000-70000b-5cc9-0000-000000000cb</directoryServerTransactionId>
      </threeDomainSecure>
   </transaction>
   <isTest>false</isTest>
</request>

Ejemplo de una respuesta:

<paymentResponse>
    <code>SUCCESS</code>
    <transactionResponse>
        <orderId>1400449666</orderId>
        <transactionId>c29d0543-810d-48c4-bd3e-163e935c2173</transactionId>
        <state>APPROVED</state>
        <paymentNetworkResponseCode>79</paymentNetworkResponseCode>
        <trazabilityCode>CRED - 666116683</trazabilityCode>
        <authorizationCode>787517</authorizationCode>
        <responseCode>APPROVED</responseCode>
        <responseMessage>Approved administrative transaction</responseMessage>
        <operationDate>2021-06-23T10:26:28</operationDate>
        <extraParameters>
            <entry>
                <string>BANK_REFERENCED_CODE</string>
                <string>CREDIT</string>
            </entry>
        </extraParameters>
        <additionalInfo>
            <paymentNetwork>CREDIBANCO</paymentNetwork>
            <rejectionType>NONE</rejectionType>
            <cardType>CREDIT</cardType>
            <transactionType>AUTHORIZATION_AND_CAPTURE</transactionType>
        </additionalInfo>
    </transactionResponse>
</paymentResponse>

Enviar transacciones utilizando Nequi

Nequi es una plataforma integral de servicios financieros que funciona por medio de una billetera digital disponible para millones de usuarios a través de una aplicación móvil. Con Nequi, puedes realizar pagos, transferencias, recargas y retiros de dinero de manera rápida y segura, todo desde tu dispositivo personal.

Además de ser una herramienta conveniente para usuarios individuales, Nequi también es una solución de pagos innovadora para comercios. Al aceptar pagos con Nequi, tu negocio puede disfrutar de una serie de ventajas significativas:

  • Aumento de las ventas: Al ofrecer Nequi como opción de pago, tu negocio puede atraer a nuevos clientes que prefieren realizar transacciones digitales. Esto puede traducirse en un aumento de las ventas y una mayor fidelización de clientes.

  • Mayor conveniencia: Al permitir que tus clientes paguen con Nequi, estás proporcionando una experiencia de compra más versátil y rápida. Los clientes pueden realizar sus pagos de forma instantánea utilizando sus teléfonos móviles, sin necesidad de efectivo o tarjetas físicas.

  • Mayor seguridad: Nequi ofrece un entorno de pago seguro y confiable, respaldado por Bancolombia, una de las instituciones financieras más grandes y confiables de Colombia. Esto brinda tranquilidad tanto a los comercios como a los clientes, ya que las transacciones se realizan de manera segura y protegida.

Proceso de pago con Nequi

El flujo de pago con Nequi está diseñado para ser sencillo y ágil para el usuario. El proceso incluye 4 pasos:

  1. Selección del Medio de Pago: El cliente, al momento de efectuar la compra, elige Nequi como su medio de pago preferido entre las opciones disponibles.

  2. Generación de Notificación Push: Automáticamente, el sistema genera una notificación push que se envía a la aplicación móvil de Nequi del cliente.

  3. Aceptación de la Notificación: El cliente recibe la notificación en su aplicación Nequi y procede a aceptarla para confirmar la transacción.

  4. Ingreso del PIN de Nequi: Para finalizar la operación, el cliente ingresa su PIN personal de Nequi para autenticar y autorizar el pago.

Experiencia de usuario

En esta sección, te indicamos los elementos necesarios para la óptima experiencia de usuario al utilizar Nequi como método de pago:

  1. Solicita el nombre y correo electrónico del comprador, por ejemplo:

PrintScreen

  1. Presenta el método de pago Nequi y solicita el número de teléfono asociado con la cuenta de Nequi, por ejemplo:

PrintScreen

  1. Muestra un resumen detallado del pago y la cuenta, por ejemplo:

PrintScreen

  1. Destaca los pasos a seguir para facilitar el proceso de pago al comprador, por ejemplo:

PrintScreen

Parámetros para la petición y la respuesta

Petición (Request)
Nombre del Campo Formato Tamaño Descripción Obligatorio
language Alfanumérico 2 Idioma utilizado en la solicitud, este idioma se utiliza para mostrar los mensajes de error generados. Consulta los idiomas admitidos. Sí
command Alfanumérico Máx:32 Asigna SUBMIT_TRANSACTION. Sí
test (JSON)
isTest (XML)		 Booleano Asigna true si la solicitud está en modo de prueba. De lo contrario, asigna false. Sí
merchant Objeto Este objeto contiene los datos de autenticación. Sí
merchant > apiLogin Alfanumérico Min:12 Máx:32 Nombre de usuario o login proporcionado por PayU. Sí
merchant > apiKey Alfanumérico Min:6 Máx:32 Contraseña proporcionada por PayU. Sí
transaction Objeto Este objeto contiene los datos de la transacción. Sí
transaction > order Objeto Este objeto contiene los datos de la orden. Sí
transaction > order > accountId Número Identificador de tu cuenta. Sí
transaction > order > referenceCode Alfanumérico Min:1 Máx:255 Representa el identificador de la orden en tu sistema. Sí
transaction > order > description Alfanumérico Min:1 Máx:255 Descripción de la orden. Sí
transaction > order > language Alfanumérico 2 Idioma utilizado en los correos electrónicos enviados al comprador y al vendedor. Sí
transaction > order > notifyUrl Alfanumérico Máx:2048 URL de confirmación de la orden. No
transaction > order > partnerId Alfanumérico Máx:255 ID de socio en PayU. No
transaction > order > signature Alfanumérico Máx:255 Firma asociada al formulario. Para más información, consulta Firma de autenticación. Sí
transaction > order > shippingAddress Objeto Dirección de envío. No
transaction > order > shippingAddress > street1 Alfanumérico Máx:100 Línea de dirección 1. No
transaction > order > shippingAddress > street2 Alfanumérico Máx:100 Línea de dirección 2. No
transaction > order > shippingAddress > city Alfanumérico Máx:50 Ciudad de la dirección. No
transaction > order > shippingAddress > state Alfanumérico Máx:40 Departamento de la dirección. No
transaction > order > shippingAddress > country Alfanumérico 2 País de la dirección. No
transaction > order > shippingAddress > postalCode Alfanumérico Máx:8 Código postal de la dirección. No
transaction > order > shippingAddress > phone Alfanumérico Máx:11 Número de teléfono asociado con la dirección. No
transaction > order > buyer Objeto Información del comprador. Sí
transaction > order > buyer > merchantBuyerId Alfanumérico Máx:100 ID del comprador en tu sistema. No
transaction > order > buyer > fullName Alfanumérico Máx:150 Nombre completo del comprador. Sí
transaction > order > buyer > emailAddress Alfanumérico Máx:255 Correo electrónico del comprador. Sí
transaction > order > buyer > contactPhone Alfanumérico Máx:20 Número de teléfono del comprador. Sí
transaction > order > buyer > dniNumber Alfanumérico Máx:20 Número de identificación del comprador. Sí
transaction > order > buyer > shippingAddress Objeto Dirección de envío del comprador. Sí
transaction > order > buyer > shippingAddress > street1 Alfanumérico Máx:150 Línea 1 de la dirección de envío del comprador. Sí
transaction > order > buyer > shippingAddress > city Alfanumérico Máx:50 Ciudad de la dirección de envío del comprador. Sí
transaction > order > buyer > shippingAddress > state Alfanumérico Máx:40 Departamento de la dirección de envío del comprador. Sí
transaction > order > buyer > shippingAddress > country Alfanumérico 2 País de la dirección de envío del comprador en formato ISO 3166 alfa-2. Sí
transaction > order > buyer > shippingAddress > postalCode Número Máx:20 Código postal de la dirección de envío del comprador. Sí
transaction > order > buyer > shippingAddress > phone Número Máx:20 Número de teléfono de la dirección de envío del comprador. Sí
transaction > order > additionalValues > Alfanumérico 64 Monto de la orden y sus valores asociados. Sí
transaction > order > additionalValues > TX_VALUE Alfanumérico 64 Monto de la transacción. Sí
transaction > order > additionalValues > TX_VALUE > value Número 12, 2 Especifica el monto de la transacción. Este monto no puede incluir decimales. Sí
transaction > order > additionalValues > TX_VALUE > currency Alfanumérico 3 Código ISO de la moneda. Consulta las monedas aceptadas. No
transaction > order > additionalValues > TX_TAX Alfanumérico 64 Monto del Impuesto al Valor Agregado (IVA). Sí
transaction > order > additionalValues > TX_TAX > value Número 12, 2 Especifica el monto del IVA. Si este parámetro no está configurado, PayU aplica el valor de impuesto actual (19%). Si el monto no tiene IVA, envía 0. Este valor puede tener dos dígitos decimales. No
transaction > order > additionalValues > TX_TAX > currency Alfanumérico 3 Código ISO de la moneda. Consulta las monedas aceptadas. No
transaction > order > additionalValues > TX_TAX_RETURN_BASE Alfanumérico 64 Valor base para calcular el IVA. Si el monto no tiene IVA, envía 0. Este valor puede tener dos dígitos decimales. No
transaction > order > additionalValues > TX_TAX_RETURN_BASE > value Número 12, 2 Especifica el monto base de la transacción. No
transaction > order > additionalValues > TX_TAX_RETURN_BASE > currency Alfanumérico 3 Código ISO de la moneda. Consulta las monedas aceptadas. No
transaction > payer Objeto Información del pagador. Sí
transaction > payer > emailAddress Alfanumérico Máx:255 Correo electrónico del pagador. Sí
transaction > payer > merchantPayerId Alfanumérico Máx:100 Identificador del pagador en tu sistema. No
transaction > payer > fullName Alfanumérico Máx:150 Nombre del pagador. Sí
transaction > payer > billingAddress Objeto Dirección de facturación. Sí
transaction > payer > billingAddress > street1 Alfanumérico Máx:100 Línea 1 de la dirección de facturación. Sí
transaction > payer > billingAddress > street2 Alfanumérico Máx:100 Línea 2 de la dirección de facturación. No
transaction > payer > billingAddress > city Alfanumérico Máx:50 Ciudad de la dirección de facturación. Sí
transaction > payer > billingAddress > state Alfanumérico Máx:40 Departamento de la dirección de facturación. No
transaction > payer > billingAddress > country Alfanumérico 2 País de la dirección de facturación en formato ISO 3166 alfa-2. Sí
transaction > payer > billingAddress > postalCode Alfanumérico Máx:20 Código postal de la dirección de facturación. No
transaction > payer > billingAddress > phone Alfanumérico Máx:20 Número de teléfono de la dirección de facturación. No
transaction > payer > birthdate Alfanumérico Máx:10 Fecha de nacimiento del pagador. No
transaction > payer > contactPhone Alfanumérico Máx:20 Número de teléfono del pagador. Este es el número que se utilizará para pagar en Nequi. Sí
transaction > payer > dniNumber Alfanumérico Máx:20 Número de identificación del comprador. Sí
transaction > payer > dniType Alfanumérico 2 Tipo de identificación del comprador. Consulta los tipos de documentos.. No
transaction > type Alfanumérico 32 Asigna este valor de acuerdo con la transacción. Para Colombia, asigna AUTHORIZATION_AND_CAPTURE. Sí
transaction > paymentMethod Alfanumérico 32 Asigna NEQUI para el Método de Pago Nequi. Sí
transaction > paymentCountry Alfanumérico 2 Asigna CO para Colombia. Sí
transaction > deviceSessionId Alfanumérico Máx:255 Identificador de sesión del dispositivo donde el cliente realiza la transacción. Para más información, consulta este artículo. Sí
transaction > ipAddress Alfanumérico Máx:39 Dirección IP del dispositivo donde el cliente realiza la transacción. Sí
transaction > cookie Alfanumérico Máx:255 Cookie almacenada por el dispositivo donde el cliente realiza la transacción. Sí
transaction > userAgent Alfanumérico Máx:1024 El agente de usuario del navegador donde el cliente realiza la transacción. Sí
Respuesta (Response)
Nombre del campo Formato Tamaño Descripción
code Alfanumérico Código de respuesta de la transacción. Los valores posibles son ERROR y SUCCESS.
error Alfanumérico Máx:2048 Mensaje de error asociado cuando el código de respuesta es ERROR.
transactionResponse Objeto Datos de la respuesta.
transactionResponse > orderId Número Identificador de orden generado o existente en PayU.
transactionResponse > transactionId Alfanumérico 36 Identificador de la transacción en PayU.
transactionResponse > state Alfanumérico Máx:32 Estado de la transacción.
transactionResponse > responseCode Alfanumérico Máx:64 Código de respuesta asociado con el estado.
transactionResponse > pendingReason Alfanumérico Máx:64 Razón pendiente de la transacción.
transactionResponse > paymentNetworkResponseCode Alfanumérico Máx:255 Código de respuesta devuelto por la red financiera.
transactionResponse > paymentNetworkResponseErrorMessage Alfanumérico Máx:255 Mensaje de error devuelto por la red financiera.
transactionResponse > trazabilityCode Alfanumérico Máx:32 Código de trazabilidad devuelto por la red financiera.
transactionResponse > authorizationCode Alfanumérico Máx:12 Código de autorización devuelto por la red financiera.
transactionResponse > responseMessage Alfanumérico Máx:2048 Mensaje asociado con el código de respuesta.
transactionResponse > operationDate Fecha Fecha de creación de la respuesta en el sistema de PayU.
transactionResponse > extraParameters Objeto Parámetros o datos adicionales asociados con la respuesta. En JSON, el parámetro extraParameters sigue esta estructura: "extraParameters": { "BANK_REFERENCED_CODE": "CREDIT"}
En XML, el parámetro extraParameters sigue esta estructura: <extraParameters> <entry>  <string>BANK_REFERENCED_CODE</string>  <string>CREDIT</string> </entry></extraParameters>
transactionResponse > additionalInfo Objeto Información adicional asociada con la respuesta. Este objeto sigue la misma estructura que transactionResponse.extraParameters.

Llamado a la API

Los siguientes son los cuerpos de la petición y la respuesta para este método de pago:


Ejemplo de una petición:

{
   "language": "es",
   "command": "SUBMIT_TRANSACTION",
   "merchant": {
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction": {
      "order": {
         "accountId": "512321",
         "referenceCode": "PRODUCT_TEST_2024-01-18T19:59:43.229Z",
         "description": "Payment test description",
         "language": "es",
         "signature": "1d6c33aed575c4974ad5c0be7c6a1c87",
         "notifyUrl": "http://www.payu.com/notify",
         "additionalValues": {
            "TX_VALUE": {
               "value": 65000,
               "currency": "COP"
            },
            "TX_TAX": {
               "value": 10378,
               "currency": "COP"
            },
            "TX_TAX_RETURN_BASE": {
               "value": 54622,
               "currency": "COP"
            }
         },
         "buyer": {
            "merchantBuyerId": "1",
            "fullName": "First name and second buyer name",
            "emailAddress": "buyer_test@test.com",
            "contactPhone": "57 3007777777",
            "dniNumber": "123456789",
            "shippingAddress": {
               "street1": "Cr 23 No. 53-50",
               "street2": "5555487",
               "city": "Bogotá",
               "state": "Bogotá D.C.",
               "country": "CO",
               "postalCode": "000000",
               "phone": "57 3007777777"
            }
         },
         "shippingAddress": {
            "street1": "Cr 23 No. 53-50",
            "street2": "5555487",
            "city": "Bogotá",
            "state": "Bogotá D.C.",
            "country": "CO",
            "postalCode": "0000000",
            "phone": "7563126"
         }
      },
      "payer": {
         "merchantPayerId": "1",
         "fullName": "First name and second payer name",
         "emailAddress": "payer_test@test.com",
         "contactPhone": "57 3007777777",
         "dniNumber": "5415668464654",
         "billingAddress": {
            "street1": "Cr 23 No. 53-50",
            "street2": "125544",
            "city": "Bogotá",
            "state": "Bogotá D.C.",
            "country": "CO",
            "postalCode": "000000",
            "phone": "57 3007777777"
         }
      },
      "type": "AUTHORIZATION_AND_CAPTURE",
      "paymentMethod": "NEQUI",
      "paymentCountry": "CO",
      "deviceSessionId": "vghs6tvkcle931686k1900o6e1",
      "ipAddress": "127.0.0.1",
      "cookie": "pt1t38347bs6jc9ruv2ecpv7o2",
      "userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0"
   },
   "test": false
}

Ejemplo de una respuesta:

{
    "code": "SUCCESS",
    "error": null,
    "transactionResponse": {
        "orderId": 2151135729,
        "transactionId": "fe667b48-e685-40b3-8863-9a0cd8257860",
        "state": "PENDING",
        "paymentNetworkResponseCode": "0",
        "paymentNetworkResponseErrorMessage": null,
        "trazabilityCode": "3ba38ac9-3d68-48ef-bf86-b6c121404162",
        "authorizationCode": null,
        "pendingReason": "AWAITING_PAYMENT_IN_ENTITY",
        "responseCode": "PENDING_PAYMENT_IN_ENTITY",
        "errorCode": null,
        "responseMessage": "SUCCESS",
        "transactionDate": null,
        "transactionTime": null,
        "operationDate": 1705670262058,
        "referenceQuestionnaire": null,
        "extraParameters": null,
        "additionalInfo": null
    }
}

Ejemplo de una petición:

<request>
  <language>es</language>
  <command>SUBMIT_TRANSACTION</command>
  <merchant>
    <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
    <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
  </merchant>
  <transaction>
    <order>
      <accountId>512321</accountId>
      <referenceCode>PRODUCT_TEST_2024-01-18T19:59:43.229Z</referenceCode>
      <description>Payment test description</description>
      <language>es</language>
      <signature>1d6c33aed575c4974ad5c0be7c6a1c87</signature>
      <notifyUrl>http://www.payu.com/notify</notifyUrl>
      <additionalValues>
        <entry>
          <string>TX_VALUE</string>
          <additionalValue>
            <value>65000</value>
            <currency>COP</currency>
          </additionalValue>
          <string>TX_TAX</string>
          <additionalValue>
            <value>10378</value>
            <currency>COP</currency>
          </additionalValue>
          <string>TX_TAX_RETURN_BASE</string>
          <additionalValue>
            <value>54622</value>
            <currency>COP</currency>
          </additionalValue>
        </entry>
      </additionalValues>
      <buyer>
        <merchantBuyerId>1</merchantBuyerId>
        <fullName>First name and second buyer name</fullName>
        <emailAddress>buyer_test@test.com</emailAddress>
        <contactPhone>57 3007777777</contactPhone>
        <dniNumber>123456789</dniNumber>
        <shippingAddress>
          <street1>Cr 23 No. 53-50</street1>
          <street2>5555487</street2>
          <city>Bogotá</city>
          <state>Bogotá D.C.</state>
          <country>CO</country>
          <postalCode>000000</postalCode>
          <phone>57 3007777777</phone>
        </shippingAddress>
      </buyer>
      <shippingAddress>
        <street1>Cr 23 No. 53-50</street1>
        <street2>5555487</street2>
        <city>Bogot√°</city>
        <state>Bogot√° D.C.</state>
        <country>CO</country>
        <postalCode>0000000</postalCode>
        <phone>7563126</phone>
      </shippingAddress>
    </order>
    <payer>
      <merchantPayerId>1</merchantPayerId>
      <fullName>First name and second payer name</fullName>
      <emailAddress>payer_test@test.com</emailAddress>
      <contactPhone>57 3007777777</contactPhone>
      <dniNumber>5415668464654</dniNumber>
      <billingAddress>
        <street1>Cr 23 No. 53-50</street1>
        <street2>125544</street2>
        <city>Bogotá</city>
        <state>Bogotá D.C.</state>
        <country>CO</country>
        <postalCode>000000</postalCode>
        <phone>57 3007777777</phone>
      </billingAddress>
    </payer>
    <type>AUTHORIZATION_AND_CAPTURE</type>
    <paymentMethod>NEQUI</paymentMethod>
    <paymentCountry>CO</paymentCountry>
    <deviceSessionId>vghs6tvkcle931686k1900o6e1</deviceSessionId>
    <ipAddress>127.0.0.1</ipAddress>
    <cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
    <userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
  </transaction>
  <isTest>false</isTest>
</request>

Ejemplo de una respuesta:

<paymentResponse>
    <code>SUCCESS</code>
    <transactionResponse>
        <orderId>2151135729</orderId>
        <transactionId>fe667b48-e685-40b3-8863-9a0cd8257860</transactionId>
        <state>PENDING</state>
        <paymentNetworkResponseCode>0</paymentNetworkResponseCode>
        <trazabilityCode>3ba38ac9-3d68-48ef-bf86-b6c121404162</trazabilityCode>
        <pendingReason>AWAITING_PAYMENT_IN_ENTITY</pendingReason>
        <responseCode>PENDING_PAYMENT_IN_ENTITY</responseCode>
        <responseMessage>SUCCESS</responseMessage>
        <operationDate>2024-01-19T08:17:42</operationDate>
    </transactionResponse>
</paymentResponse>

Consideraciones

Detalles del número de teléfono

En PayU, nos apasiona simplificar los pagos en línea tanto para nuestros comercios como para sus clientes. Para mejorar la experiencia de pago con Nequi, te sugerimos prestar atención a los siguientes escenarios en los que los pagadores podrían cometer errores al ingresar su número de celular.

En las transacciones enviadas mediante integraciones API que contienen espacios en el número de celular, la transacción se pierde. Esto se debe a que no hay un mecanismo que elimine los espacios por defecto. A continuación, se muestran los resultados que se obtendrían:

  • 57 3007777777 → Aprobada
  • 3007777777 → Aprobada
  • 573007777777 → Error
  • 57 300 7777777 → Error

Recomendaciones

Para prevenir errores causados por espacios en blanco en los números de celular, te recomendamos implementar las siguientes características en la experiencia de usuario:

  1. Implementa una interfaz que automáticamente cree espacios separadores en el número de teléfono móvil mientras el usuario lo ingresa, haciendo que el número sea más fácil de leer y reduciendo la probabilidad de errores de entrada manual. Asegúrate de que estos espacios sean visibles a nivel de la interfaz mientras configuras tu sistema para eliminarlos a nivel de backend.
  • Ejemplo de la interfaz:

PrintScreen

  1. Configura mensajes de error para que se muestren cuando un usuario ingrese un número de teléfono con menos de 10 dígitos o más de 10 dígitos (excluyendo el código de país, que es +57 para Colombia).
  • A) Ejemplo de una interfaz con espacios generados automáticamente donde el usuario no ha ingresado 10 dígitos:

PrintScreen

  • B) Ejemplo de una interfaz sin espacios donde el usuario ha ingresado más de 10 dígitos:

PrintScreen

Pruebas en ambiente Sandbox

Para probar las transacciones de Nequi en el ambiente Sandbox de PayU, utiliza los siguientes datos:

Número de teléfono Comportamiento de la autorización Comportamiento de la consulta
(Aprox. 5 minutos después de la autorización)
3006666666 Transaction rejected - Client not found on database N/A
3007777777 Transaction pending Transaction approved
3007777776 Transaction pending Transaction declined
3007777775 Transaction pending Transaction pending
3007777774 Transaction pending Transaction failed
3007777772 Transaction pending Transaction expired

Puedes consultar el estado de la transacción a través de la API de Consultas.

Enviar transacciones utilizando efectivo o referencia bancaria

Este método te permite procesar los pagos en efectivo o por referencia bancaria de tus clientes. Para integrarte con estas transacciones, debes redirigir a tu cliente a la URL que se encuentra en la respuesta; tu cliente ve un recibo de pago como los siguientes.

Pagos en efectivo

PrintScreen

Pagos con Referencia bancaria

PrintScreen

Parámetros para la petición y la respuesta

Petición (Request)
Nombre del campo Formato Tamaño Descripción Obligatorio
language Alfanumérico 2 Idioma utilizado en la petición, este idioma se utiliza para mostrar los mensajes de error generados. Ver idiomas soportados. Sí
command Alfanumérico Máx:32 Asigna SUBMIT_TRANSACTION. Sí
test (JSON)
isTest (XML)		 Booleano Asigna true si la petición es en modo pruebas. Si no, asigna false. Sí
merchant Este objeto tiene los datos de autenticación. Sí
merchant > apiLogin Alfanumérico Min:12 Máx:32 Usuario o login entregado por PayU. Cómo obtengo mi API Login Sí
merchant > apiKey Alfanumérico Min:6 Máx:32 Contraseña entregada por PayU. Cómo obtengo mi API Key Sí
transaction Este objeto tiene los datos de la transacción. Sí
transaction > order Este objeto tiene los datos de la orden. Sí
transaction > order > accountId Numérico Identificador de tu cuenta. Sí
transaction > order > referenceCode Alfanumérico Min:1 Máx:255 Representa el identificador de la orden en tu sistema. Sí
transaction > order > description Alfanumérico Min:1 Máx:255 Descripción de la orden. Sí
transaction > order > language Alfanumérico 2 Idioma utilizado en los correos electrónicos enviados al comprador y al vendedor. Sí
transaction > order > notifyUrl Alfanumérico Máx:2048 URL de confirmación de la orden. No
transaction > order > partnerId Alfanumérico Máx:255 ID de aliado dentro de PayUID de aliado dentro de PayU. No
transaction > order > signature Alfanumérico Máx:255 Firma asociada al formulario. Para más información, consulta Firma de autenticación. Sí
transaction > order > shippingAddress Objeto Dirección de envío. No
transaction > order > shippingAddress > street1 Alfanumérico Máx:100 Línea de dirección 1. No
transaction > order > shippingAddress > street2 Alfanumérico Máx:100 Línea de dirección 2. No
transaction > order > shippingAddress > city Alfanumérico Máx:50 Ciudad de la dirección. No
transaction > order > shippingAddress > state Alfanumérico Máx:40 Departamento de la dirección. No
transaction > order > shippingAddress > country Alfanumérico 2 País de la dirección. No
transaction > order > shippingAddress > postalCode Alfanumérico Máx:8 Código postal de la dirección. No
transaction > order > shippingAddress > phone Alfanumérico Máx:11 Número de teléfono asociado con la dirección. No
transaction > order > buyer Información del comprador. Sí
transaction > order > buyer > merchantBuyerId Alfanumérico Máx:100 Identificador del comprador en tu sistema. No
transaction > order > buyer > fullName Alfanumérico Máx:150 Nombre del comprador. Sí
transaction > order > buyer > emailAddress Alfanumérico Máx:255 Correo electrónico del comprador. Sí
transaction > order > buyer > contactPhone Alfanumérico Máx:20 Número de teléfono del comprador. Sí
transaction > order > buyer > dniNumber Alfanumérico Máx:20 Número de identificación del comprador. Sí
transaction > order > buyer > shippingAddress Objeto Dirección de envío del comprador. Sí
transaction > order > buyer > shippingAddress > street1 Alfanumérico Máx:150 Línea de dirección 1 del comprador. Sí
transaction > order > buyer > shippingAddress > city Alfanumérico Máx:50 Ciudad de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > state Alfanumérico Máx:40 Departamento de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > country Alfanumérico 2 País de la dirección del comprador en formato ISO 3166 alpha-2. Sí
transaction > order > buyer > shippingAddress > postalCode Numérico Máx:20 Código postal de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > phone Numérico Máx:20 Número de teléfono de la dirección del comprador. Sí
transaction > order > additionalValues > 64 Monto de la orden y sus valores asociados. Sí
transaction > order > additionalValues > TX_VALUE Alfanumérico 64 Monto de la transacción. Sí
transaction > order > additionalValues > TX_VALUE > value Numérico 12, 2 Especifica el monto de la transacción, este valor no puede tener decimales. Sí
transaction > order > additionalValues > TX_VALUE > currency Alfanumérico 3 Código ISO de la moneda. Ver monedas aceptadas. Sí
transaction > order > additionalValues > TX_TAX Alfanumérico 64 Monto del IVA (Impuesto al Valor Agregado). Sí
transaction > order > additionalValues > TX_TAX > value Numérico 12, 2 Especifica el monto del IVA.
Si no se envía este parámetro, PayU aplica el impuesto actual (19%).
Si la cantidad está exenta de IVA, envía 0.
Este valor puede tener dos dígitos decimales.		 No
transaction > order > additionalValues > TX_TAX > currency Alfanumérico 3 Código ISO de la moneda. Ver monedas aceptadas. No
transaction > order > additionalValues > TX_TAX_RETURN_BASE Alfanumérico 64 Valor base para calcular el IVA.
Si la cantidad está exenta de IVA, envía 0.
Este valor puede tener dos dígitos decimales		 No
transaction > order > additionalValues > TX_TAX_RETURN_BASE > value Numérico 12, 2 Especifica el valor base de la transacción. No
transaction > order > additionalValues > TX_TAX_RETURN_BASE > currency Alfanumérico 3 Código ISO de la moneda. Ver monedas aceptadas. No
transaction > payer Información del pagador. Sí
transaction > payer > emailAddress Alfanumérico Máx:255 Correo electrónico del pagador. Sí
transaction > payer > merchantPayerId Alfanumérico Máx:100 Identificador del pagador en tu sistema. No
transaction > payer > fullName Alfanumérico Máx:150 Nombre del pagador. Sí
transaction > payer > billingAddress Dirección de facturación. Sí
transaction > payer > billingAddress > street1 Alfanumérico Máx:100 Línea 1 de la dirección de facturación. Sí
transaction > payer > billingAddress > street2 Alfanumérico Máx:100 Línea 2 de la dirección de facturación. No
transaction > payer > billingAddress > city Alfanumérico Máx:50 Ciudad de la dirección de facturación. Sí
transaction > payer > billingAddress > state Alfanumérico Máx:40 Departamento de la dirección de facturación. Sí
transaction > payer > billingAddress > country Alfanumérico 2 País de la dirección de facturación en formato ISO 3166 Alpha-2. Sí
transaction > payer > billingAddress > postalCode Alfanumérico Máx:20 Código postal de la dirección de facturación. No
transaction > payer > billingAddress > phone Alfanumérico Máx:20 Número de teléfono de la dirección de facturación. No
transaction > payer > birthdate Alfanumérico Máx:10 Fecha de nacimiento del pagador. No
transaction > payer > contactPhone Alfanumérico Máx:20 Número de teléfono del pagador. Sí
transaction > payer > dniNumber Alfanumérico Máx:20 Número de identificación del pagador. Sí
transaction > payer > dniType Alfanumérico 2 Tipo de identificación del pagador. Ver tipos de documentos. No
transaction > type Alfanumérico 32 Como los pagos en efectivo se realizan en oficinas físicas, la única transacción disponible es AUTHORIZATION_AND_CAPTURE Sí
transaction > paymentMethod Alfanumérico 32 Seleccione un método de pago en efectivo o de referencia bancaria válido. Ver los métodos de pago disponibles para Colombia. Sí
transaction > paymentCountry Alfanumérico 2 Asigna CO para Colombia. Sí
transaction > expirationDate Alfanumérico 23 Fecha y hora máxima en la que el cliente puede realizar el pago. Formato YYYY-MM-DDTHH:MM:SS, por ejemplo 2021-06-12T16:07:11.586. No
transaction > ipAddress Alfanumérico Máx:39 Dirección IP del dispositivo donde el cliente realiza la transacción. Sí
Respuesta (Response)
Nombre del campo Formato Tamaño Descripción
code Alfanumérico Código de respuesta de la transacción. Los valores posibles son ERROR y SUCCESS.
error Alfanumérico Máx:2048 Mensaje de error asociado cuando el código de respuesta es ERROR.
transactionResponse Datos de la respuesta.
transactionResponse > orderId Numérico Identificador generado o existente de la orden en PayU.
transactionResponse > transactionId Alfanumérico 36 Identificador de la transacción en PayU.
transactionResponse > state Alfanumérico Máx:32 Estado de la transacción. Como el pago se realiza de forma externa, el estado de una transacción exitosa es PENDING
transactionResponse > paymentNetworkResponseCode Alfanumérico Máx:255 Código de respuesta retornado por la red bancaria.
transactionResponse > paymentNetworkResponseErrorMessage Alfanumérico Máx:255 Mensaje de error retornado por la red bancaria.
transactionResponse > trazabilityCode Alfanumérico Máx:32 Código de trazabilidad retornado por la red bancaria.
transactionResponse > authorizationCode Alfanumérico Máx:12 Código de autorización retornado por la red bancaria.
transactionResponse > pendingReason Alfanumérico Máx:21 Código de la razón asociada con el estado, como se mencionó en transactionResponse > state, la transacción está en espera del pago.
transactionResponse > responseCode Alfanumérico Máx:64 Código de respuesta asociado con el estado. En este caso, para una transacción exitosa es PENDING_TRANSACTION_CONFIRMATION.
transactionResponse > responseMessage Alfanumérico Máx:2048 Mensaje asociado con el código de respuesta.
transactionResponse > operationDate Fecha Fecha de creación de la respuesta en el sistema de PayU.
transactionResponse > extraParameters Parámetros adicionales o datos asociados con la respuesta.
En JSON, el parámetro extraParameters sigue esta estructura:
"extraParameters": {
 "REFERENCE": "74794"
}

En XML, el parámetro extraParameters sigue esta estructura:
<extraParameters>
 <entry>
  <string>REFERENCE</string>
  <int>74794</int>
 </entry>
</extraParameters>
transactionResponse > additionalInfo Información adicional de la respuesta. Este objeto tiene la misma estructura de transactionResponse.extraParameters.

Consideraciones

  • El parámetro transaction.expirationDate no es obligatorio. Si no envías este parámetro, su valor por defecto es siete (7) días luego de la fecha actual.
    Si envías una fecha posterior a dicho número de días, PayU ignorará este valor y asignará el valor por defecto.
  • Para EFECTY, la confirmación del pago tarda 15 minutos. Para BANK_REFERENCED y OTHERS_CASH (Su Red), la confirmación es en línea.
  • Los valores mínimos de máximos para pagos en EFECTY y OTHERS_CASH (Su Red) son:
    • EFECTY > Min: $20.000 COP - Máx: $6.000.000 COP
    • OTHERS_CASH (Su Red) > Min: $1.000 COP - Máx: $4.000.000 COP
  • El parámetro transactionResponse.extraParameters tiene los siguientes parámetros relacionados con la transacción:
    • EXPIRATION_DATE: fecha máxima en la que el pagador puede realizar el pago.
    • REFERENCE: referencia de pago interna generada por PayU.
    • URL_PAYMENT_RECEIPT_HTML: recibo de pago en formato HTML. Aquí es donde debe redirigir el pago cuando el pagador selecciona un método de pago en efectivo.
    • URL_PAYMENT_RECEIPT_PDF: recibo de pago en formato PDF.
    • BANCO_BOGOTA_SERVICE_CODE: código de pago para Banco de Bogotá. Disponible cuando utilices BANK_REFERENCED.
    • BANK_REFERENCED_NAME: nombre de la referencia para Bancolombia. Disponible cuando utilices BANK_REFERENCED.
    • BANCOLOMBIA_SERVICE_CODE: código de pago para Bancolombia. Disponible cuando utilices BANK_REFERENCED.

Llamado a la API

Los siguientes son los cuerpos de la petición y la respuesta para este método de pago.


Ejemplo de una petición:

{
   "language": "es",
   "command": "SUBMIT_TRANSACTION",
   "merchant": {
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction": {
      "order": {
         "accountId": "512321",
         "referenceCode": "PRODUCT_TEST_2021-06-23T19:59:43.229Z",
         "description": "Payment test description",
         "language": "es",
         "signature": "1d6c33aed575c4974ad5c0be7c6a1c87",
         "notifyUrl": "http://www.payu.com/notify",
         "additionalValues": {
            "TX_VALUE": {
               "value": 65000,
               "currency": "COP"
         },
            "TX_TAX": {
               "value": 10378,
               "currency": "COP"
         },
            "TX_TAX_RETURN_BASE": {
               "value": 54622,
               "currency": "COP"
         }
         },
         "buyer": {
            "merchantBuyerId": "1",
            "fullName": "First name and second buyer name",
            "emailAddress": "buyer_test@test.com",
            "contactPhone": "7563126",
            "dniNumber": "123456789",
            "shippingAddress": {
               "street1": "Cr 23 No. 53-50",
               "street2": "5555487",
               "city": "Bogotá",
               "state": "Bogotá D.C.",
               "country": "CO",
               "postalCode": "000000",
               "phone": "7563126"
            }
         },
         "shippingAddress": {
            "street1": "Cr 23 No. 53-50",
            "street2": "5555487",
            "city": "Bogotá",
            "state": "Bogotá D.C.",
            "country": "CO",
            "postalCode": "0000000",
            "phone": "7563126"
         }
      },
      "payer": {
         "merchantPayerId": "1",
         "fullName": "First name and second payer name",
         "emailAddress": "payer_test@test.com",
         "contactPhone": "7563126",
         "dniNumber": "5415668464654",
         "billingAddress": {
            "street1": "Cr 23 No. 53-50",
            "street2": "125544",
            "city": "Bogotá",
            "state": "Bogotá D.C.",
            "country": "CO",
            "postalCode": "000000",
            "phone": "7563126"
         }
      },
      "type": "AUTHORIZATION_AND_CAPTURE",
      "paymentMethod": "EFECTY",
      "expirationDate": "2021-06-24T20:58:35.804",
      "paymentCountry": "CO",
      "ipAddress": "127.0.0.1"
   },
   "test": false
}

Ejemplo de una respuesta:

{
    "code": "SUCCESS",
    "error": null,
    "transactionResponse": {
        "orderId": 1400449740,
        "transactionId": "f3531b6a-3e30-4a8b-8a69-d4a5bd2a3377",
        "state": "PENDING",
        "paymentNetworkResponseCode": null,
        "paymentNetworkResponseErrorMessage": null,
        "trazabilityCode": "f3531b6a-3e30-4a8b-8a69-d4a5bd2a3377",
        "authorizationCode": null,
        "pendingReason": "AWAITING_NOTIFICATION",
        "responseCode": "PENDING_TRANSACTION_CONFIRMATION",
        "errorCode": null,
        "responseMessage": null,
        "transactionDate": null,
        "transactionTime": null,
        "operationDate": 1624463917065,
        "referenceQuestionnaire": null,
        "extraParameters": {
            "EXPIRATION_DATE": 1624568315804,
            "REFERENCE": 1400449740,
            "URL_PAYMENT_RECEIPT_PDF": "https://sandbox.checkout.payulatam.com/ppp-web-gateway-payu/receipt?vid=1400449740Yf3531b6a3e304a8Y30f3f7b4598eb19",
            "URL_PAYMENT_RECEIPT_HTML": "https://sandbox.checkout.payulatam.com/ppp-web-gateway-payu/app/v2?vid=1400449740Yf3531b6a3e304a8Y30f3f7b4598eb19"
        },
        "additionalInfo": {
            "paymentNetwork": "EFECTY",
            "rejectionType": "NONE",
            "responseNetworkMessage": null,
            "travelAgencyAuthorizationCode": null,
            "cardType": null,
            "transactionType": "AUTHORIZATION_AND_CAPTURE"
        }
    }
}

Ejemplo de una petición:

<request>
   <language>es</language>
   <command>SUBMIT_TRANSACTION</command>
   <merchant>
      <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
      <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
   </merchant>
   <transaction>
      <order>
         <accountId>512321</accountId>
         <referenceCode>PRODUCT_TEST_2021-06-23T19:59:43.229Z</referenceCode>
         <description>Payment test description</description>
         <language>es</language>
         <signature>1d6c33aed575c4974ad5c0be7c6a1c87</signature>
         <notifyUrl>http://www.payu.com/notify</notifyUrl>
         <additionalValues>
            <entry>
               <string>TX_VALUE</string>
               <additionalValue>
                  <value>65000</value>
                  <currency>COP</currency>
               </additionalValue>
               <string>TX_TAX</string>
               <additionalValue>
                  <value>10378</value>
                  <currency>COP</currency>
               </additionalValue>
               <string>TX_TAX_RETURN_BASE</string>
               <additionalValue>
                  <value>54622</value>
                  <currency>COP</currency>
               </additionalValue>
            </entry>
         </additionalValues>
         <buyer>
            <merchantBuyerId>1</merchantBuyerId>
            <fullName>First name and second buyer name</fullName>
            <emailAddress>buyer_test@test.com</emailAddress>
            <contactPhone>7563126</contactPhone>
            <dniNumber>123456789</dniNumber>
            <shippingAddress>
               <street1>Cr 23 No. 53-50</street1>
               <street2>5555487</street2>
               <city>Bogotá</city>
               <state>Bogotá D.C.</state>
               <country>CO</country>
               <postalCode>000000</postalCode>
               <phone>7563126</phone>
            </shippingAddress>
         </buyer>
         <shippingAddress>
            <street1>Cr 23 No. 53-50</street1>
            <street2>5555487</street2>
            <city>Bogotá</city>
            <state>Bogotá D.C.</state>
            <country>CO</country>
            <postalCode>0000000</postalCode>
            <phone>7563126</phone>
         </shippingAddress>
      </order>
      <payer>
         <merchantPayerId>1</merchantPayerId>
         <fullName>First name and second payer name</fullName>
         <emailAddress>payer_test@test.com</emailAddress>
         <contactPhone>7563126</contactPhone>
         <dniNumber>5415668464654</dniNumber>
         <billingAddress>
            <street1>Cr 23 No. 53-50</street1>
            <street2>5555487</street2>
            <city>Bogotá</city>
            <state>Bogotá D.C.</state>
            <country>CO</country>
            <postalCode>000000</postalCode>
            <phone>7563126</phone>
         </billingAddress>
      </payer>
      <type>AUTHORIZATION_AND_CAPTURE</type>
      <paymentMethod>EFECTY</paymentMethod>
      <expirationDate>2021-06-24T20:58:35.804</expirationDate>
      <paymentCountry>CO</paymentCountry>
      <ipAddress>127.0.0.1</ipAddress>
   </transaction>
   <isTest>false</isTest>
</request>

Ejemplo de una respuesta:

<paymentResponse>
    <code>SUCCESS</code>
    <transactionResponse>
        <orderId>1400449797</orderId>
        <transactionId>0b41f4d0-4486-4acf-ab5e-d757e35d994d</transactionId>
        <state>PENDING</state>
        <trazabilityCode>0b41f4d0-4486-4acf-ab5e-d757e35d994d</trazabilityCode>
        <pendingReason>AWAITING_NOTIFICATION</pendingReason>
        <responseCode>PENDING_TRANSACTION_CONFIRMATION</responseCode>
        <operationDate>2021-06-23T11:20:03</operationDate>
        <extraParameters>
            <entry>
                <string>EXPIRATION_DATE</string>
                <date>2021-06-30T23:59:59</date>
            </entry>
            <entry>
                <string>REFERENCE</string>
                <int>1400449797</int>
            </entry>
            <entry>
                <string>URL_PAYMENT_RECEIPT_PDF</string>
                <string>https://sandbox.checkout.payulatam.com/ppp-web-gateway-payu/receipt?vid=1400449797Y0b41f4d044864acY3e5f14fc8ef00e8</string>
            </entry>
            <entry>
                <string>URL_PAYMENT_RECEIPT_HTML</string>
                <string>https://sandbox.checkout.payulatam.com/ppp-web-gateway-payu/app/v2?vid=1400449797Y0b41f4d044864acY3e5f14fc8ef00e8</string>
            </entry>
        </extraParameters>
        <additionalInfo>
            <paymentNetwork>EFECTY</paymentNetwork>
            <rejectionType>NONE</rejectionType>
            <transactionType>AUTHORIZATION_AND_CAPTURE</transactionType>
        </additionalInfo>
    </transactionResponse>
</paymentResponse>

Enviar transacciones utilizando transferencia bancaria (PSE)

Este método te permite procesar los pagos realizados por tus clientes por medio de transferencia bancaria. En Colombia, las transferencias bancarias se hacen a través de PSE, para integrarte con este método de pago, necesitas crear un formulario de pago siguiendo estos pasos:

  1. Incluye un botón PSE button haciendo evidente que tu cliente va a utilizar Proveedor de Servicios Electrónicos PSE.
  • Puedes utilizar los siguientes nombres:
    • Débito desde cuenta corriente/ahorros
    • Debito bancario PSE
    • PSE
  • No utilices ninguno de los siguientes nombres
    • Transferencia bancaria
    • Débito de cuenta
    • Tarjeta débito

  1. Consulta la lista de bancos disponibles para mostrarla al pagador. Para consultar la lista de bancos, consulta este método.
    Debes actualizar la lista de bancos en tu sistema por lo menos una vez al día.

  2. Muestra la lista de bancos tal y como se muestra a continuación:

PrintScreen

Cuando el pagador seleccione un banco, debes enviar al parámetro pseCode seleccionado en el extra parámetro FINANCIAL_INSTITUTION_CODE de la petición.

  1. Muestra una lista para que el pagador escoja si es una persona Natural (N) o Jurídica (J). Dependiendo de lo que escoja, debes enviar el valor en el extra parámetro USER_TYPE de la petición. La lista debe verse así:

PrintScreen

  1. Muestra una lista para que el pagador escoja su tipo de identificación. Debes enviar el código ISO del valor seleccionado en el extra parámetro PSE_REFERENCE2 de la petición. La lista debe verse así:

PrintScreen

La lista de documentos disponibles es:

ISO Descripción
CC Cédula de ciudadanía.
CE Cédula de extranjería.
NIT Número de Identificación Tributaria (Empresas).
TI Tarjeta de identidad.
PP Pasaporte.
RC Registro civil de nacimiento.
DE Documento de identificación extranjero.
  1. Debes enviar el número de identificación del pagador en el extra parámetro PSE_REFERENCE3 de la petición.

Parámetros para la petición y la respuesta

Petición (Request)
Nombre del campo Formato Tamaño Descripción Obligatorio
language Alfanumérico 2 Idioma utilizado en la petición, este idioma se utiliza para mostrar los mensajes de error generados. Ver idiomas soportados. Sí
command Alfanumérico Máx:32 Asigna SUBMIT_TRANSACTION. Sí
test (JSON)
isTest (XML)		 Booleano Asigna true si la petición es en modo pruebas. Si no, asigna false. Sí
merchant Este objeto tiene los datos de autenticación. Sí
merchant > apiLogin Alfanumérico Min:12 Máx:32 Usuario o login entregado por PayU. Cómo obtengo mi API Login Sí
merchant > apiKey Alfanumérico Min:6 Máx:32 Contraseña entregada por PayU. Cómo obtengo mi API Key Sí
transaction Este objeto tiene los datos de la transacción. Sí
transaction > order Este objeto tiene los datos de la orden. Sí
transaction > order > accountId Numérico Identificador de tu cuenta. Sí
transaction > order > referenceCode Alfanumérico Min:1 Máx:255 Representa el identificador de la orden en tu sistema. Sí
transaction > order > description Alfanumérico Min:1 Máx:255 Descripción de la orden. Sí
transaction > order > language Alfanumérico 2 Idioma utilizado en los correos electrónicos enviados al comprador y al vendedor. Sí
transaction > order > notifyUrl Alfanumérico Máx:2048 URL de confirmación de la orden. No
transaction > order > partnerId Alfanumérico Máx:255 ID de aliado dentro de PayUID de aliado dentro de PayU. No
transaction > order > signature Alfanumérico Máx:255 Firma asociada al formulario. Para más información, consulta Firma de autenticación. Sí
transaction > order > shippingAddress Objeto Dirección de envío. No
transaction > order > shippingAddress > street1 Alfanumérico Máx:100 Línea de dirección 1. No
transaction > order > shippingAddress > street2 Alfanumérico Máx:100 Línea de dirección 2. No
transaction > order > shippingAddress > city Alfanumérico Máx:50 Ciudad de la dirección. No
transaction > order > shippingAddress > state Alfanumérico Máx:40 Departamento de la dirección. No
transaction > order > shippingAddress > country Alfanumérico 2 País de la dirección. No
transaction > order > shippingAddress > postalCode Alfanumérico Máx:8 Código postal de la dirección. No
transaction > order > shippingAddress > phone Alfanumérico Máx:11 Número de teléfono asociado con la dirección. No
transaction > order > buyer Información del comprador. Sí
transaction > order > buyer > merchantBuyerId Alfanumérico Máx:100 Identificador del comprador en tu sistema. No
transaction > order > buyer > fullName Alfanumérico Máx:150 Nombre del comprador. Sí
transaction > order > buyer > emailAddress Alfanumérico Máx:255 Correo electrónico del comprador. Sí
transaction > order > buyer > contactPhone Alfanumérico Máx:20 Número de teléfono del comprador. Sí
transaction > order > buyer > dniNumber Alfanumérico Máx:20 Número de identificación del comprador. Sí
transaction > order > buyer > shippingAddress Objeto Dirección de envío del comprador. Sí
transaction > order > buyer > shippingAddress > street1 Alfanumérico Máx:150 Línea de dirección 1 del comprador. Sí
transaction > order > buyer > shippingAddress > city Alfanumérico Máx:50 Ciudad de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > state Alfanumérico Máx:40 Departamento de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > country Alfanumérico 2 País de la dirección del comprador en formato ISO 3166 alpha-2. Sí
transaction > order > buyer > shippingAddress > postalCode Numérico Máx:20 Código postal de la dirección del comprador. Sí
transaction > order > buyer > shippingAddress > phone Numérico Máx:20 Número de teléfono de la dirección del comprador. Sí
transaction > order > additionalValues > 64 Monto de la orden y sus valores asociados. Sí
transaction > order > additionalValues > TX_VALUE Alfanumérico 64 Monto de la transacción. Sí
transaction > order > additionalValues > TX_VALUE > value Numérico 12, 2 Especifica el monto de la transacción, este valor no puede tener decimales. Sí
transaction > order > additionalValues > TX_VALUE > currency Alfanumérico 3 Código ISO de la moneda. Ver monedas aceptadas. Sí
transaction > payer Información del pagador. Sí
transaction > payer > emailAddress Alfanumérico Máx:255 Correo electrónico del pagador. Sí
transaction > payer > merchantPayerId Alfanumérico Máx:100 Identificador del pagador en tu sistema. No
transaction > payer > fullName Alfanumérico Máx:150 Nombre del pagador. Sí
transaction > payer > billingAddress Dirección de facturación. Sí
transaction > payer > billingAddress > street1 Alfanumérico Máx:100 Línea 1 de la dirección de facturación. Sí
transaction > payer > billingAddress > street2 Alfanumérico Máx:100 Línea 2 de la dirección de facturación. No
transaction > payer > billingAddress > city Alfanumérico Máx:50 Ciudad de la dirección de facturación. Sí
transaction > payer > billingAddress > state Alfanumérico Máx:40 Departamento de la dirección de facturación. No
transaction > payer > billingAddress > country Alfanumérico 2 País de la dirección de facturación en formato ISO 3166 Alpha-2. Sí
transaction > payer > billingAddress > postalCode Alfanumérico Máx:20 Código postal de la dirección de facturación. No
transaction > payer > billingAddress > phone Alfanumérico Máx:20 Número de teléfono de la dirección de facturación. No
transaction > payer > birthdate Alfanumérico Máx:10 Fecha de nacimiento del pagador. No
transaction > payer > contactPhone Alfanumérico Máx:20 Número de teléfono del pagador. Sí
transaction > payer > dniNumber Alfanumérico Máx:20 Número de identificación del pagador. Sí
transaction > payer > dniType Alfanumérico 2 Tipo de identificación del pagador. Ver tipos de documentos. Sí
transaction > type Alfanumérico 32 Como estos pagos se realizan en la página web de PSE, la única transacción disponible es AUTHORIZATION_AND_CAPTURE Sí
transaction > paymentMethod Alfanumérico 32 Selecciona un método de pago por transferencia bancaria válido. Ver los métodos de pago disponibles para Colombia. Sí
transaction > paymentCountry Alfanumérico 2 Asigna CO para Colombia. Sí
transaction > deviceSessionId Alfanumérico Máx:255 Identificador de la sesión del dispositivo donde el cliente realiza la transacción. Para más información, consulta este artículo. Sí
transaction > ipAddress Alfanumérico Máx:39 Dirección IP del dispositivo donde el cliente realiza la transacción. Sí
transaction > cookie Alfanumérico Máx:255 Cookie almacenada por el dispositivo donde el cliente realiza la transacción. Sí
transaction > userAgent Alfanumérico Máx:1024 User agent del navegador donde el cliente realiza la transacción. Sí
transaction > extraParameters Parámetros adicionales o datos asociados a la petición.
Para pagos por transferencia bancaria, esta es la página de respuesta de tu comercio.
En JSON, el parámetro extraParameters se asigna como:
"extraParameters": {
 "PSE_REFERENCE3": "123456789"
}

En XML, el parámetro extraParameters se asigna como:
<extraParameters>
 <entry>
  <string>PSE_REFERENCE3</string>
  <string>123456789</string>
 </entry>
</extraParameters>		 No
Respuesta (Response)
Nombre del campo Formato Tamaño Descripción
code Alfanumérico Código de respuesta de la transacción. Los valores posibles son ERROR y SUCCESS.
error Alfanumérico Máx:2048 Mensaje de error asociado cuando el código de respuesta es ERROR.
transactionResponse Datos de la respuesta.
transactionResponse > orderId Numérico Identificador generado o existente de la orden en PayU.
transactionResponse > transactionId Alfanumérico 36 Identificador de la transacción en PayU.
transactionResponse > state Alfanumérico Máx:32 Estado de la transacción. Como el pago se realiza de forma externa, el estado de una transacción exitosa es PENDING
transactionResponse > paymentNetworkResponseCode Alfanumérico Máx:255 Código de respuesta retornado por la red bancaria.
transactionResponse > paymentNetworkResponseErrorMessage Alfanumérico Máx:255 Mensaje de error retornado por la red bancaria.
transactionResponse > trazabilityCode Alfanumérico Máx:32 Código de trazabilidad retornado por la red bancaria.
transactionResponse > authorizationCode Alfanumérico Máx:12 Código de autorización retornado por la red bancaria.
transactionResponse > pendingReason Alfanumérico Máx:21 Código de la razón asociada con el estado, como se mencionó en transactionResponse > state, la transacción está en espera del pago.
transactionResponse > responseCode Alfanumérico Máx:64 Código de respuesta asociado con el estado. En este caso, para una transacción exitosa es PENDING_TRANSACTION_CONFIRMATION.
transactionResponse > responseMessage Alfanumérico Máx:2048 Mensaje asociado con el código de respuesta.
transactionResponse > operationDate Fecha Fecha de creación de la respuesta en el sistema de PayU.
transactionResponse > extraParameters Parámetros adicionales o datos asociados con la respuesta.
En JSON, el parámetro extraParameters sigue esta estructura:
"extraParameters": {
 "BANK_URL": "xxxx"
}

En XML, el parámetro extraParameters sigue esta estructura:
<extraParameters>
 <entry>
  <string>BANK_URL</string>
  <string>xxxx</string>
 </entry>
</extraParameters>

Consideraciones

  • Para probar las transferencias bancarias PSE en el ambiente de Sandbox de PayU, consulta la Guía de pruebas de PSE (PDF).
  • Todos los valores de pago deben estar formateados en miles sin excepción (p.ej., 1,200.00 o 1,200).
  • Si la solicitud de pago es exitosa, el estado de la transacción es pendiente (PENDING) y el responseCode es PENDING_TRANSACTION_CONFIRMATION; esto es debido a que el pagador es redirigido al naco seleccionado para completar el pago; debes redirigir al pagador a la URL retornada en el extra parámetro BANK_URL.
  • La URL retornada en el extra parámetro BANK_URL se configura en el Modulo PayU y debe mostrar la siguiente información:

    PrintScreen
    Los parámetros que empiezan con el símbolo $ se envían vía GET.
  • Una vez el cliente hace clic en el botón de pago, debe desactivarse para evitar enviar una nueva solicitud sobre el mismo pago.
  • No muestres la página del banco en contenedores (frames, panel, iframes, etc). El proceso de pago debe ser fluido. Además, evita abrir la página del banco en una nueva pestaña o en una nueva ventana del navegador. Si necesitas utilizar una nueva pestaña o ventana, bloquea la página de origen para evitar enviar una nueva solicitud sobre el mismo pago.
  • Debes agregar a la página de respuesta las opciones para reintentar el pago, finalizar la transacción e imprimir el recibo.
  • Los estados mostrados en la página de respuesta pueden ser los siguientes:
polTransactionState polResponseCode Estado
4 1 Transacción aprobada
6 5 Transacción fallida
6 4 Transacción rechazada
12 o 14 9994 o 25 Transacción pendiente, por favor revisar si el débito fue realizado en el banco.

Llamado a la API

Los siguientes son los cuerpos de la petición y la respuesta para este método de pago.


Ejemplo de una petición:

{
   "language": "es",
   "command": "SUBMIT_TRANSACTION",
   "merchant": {
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction": {
      "order": {
         "accountId": "512321",
         "referenceCode": "PRODUCT_TEST_2021-06-23T19:59:43.229Z",
         "description": "Payment test description",
         "language": "es",
         "signature": "1d6c33aed575c4974ad5c0be7c6a1c87",
         "notifyUrl": "http://www.payu.com/notify",
         "additionalValues": {
            "TX_VALUE": {
               "value": 65000,
               "currency": "COP"
         },
            "TX_TAX": {
               "value": 10378,
               "currency": "COP"
         },
            "TX_TAX_RETURN_BASE": {
               "value": 54622,
               "currency": "COP"
         }
         },
         "buyer": {
            "merchantBuyerId": "1",
            "fullName": "First name and second buyer name",
            "emailAddress": "buyer_test@test.com",
            "contactPhone": "7563126",
            "dniNumber": "123456789",
            "shippingAddress": {
               "street1": "Cr 23 No. 53-50",
               "street2": "5555487",
               "city": "Bogotá",
               "state": "Bogotá D.C.",
               "country": "CO",
               "postalCode": "000000",
               "phone": "7563126"
            }
         },
         "shippingAddress": {
            "street1": "Cr 23 No. 53-50",
            "street2": "5555487",
            "city": "Bogotá",
            "state": "Bogotá D.C.",
            "country": "CO",
            "postalCode": "0000000",
            "phone": "7563126"
         }
      },
      "payer": {
         "merchantPayerId": "1",
         "fullName": "First name and second payer name",
         "emailAddress": "payer_test@test.com",
         "contactPhone": "7563126",
         "dniNumber": "5415668464654",
         "billingAddress": {
            "street1": "Cr 23 No. 53-50",
            "street2": "125544",
            "city": "Bogotá",
            "state": "Bogotá D.C.",
            "country": "CO",
            "postalCode": "000000",
            "phone": "7563126"
         }
      },
      "extraParameters": {
         "RESPONSE_URL": "http://www.payu.com/response",
         "PSE_REFERENCE1": "127.0.0.1",
         "FINANCIAL_INSTITUTION_CODE": "1022",
         "USER_TYPE": "N",
         "PSE_REFERENCE2": "CC",
         "PSE_REFERENCE3": "123456789"
      },
      "type": "AUTHORIZATION_AND_CAPTURE",
      "paymentMethod": "PSE",
      "paymentCountry": "CO",
      "deviceSessionId": "vghs6tvkcle931686k1900o6e1",
      "ipAddress": "127.0.0.1",
      "cookie": "pt1t38347bs6jc9ruv2ecpv7o2",
      "userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0"
   },
   "test": false
}

Ejemplo de una respuesta:

{
    "code": "SUCCESS",
    "error": null,
    "transactionResponse": {
        "orderId": 1400449959,
        "transactionId": "4d49e544-e23f-474e-92b1-59357e0e85e8",
        "state": "PENDING",
        "paymentNetworkResponseCode": null,
        "paymentNetworkResponseErrorMessage": null,
        "trazabilityCode": "2204682",
        "authorizationCode": null,
        "pendingReason": "AWAITING_NOTIFICATION",
        "responseCode": "PENDING_TRANSACTION_CONFIRMATION",
        "errorCode": null,
        "responseMessage": null,
        "transactionDate": null,
        "transactionTime": null,
        "operationDate": 1624471332753,
        "referenceQuestionnaire": null,
        "extraParameters": {
            "TRANSACTION_CYCLE": "1",
            "BANK_URL": "https://sandbox.api.payulatam.com/payments-api/pse-caller?enc=aHR0cHM6Ly9yZWdpc3Ryby5kZXNhcnJvbGxvLnBzZS5jb20uY28vUFNFVXNlclJlZ2lzdGVyL1N0YXJ0VHJhbnNhY3Rpb24uYXNweD9lbmM9dG5QY0pITUtsU25tUnBITThmQWJ1NHVWTmt6YW92Q0tWR2g0b0IxbEpkOXNEeGlSU2E5cXl1Uk5TUW5mbkxSdiMjcGF5ZXJfdGVzdEB0ZXN0LmNvbSMjMTIzNDU2Nzg5IyNDQw=="
        },
        "additionalInfo": {
            "paymentNetwork": "PSE",
            "rejectionType": "NONE",
            "responseNetworkMessage": null,
            "travelAgencyAuthorizationCode": null,
            "cardType": null,
            "transactionType": "AUTHORIZATION_AND_CAPTURE"
        }
    }
}

Ejemplo de una petición:

<request>
   <language>es</language>
   <command>SUBMIT_TRANSACTION</command>
   <merchant>
      <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
      <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
   </merchant>
   <transaction>
      <order>
         <accountId>512321</accountId>
         <referenceCode>PRODUCT_TEST_2021-06-23T19:59:43.229Z</referenceCode>
         <description>Payment test description</description>
         <language>es</language>
         <signature>1d6c33aed575c4974ad5c0be7c6a1c87</signature>
         <notifyUrl>http://www.payu.com/notify</notifyUrl>
         <additionalValues>
            <entry>
               <string>TX_VALUE</string>
               <additionalValue>
                  <value>65000</value>
                  <currency>COP</currency>
               </additionalValue>
               <string>TX_TAX</string>
               <additionalValue>
                  <value>10378</value>
                  <currency>COP</currency>
               </additionalValue>
               <string>TX_TAX_RETURN_BASE</string>
               <additionalValue>
                  <value>54622</value>
                  <currency>COP</currency>
               </additionalValue>
            </entry>
         </additionalValues>
         <buyer>
            <merchantBuyerId>1</merchantBuyerId>
            <fullName>First name and second buyer name</fullName>
            <emailAddress>buyer_test@test.com</emailAddress>
            <contactPhone>7563126</contactPhone>
            <dniNumber>123456789</dniNumber>
            <shippingAddress>
               <street1>Cr 23 No. 53-50</street1>
               <street2>5555487</street2>
               <city>Bogotá</city>
               <state>Bogotá D.C.</state>
               <country>CO</country>
               <postalCode>000000</postalCode>
               <phone>7563126</phone>
            </shippingAddress>
         </buyer>
         <shippingAddress>
            <street1>Cr 23 No. 53-50</street1>
            <street2>5555487</street2>
            <city>Bogotá</city>
            <state>Bogotá D.C.</state>
            <country>CO</country>
            <postalCode>0000000</postalCode>
            <phone>7563126</phone>
         </shippingAddress>
      </order>
      <payer>
         <merchantPayerId>1</merchantPayerId>
         <fullName>First name and second payer name</fullName>
         <emailAddress>payer_test@test.com</emailAddress>
         <contactPhone>7563126</contactPhone>
         <dniNumber>5415668464654</dniNumber>
         <billingAddress>
            <street1>Cr 23 No. 53-50</street1>
            <street2>5555487</street2>
            <city>Bogotá</city>
            <state>Bogotá D.C.</state>
            <country>CO</country>
            <postalCode>000000</postalCode>
            <phone>7563126</phone>
         </billingAddress>
      </payer>
      <extraParameters>
         <entry>
            <string>RESPONSE_URL</string>
            <string>http://www.payu.com/response</string>
         </entry>
         <entry>
            <string>PSE_REFERENCE1</string>
            <string>127.0.0.1</string>
         </entry>
         <entry>
            <string>FINANCIAL_INSTITUTION_CODE</string>
            <string>1022</string>
         </entry>
         <entry>
            <string>USER_TYPE</string>
            <string>N</string>
         </entry>
         <entry>
            <string>PSE_REFERENCE2</string>
            <string>CC</string>
         </entry>
         <entry>
            <string>PSE_REFERENCE3</string>
            <string>123456789</string>
         </entry>
      </extraParameters>
      <type>AUTHORIZATION_AND_CAPTURE</type>
      <paymentMethod>PSE</paymentMethod>
      <paymentCountry>CO</paymentCountry>
      <deviceSessionId>vghs6tvkcle931686k1900o6e1</deviceSessionId>
      <ipAddress>127.0.0.1</ipAddress>
      <cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
      <userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
   </transaction>
   <isTest>false</isTest>
</request>

Ejemplo de una respuesta:

<paymentResponse>
    <code>SUCCESS</code>
    <transactionResponse>
        <orderId>1400449974</orderId>
        <transactionId>6c99b11b-fe6f-4270-8c9a-dfc35b7c7e34</transactionId>
        <state>PENDING</state>
        <trazabilityCode>2204695</trazabilityCode>
        <pendingReason>AWAITING_NOTIFICATION</pendingReason>
        <responseCode>PENDING_TRANSACTION_CONFIRMATION</responseCode>
        <operationDate>2021-06-23T13:12:14</operationDate>
        <extraParameters>
            <entry>
                <string>TRANSACTION_CYCLE</string>
                <string>1</string>
            </entry>
            <entry>
                <string>BANK_URL</string>
                <string>https://sandbox.api.payulatam.com/payments-api/pse-caller?enc=aHR0cHM6Ly9yZWdpc3Ryby5kZXNhcnJvbGxvLnBzZS5jb20uY28vUFNFVXNlclJlZ2lzdGVyL1N0YXJ0VHJhbnNhY3Rpb24uYXNweD9lbmM9dG5QY0pITUtsU25tUnBITThmQWJ1NHVWTmt6YW92Q0tWR2g0b0IxbEpkJTJmSGhQT0oyU2t4UnRmOEdLTk5tcGNYIyNwYXllcl90ZXN0QHRlc3QuY29tIyMxMjM0NTY3ODkjI0ND</string>
            </entry>
        </extraParameters>
        <additionalInfo>
            <paymentNetwork>PSE</paymentNetwork>
            <rejectionType>NONE</rejectionType>
            <transactionType>AUTHORIZATION_AND_CAPTURE</transactionType>
        </additionalInfo>
    </transactionResponse>
</paymentResponse>

Lista de Bancos - PSE

Este método retorna la lista de bancos disponibles para realizar pagos utilizando PSE.

Parámetros para la petición y la respuesta

Petición (Request)
Nombre del campo Formato Tamaño Descripción Obligatorio
language Alfanumérico 2 Idioma utilizado en la petición, este idioma se utiliza para mostrar los mensajes de error generados. Ver idiomas soportados. Sí
command Alfanumérico Máx:32 Asigna GET_BANKS_LIST. Sí
test (JSON)
isTest (XML)		 Booleano Asigna true si la petición es en modo pruebas. Si no, asigna false. Sí
merchant Este objeto tiene los datos de autenticación. Sí
merchant > apiLogin Alfanumérico Min:12 Máx:32 Usuario o login entregado por PayU. Cómo obtengo mi API Login Sí
merchant > apiKey Alfanumérico Min:6 Máx:32 Contraseña entregada por PayU. Cómo obtengo mi API Key Sí
bankListInformation Este objeto tiene la información de la consulta. Sí
bankListInformation > paymentMethod Alfanumérico Asigna PSE. Sí
bankListInformation > paymentCountry Alfanumérico Asigna CO. Sí
Respuesta (Response)
Nombre del campo Formato Tamaño Descripción
code Alfanumérico Código de respuesta de la transacción. Los valores posibles son ERROR y SUCCESS.
error Alfanumérico Máx:2048 Mensaje de error asociado cuando el código de respuesta es ERROR.
banks Lista de bancos disponibles en PSE.
banks > id Numérico Identificador interno del banco.
banks > description Alfanumérico Nombre del banco para ser mostrado en la lista.
banks > pseCode Alfanumérico Código para enviar en el extra parámetro FINANCIAL_INSTITUTION_CODE de la solicitud de pago.

Llamado a la API

Los siguientes son los cuerpos de la petición y la respuesta para este método.


Ejemplo de una petición:

{
   "language": "es",
   "command": "GET_BANKS_LIST",
   "merchant": {
      "apiLogin": "pRRXKOl8ikMmt9u",
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA"
   },
   "test": false,
   "bankListInformation": {
      "paymentMethod": "PSE",
      "paymentCountry": "CO"
   }
}

Ejemplo de una respuesta:

{
    "code": "SUCCESS",
    "error": null,
    "banks": [
        {
            "id": "34e6e912-a395-4d31-9599-9baa176c1a61",
            "description": "A continuación seleccione su banco",
            "pseCode": "0"
        },
        {
            "id": "033aec11-e068-4252-8043-237144be9233",
            "description": "BAN.CO",
            "pseCode": "1552"
        },
        {
            "id": "a720cb4c-6549-4932-83be-6d72b3eb0016",
            "description": "BANCAMIA",
            "pseCode": "1059"
        },
        {
            "id": "d9280852-47a5-4e99-94ac-3d7648ba79a3",
            "description": "BANCO AGRARIO",
            "pseCode": "1040"
        },
        {
            "id": "ff216e8a-28ba-4bf6-9935-b94dfdfd96a0",
            "description": "BANCO AGRARIO DESARROLLO",
            "pseCode": "1081"
        },
        {
            "id": "5073154e-efd4-4870-9315-abb926e87519",
            "description": "BANCO AGRARIO QA DEFECTOS",
            "pseCode": "1080"
        },
        {
            "id": "6e61a91d-58bf-46ec-aa09-1f44974dda7e",
            "description": "BANCO CAJA SOCIAL",
            "pseCode": "10322"
        },
        {
            "id": "e062711e-6bbd-4a13-819a-d60084f9c6fa",
            "description": "BANCO CAJA SOCIAL DESARROLLO",
            "pseCode": "1032"
        },
        {
            "id": "a9b5cc17-b0ae-4708-9835-586a0bef95df",
            "description": "BANCO COMERCIAL AVVILLAS S.A.",
            "pseCode": "1052"
        },
        {
            "id": "c5c97dfe-6101-453f-bcd4-691f4b329a3c",
            "description": "BANCO COOMEVA S.A. - BANCOOMEVA",
            "pseCode": "1061"
        },
        {
            "id": "7a2e8d04-e8c8-404b-8e49-d5d37c107a12",
            "description": "BANCO COOPERATIVO COOPCENTRAL",
            "pseCode": "1066"
        },
        {
            "id": "197fe0af-f658-4fe0-ad1b-952e174de549",
            "description": "BANCO CREDIFINANCIERA",
            "pseCode": "1058"
        },
        {
            "id": "b1de44f1-cede-4aca-9d3f-3313d5cc0c63",
            "description": "BANCO DAVIVIENDA",
            "pseCode": "1051"
        },
        {
            "id": "7a10219e-04a7-4c31-b747-54ded27c7f07",
            "description": "BANCO DAVIVIENDA Desarrollo",
            "pseCode": "10512"
        },
        {
            "id": "ed06f40e-a1b9-4e48-8851-bffb4cda0480",
            "description": "BANCO DE BOGOTA",
            "pseCode": "1039"
        },
        {
            "id": "4592a13b-6334-4fba-8402-9d006b599fa8",
            "description": "BANCO DE BOGOTA DESARROLLO 2013",
            "pseCode": "1001"
        },
        {
            "id": "55f59084-cd3b-47d2-a420-6442cdb9e4b1",
            "description": "BANCO DE OCCIDENTE",
            "pseCode": "1023"
        },
        {
            "id": "8e134fca-4fde-44e6-b012-55e8f2d338ca",
            "description": "BANCO FALABELLA",
            "pseCode": "1062"
        },
        {
            "id": "8eb03abf-5608-419b-8d2c-9d90b8ab6b88",
            "description": "BANCO GNB COLOMBIA (ANTES HSBC)",
            "pseCode": "1010"
        },
        {
            "id": "283e0068-749f-43f1-a2e5-340910f41af3",
            "description": "BANCO GNB SUDAMERIS",
            "pseCode": "1012"
        },
        {
            "id": "8b0bf5e7-394d-4f7e-a467-e4d21d04c9fb",
            "description": "BANCO PICHINCHA S.A.",
            "pseCode": "1060"
        },
        {
            "id": "beeb494a-4ce5-41b4-b497-0756f0b6a6d9",
            "description": "BANCO POPULAR",
            "pseCode": "1002"
        },
        {
            "id": "a5a4b740-1644-4627-ae2a-41b13ffc7c5e",
            "description": "BANCO PRODUCTOS POR SEPARADO",
            "pseCode": "1203"
        },
        {
            "id": "47e747ef-c817-4be6-9eff-b6b16f50d001",
            "description": "Banco PSE",
            "pseCode": "1101"
        },
        {
            "id": "589939d7-06d1-4933-a101-8bb29b801d76",
            "description": "BANCO SANTANDER COLOMBIA",
            "pseCode": "1065"
        },
        {
            "id": "fcdaa98e-99ce-4e76-a504-1e053a05e773",
            "description": "BANCO SERFINANZA",
            "pseCode": "1069"
        },
        {
            "id": "201608c6-81de-436f-967a-2ec7c212c100",
            "description": "BANCO TEQUENDAMA",
            "pseCode": "1035"
        },
        {
            "id": "a8f33ba3-0053-464a-afbe-9add7c63fbc3",
            "description": "Banco union Colombia Credito",
            "pseCode": "1004"
        },
        {
            "id": "5dfa1b2c-64bd-4e8c-9fad-585337cfd4ff",
            "description": "BANCO UNION COLOMBIANO",
            "pseCode": "1022"
        },
        {
            "id": "56e306ef-6011-4f41-9640-b98449d6a6be",
            "description": "BANCO UNION COLOMBIANO FD2",
            "pseCode": "1005"
        },
        {
            "id": "bc883c0d-3610-4a88-96ca-2e2baa1dd2e5",
            "description": "Banco Web Service ACH",
            "pseCode": "1055"
        },
        {
            "id": "4e97e580-fc92-47ea-af4f-7b3b3ddffff8",
            "description": "Banco Web Service ACH WSE 3.0",
            "pseCode": "1055"
        },
        {
            "id": "931f6bfb-283e-4721-bb86-4a7484bfd28e",
            "description": "BANCOLOMBIA DATAPOWER",
            "pseCode": "10072"
        },
        {
            "id": "1285de9c-8d47-49f7-b00a-e87882e2a3f9",
            "description": "BANCOLOMBIA DESARROLLO",
            "pseCode": "10071"
        },
        {
            "id": "451f0e5f-5db4-4f55-a1fc-b38e06526e04",
            "description": "BANCOLOMBIA QA",
            "pseCode": "1007"
        },
        {
            "id": "448e00ec-c479-497d-9a35-0dfbbf462f72",
            "description": "BANKA",
            "pseCode": "1077"
        },
        {
            "id": "5f3a7adb-b283-4ca3-bee9-741f1306a03d",
            "description": "BBVA COLOMBIA S.A.",
            "pseCode": "1013"
        },
        {
            "id": "cd4286fa-850a-4b34-96d1-f71d6a79f44a",
            "description": "BBVA DESARROLLO",
            "pseCode": "1513"
        },
        {
            "id": "10e9b7b6-7a5f-4d5b-8d7f-4b2020f43f93",
            "description": "CITIBANK COLOMBIA S.A.",
            "pseCode": "1009"
        },
        {
            "id": "77f0988f-cf45-4931-bbcd-984e07e0fc51",
            "description": "COLTEFINANCIERA",
            "pseCode": "1370"
        },
        {
            "id": "48c81f6a-e0f1-4c1d-ab9b-9915726e3596",
            "description": "CONFIAR COOPERATIVA FINANCIERA",
            "pseCode": "1292"
        },
        {
            "id": "8694df26-5ccd-45c0-b5b7-2b995c47f81a",
            "description": "COOPERATIVA FINANCIERA COTRAFA",
            "pseCode": "1289"
        },
        {
            "id": "1c222feb-2b58-408c-a495-ade06b6825c0",
            "description": "COOPERATIVA FINANCIERA DE ANTIOQUIA",
            "pseCode": "1283"
        },
        {
            "id": "70a18a09-38f2-4f62-aba6-9ad28c30c966",
            "description": "CREDIFIANCIERA",
            "pseCode": "1558"
        },
        {
            "id": "3f8b3126-8aa3-4438-8a6c-1d544184f2d7",
            "description": "DALE",
            "pseCode": "1097"
        },
        {
            "id": "a953078b-5e22-42ea-9301-954558e8f463",
            "description": "DAVIPLATA",
            "pseCode": "1551"
        },
        {
            "id": "2ad780ba-a1e8-4cb9-9150-670429aae092",
            "description": "GIROS Y FINANZAS COMPAÑIA DE FINANCIAMIENTO S.A",
            "pseCode": "1303"
        },
        {
            "id": "c0bfb716-a098-40f6-84b5-1972a4846506",
            "description": "IRIS",
            "pseCode": "1637"
        },
        {
            "id": "7e1efd88-4f88-4e21-a972-28b526b27da5",
            "description": "ITAU",
            "pseCode": "1006"
        },
        {
            "id": "26c9a2df-6b4f-4309-9137-3692d9bb9f82",
            "description": "MOVII S.A",
            "pseCode": "1801"
        },
        {
            "id": "d9b48a70-6068-4116-a345-154381e5d953",
            "description": "NEQUI CERTIFICACION",
            "pseCode": "1508"
        },
        {
            "id": "60199dc5-7d38-49c6-92a5-b839dc0087d2",
            "description": "prueba restriccion",
            "pseCode": "9988"
        },
        {
            "id": "be467299-d90a-407e-86d3-01e30ade1e06",
            "description": "Prueba Steve",
            "pseCode": "121212"
        },
        {
            "id": "201acc05-4c4f-49dc-9be6-3261a6ce4a3c",
            "description": "RAPPIPAY",
            "pseCode": "1151"
        },
        {
            "id": "7602e001-6199-48bc-9ee3-466f8eb2e422",
            "description": "SCOTIABANK COLPATRIA DESARROLLO",
            "pseCode": "1019"
        },
        {
            "id": "9bb638a0-4c3f-41d2-8811-f8cdd29b0db2",
            "description": "SCOTIABANK COLPATRIA UAT",
            "pseCode": "1078"
        },
        {
            "id": "086547b5-313b-42c7-acef-93d0f76b1dd5",
            "description": "SEIVY – GM FINANCIAL",
            "pseCode": "1305"
        }
    ]
}

Ejemplo de una petición:

<request>
    <language>en</language>
    <command>GET_BANKS_LIST</command>
    <merchant>
        apiLogin>pRRXKOl8ikMmt9u</apiLogin>
        <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
    </merchant>
    <isTest>false</isTest>
    <bankListInformation>
        <paymentMethod>PSE</paymentMethod>
        <paymentCountry>CO</paymentCountry>
    </bankListInformation>
</request>

Ejemplo de una respuesta:

<bankListResponse>
    <code>SUCCESS</code>
    <banks>
        <bank>
            <id>34e6e912-a395-4d31-9599-9baa176c1a61</id>
            <description>A continuación seleccione su banco</description>
            <pseCode>0</pseCode>
        </bank>
        <bank>
            <id>033aec11-e068-4252-8043-237144be9233</id>
            <description>BAN.CO</description>
            <pseCode>1552</pseCode>
        </bank>
        <bank>
            <id>a720cb4c-6549-4932-83be-6d72b3eb0016</id>
            <description>BANCAMIA</description>
            <pseCode>1059</pseCode>
        </bank>
        <bank>
            <id>d9280852-47a5-4e99-94ac-3d7648ba79a3</id>
            <description>BANCO AGRARIO</description>
            <pseCode>1040</pseCode>
        </bank>
        <bank>
            <id>ff216e8a-28ba-4bf6-9935-b94dfdfd96a0</id>
            <description>BANCO AGRARIO DESARROLLO</description>
            <pseCode>1081</pseCode>
        </bank>
        <bank>
            <id>5073154e-efd4-4870-9315-abb926e87519</id>
            <description>BANCO AGRARIO QA DEFECTOS</description>
            <pseCode>1080</pseCode>
        </bank>
        <bank>
            <id>6e61a91d-58bf-46ec-aa09-1f44974dda7e</id>
            <description>BANCO CAJA SOCIAL</description>
            <pseCode>10322</pseCode>
        </bank>
        <bank>
            <id>e062711e-6bbd-4a13-819a-d60084f9c6fa</id>
            <description>BANCO CAJA SOCIAL DESARROLLO</description>
            <pseCode>1032</pseCode>
        </bank>
        <bank>
            <id>a9b5cc17-b0ae-4708-9835-586a0bef95df</id>
            <description>BANCO COMERCIAL AVVILLAS S.A.</description>
            <pseCode>1052</pseCode>
        </bank>
        <bank>
            <id>c5c97dfe-6101-453f-bcd4-691f4b329a3c</id>
            <description>BANCO COOMEVA S.A. - BANCOOMEVA</description>
            <pseCode>1061</pseCode>
        </bank>
        <bank>
            <id>7a2e8d04-e8c8-404b-8e49-d5d37c107a12</id>
            <description>BANCO COOPERATIVO COOPCENTRAL</description>
            <pseCode>1066</pseCode>
        </bank>
        <bank>
            <id>197fe0af-f658-4fe0-ad1b-952e174de549</id>
            <description>BANCO CREDIFINANCIERA</description>
            <pseCode>1058</pseCode>
        </bank>
        <bank>
            <id>b1de44f1-cede-4aca-9d3f-3313d5cc0c63</id>
            <description>BANCO DAVIVIENDA</description>
            <pseCode>1051</pseCode>
        </bank>
        <bank>
            <id>7a10219e-04a7-4c31-b747-54ded27c7f07</id>
            <description>BANCO DAVIVIENDA Desarrollo</description>
            <pseCode>10512</pseCode>
        </bank>
        <bank>
            <id>ed06f40e-a1b9-4e48-8851-bffb4cda0480</id>
            <description>BANCO DE BOGOTA</description>
            <pseCode>1039</pseCode>
        </bank>
        <bank>
            <id>4592a13b-6334-4fba-8402-9d006b599fa8</id>
            <description>BANCO DE BOGOTA DESARROLLO 2013</description>
            <pseCode>1001</pseCode>
        </bank>
        <bank>
            <id>55f59084-cd3b-47d2-a420-6442cdb9e4b1</id>
            <description>BANCO DE OCCIDENTE</description>
            <pseCode>1023</pseCode>
        </bank>
        <bank>
            <id>8e134fca-4fde-44e6-b012-55e8f2d338ca</id>
            <description>BANCO FALABELLA</description>
            <pseCode>1062</pseCode>
        </bank>
        <bank>
            <id>8eb03abf-5608-419b-8d2c-9d90b8ab6b88</id>
            <description>BANCO GNB COLOMBIA (ANTES HSBC)</description>
            <pseCode>1010</pseCode>
        </bank>
        <bank>
            <id>283e0068-749f-43f1-a2e5-340910f41af3</id>
            <description>BANCO GNB SUDAMERIS</description>
            <pseCode>1012</pseCode>
        </bank>
        <bank>
            <id>8b0bf5e7-394d-4f7e-a467-e4d21d04c9fb</id>
            <description>BANCO PICHINCHA S.A.</description>
            <pseCode>1060</pseCode>
        </bank>
        <bank>
            <id>beeb494a-4ce5-41b4-b497-0756f0b6a6d9</id>
            <description>BANCO POPULAR</description>
            <pseCode>1002</pseCode>
        </bank>
        <bank>
            <id>a5a4b740-1644-4627-ae2a-41b13ffc7c5e</id>
            <description>BANCO PRODUCTOS POR SEPARADO</description>
            <pseCode>1203</pseCode>
        </bank>
        <bank>
            <id>47e747ef-c817-4be6-9eff-b6b16f50d001</id>
            <description>Banco PSE</description>
            <pseCode>1101</pseCode>
        </bank>
        <bank>
            <id>589939d7-06d1-4933-a101-8bb29b801d76</id>
            <description>BANCO SANTANDER COLOMBIA</description>
            <pseCode>1065</pseCode>
        </bank>
        <bank>
            <id>fcdaa98e-99ce-4e76-a504-1e053a05e773</id>
            <description>BANCO SERFINANZA</description>
            <pseCode>1069</pseCode>
        </bank>
        <bank>
            <id>201608c6-81de-436f-967a-2ec7c212c100</id>
            <description>BANCO TEQUENDAMA</description>
            <pseCode>1035</pseCode>
        </bank>
        <bank>
            <id>a8f33ba3-0053-464a-afbe-9add7c63fbc3</id>
            <description>Banco union Colombia Credito</description>
            <pseCode>1004</pseCode>
        </bank>
        <bank>
            <id>5dfa1b2c-64bd-4e8c-9fad-585337cfd4ff</id>
            <description>BANCO UNION COLOMBIANO</description>
            <pseCode>1022</pseCode>
        </bank>
        <bank>
            <id>56e306ef-6011-4f41-9640-b98449d6a6be</id>
            <description>BANCO UNION COLOMBIANO FD2</description>
            <pseCode>1005</pseCode>
        </bank>
        <bank>
            <id>bc883c0d-3610-4a88-96ca-2e2baa1dd2e5</id>
            <description>Banco Web Service ACH</description>
            <pseCode>1055</pseCode>
        </bank>
        <bank>
            <id>4e97e580-fc92-47ea-af4f-7b3b3ddffff8</id>
            <description>Banco Web Service ACH WSE 3.0</description>
            <pseCode>1055</pseCode>
        </bank>
        <bank>
            <id>931f6bfb-283e-4721-bb86-4a7484bfd28e</id>
            <description>BANCOLOMBIA DATAPOWER</description>
            <pseCode>10072</pseCode>
        </bank>
        <bank>
            <id>1285de9c-8d47-49f7-b00a-e87882e2a3f9</id>
            <description>BANCOLOMBIA DESARROLLO</description>
            <pseCode>10071</pseCode>
        </bank>
        <bank>
            <id>451f0e5f-5db4-4f55-a1fc-b38e06526e04</id>
            <description>BANCOLOMBIA QA</description>
            <pseCode>1007</pseCode>
        </bank>
        <bank>
            <id>448e00ec-c479-497d-9a35-0dfbbf462f72</id>
            <description>BANKA</description>
            <pseCode>1077</pseCode>
        </bank>
        <bank>
            <id>5f3a7adb-b283-4ca3-bee9-741f1306a03d</id>
            <description>BBVA COLOMBIA S.A.</description>
            <pseCode>1013</pseCode>
        </bank>
        <bank>
            <id>cd4286fa-850a-4b34-96d1-f71d6a79f44a</id>
            <description>BBVA DESARROLLO</description>
            <pseCode>1513</pseCode>
        </bank>
        <bank>
            <id>10e9b7b6-7a5f-4d5b-8d7f-4b2020f43f93</id>
            <description>CITIBANK COLOMBIA S.A.</description>
            <pseCode>1009</pseCode>
        </bank>
        <bank>
            <id>77f0988f-cf45-4931-bbcd-984e07e0fc51</id>
            <description>COLTEFINANCIERA</description>
            <pseCode>1370</pseCode>
        </bank>
        <bank>
            <id>48c81f6a-e0f1-4c1d-ab9b-9915726e3596</id>
            <description>CONFIAR COOPERATIVA FINANCIERA</description>
            <pseCode>1292</pseCode>
        </bank>
        <bank>
            <id>8694df26-5ccd-45c0-b5b7-2b995c47f81a</id>
            <description>COOPERATIVA FINANCIERA COTRAFA</description>
            <pseCode>1289</pseCode>
        </bank>
        <bank>
            <id>1c222feb-2b58-408c-a495-ade06b6825c0</id>
            <description>COOPERATIVA FINANCIERA DE ANTIOQUIA</description>
            <pseCode>1283</pseCode>
        </bank>
        <bank>
            <id>70a18a09-38f2-4f62-aba6-9ad28c30c966</id>
            <description>CREDIFIANCIERA</description>
            <pseCode>1558</pseCode>
        </bank>
        <bank>
            <id>3f8b3126-8aa3-4438-8a6c-1d544184f2d7</id>
            <description>DALE</description>
            <pseCode>1097</pseCode>
        </bank>
        <bank>
            <id>a953078b-5e22-42ea-9301-954558e8f463</id>
            <description>DAVIPLATA</description>
            <pseCode>1551</pseCode>
        </bank>
        <bank>
            <id>2ad780ba-a1e8-4cb9-9150-670429aae092</id>
            <description>GIROS Y FINANZAS COMPAÑIA DE FINANCIAMIENTO S.A</description>
            <pseCode>1303</pseCode>
        </bank>
        <bank>
            <id>c0bfb716-a098-40f6-84b5-1972a4846506</id>
            <description>IRIS</description>
            <pseCode>1637</pseCode>
        </bank>
        <bank>
            <id>7e1efd88-4f88-4e21-a972-28b526b27da5</id>
            <description>ITAU</description>
            <pseCode>1006</pseCode>
        </bank>
        <bank>
            <id>26c9a2df-6b4f-4309-9137-3692d9bb9f82</id>
            <description>MOVII S.A</description>
            <pseCode>1801</pseCode>
        </bank>
        <bank>
            <id>d9b48a70-6068-4116-a345-154381e5d953</id>
            <description>NEQUI CERTIFICACION</description>
            <pseCode>1508</pseCode>
        </bank>
        <bank>
            <id>60199dc5-7d38-49c6-92a5-b839dc0087d2</id>
            <description>prueba restriccion</description>
            <pseCode>9988</pseCode>
        </bank>
        <bank>
            <id>be467299-d90a-407e-86d3-01e30ade1e06</id>
            <description>Prueba Steve</description>
            <pseCode>121212</pseCode>
        </bank>
        <bank>
            <id>201acc05-4c4f-49dc-9be6-3261a6ce4a3c</id>
            <description>RAPPIPAY</description>
            <pseCode>1151</pseCode>
        </bank>
        <bank>
            <id>7602e001-6199-48bc-9ee3-466f8eb2e422</id>
            <description>SCOTIABANK COLPATRIA DESARROLLO</description>
            <pseCode>1019</pseCode>
        </bank>
        <bank>
            <id>9bb638a0-4c3f-41d2-8811-f8cdd29b0db2</id>
            <description>SCOTIABANK COLPATRIA UAT</description>
            <pseCode>1078</pseCode>
        </bank>
        <bank>
            <id>086547b5-313b-42c7-acef-93d0f76b1dd5</id>
            <description>SEIVY – GM FINANCIAL</description>
            <pseCode>1305</pseCode>
        </bank>
    </banks>
</bankListResponse>

Consultar métodos de pago disponibles

Este método retorna la lista de los métodos de pago disponibles en todos los paises.

Parámetros para la petición y la respuesta

Petición (Request)
Nombre del campo Formato Tamaño Descripción Obligatorio
language Alfanumérico 2 Idioma utilizado en la petición, este idioma se utiliza para mostrar los mensajes de error generados. Ver idiomas soportados. Sí
command Alfanumérico Máx:32 Asigna GET_PAYMENT_METHODS. Sí
test (JSON)
isTest (XML)		 Booleano Asigna true si la petición es en modo pruebas. Si no, asigna false. Sí
merchant Este objeto tiene los datos de autenticación. Sí
merchant > apiLogin Alfanumérico Min:12 Máx:32 Usuario o login entregado por PayU. Cómo obtengo mi API Login Sí
merchant > apiKey Alfanumérico Min:6 Máx:32 Contraseña entregada por PayU. Cómo obtengo mi API Key Sí
Respuesta (Response)
Nombre del campo Formato Tamaño Descripción
code Alfanumérico Código de respuesta de la transacción. Los valores posibles son ERROR y SUCCESS.
error Alfanumérico Máx:2048 Mensaje de error asociado cuando el código de respuesta es ERROR.
paymentMethods Lista de métodos de pago.
paymentMethods > paymentMethodComplete Este objeto tiene la información de un método de pago.
paymentMethods > paymentMethodComplete > id Numérico Identificador del método de pago.
paymentMethods > paymentMethodComplete > description Alfanumérico Máx:32 Nombre del método de pago.
paymentMethods > paymentMethodComplete > country Alfanumérico 2 Código ISO del país del método de pago.

Llamado a la API

Los siguientes son los cuerpos de la petición y la respuesta para este método. Para el propósito de este ejemplo, la respuesta muestra dos métodos de pago.


Ejemplo de una petición:

{
   "test": false,
   "language": "en",
   "command": "GET_PAYMENT_METHODS",
   "merchant": {
      "apiLogin": "pRRXKOl8ikMmt9u",
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA"
   }
}

Ejemplo de una respuesta:

{
    "code": "SUCCESS",
    "error": null,
    "paymentMethods": [
        {
            "id": "36",
            "description": "EFECTY",
            "country": "CO",
            "enabled": true,
            "reason": null
        },
        {
            "id": "10",
            "description": "MASTERCARD",
            "country": "co",
            "enabled": true,
            "reason": null
        }
    ]
}

Ejemplo de una petición:

<request>
   <language>en</language>
   <command>GET_PAYMENT_METHODS</command>
   <merchant>
      <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
      <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
   </merchant>
   <isTest>false</isTest>
</request>

Ejemplo de una respuesta:

<paymentMethodsResponse>
    <code>SUCCESS</code>
    <paymentMethods>
        <paymentMethodComplete>
            <id>36</id>
            <description>EFECTY</description>
            <country>CO</country>
            <enabled>true</enabled>
        </paymentMethodComplete>
        <paymentMethodComplete>
            <id>10</id>
            <description>MASTERCARD</description>
            <country>CO</country>
            <enabled>true</enabled>
        </paymentMethodComplete>
    </paymentMethods>
</paymentMethodsResponse>

Ping

El método PING te permite verificar la conexión con nuestra plataforma.

Parámetros para la petición y la respuesta

Petición (Request)
Nombre del campo Formato Tamaño Descripción Obligatorio
language Alfanumérico 2 Idioma utilizado en la petición, este idioma se utiliza para mostrar los mensajes de error generados. Ver idiomas soportados. Sí
command Alfanumérico Máx:32 Asigna PING. Sí
test (JSON)
isTest (XML)		 Booleano Asigna true si la petición es en modo pruebas. Si no, asigna false. Sí
merchant Este objeto tiene los datos de autenticación. Sí
merchant > apiLogin Alfanumérico Min:12 Máx:32 Usuario o login entregado por PayU. Cómo obtengo mi API Login Sí
merchant > apiKey Alfanumérico Min:6 Máx:32 Contraseña entregada por PayU. Cómo obtengo mi API Key Sí
Respuesta (Response)
Nombre del campo Formato Tamaño Descripción
code Alfanumérico Código de respuesta de la transacción.
error Alfanumérico Máx:2048 Mensaje de error asociado si ocurrió un error.
transactionResponse transactionResponse Máx:2048 La respuesta del método PING si ocurrió un error.

Llamado del API

Los siguientes son los cuerpos de la petición y la respuesta para este método.


Ejemplo de una petición:

{
   "test": false,
   "language": "en",
   "command": "PING",
   "merchant": {
      "apiLogin": "pRRXKOl8ikMmt9u",
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA"
   }
}

Ejemplo de una respuesta:

{
    "code": "SUCCESS",
    "error": null,
    "transactionResponse": null
}

Ejemplo de una petición:

<request>
   <language>en</language>
   <command>PING</command>
   <merchant>
      <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
      <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
   </merchant>
   <isTest>false</isTest>
</request>

Ejemplo de una respuesta:

<paymentResponse>
    <code>SUCCESS</code>
</paymentResponse>
Última modificación 1 de abril de 2024: Documentation updates (9feaacb7)