Widget & Checkout Web

Acepta pagos en tu sitio web en minutos usando una de nuestras dos opciones de Checkout:

Widget	Web Checkout
Permite que tus clientes completen el pago sin salir de tu sitio web, dentro de nuestro widget de pagos, simplemente incluyendo una etiqueta <script> (debes poder incluir Javascript en tu sitio). Puedes ver un ejemplo a continuación	Deja que tus clientes completen el pago fuera de tu website, a través de nuestro Checkout usando un formulario HTML estándar

Ambos métodos de integración ofrecen una experiencia de pago rápida y segura para tus clientes.

Paso a paso

• Paso 1 — Alista tu llave pública de comercio
• Paso 2 — Genera una referencia única de pago
• Paso 3 — Genera una firma de integridad
• Paso 4 — Prepara una URL de redirección para el momento de finalizar el pago
• Paso 5 — Ten en cuenta los parámetros obligatorios y opcionales de una transacción
• Paso 6 — Escoge un método de integración de checkout
• Paso 7 — Escucha el evento de una transacción en tu servidor con un webhook

Usa HTTPS

Te recomendamos fuertemente usar HTTPS en tu sitio web, ya que no sólo tus clientes se sentirán más seguros a la hora de navegar y hacer pagos, sino que también evitarás que tu sitio sea marcado como "No seguro", un cambio que Google Chrome alertó que haría desde el 24 de julio de 2018. Algo importante a tener en cuenta ya que sólo este navegador representa más del 60% del tráfico en la web.

Paso 1: Alista tu llave pública de comercio

Para cualquiera de las integraciones que hagas con Wompi, deberás contar con una llave pública de comercio, que se ve como la siguiente:

pub_prod_Kw4aC0rZVgLZQn209NbEKPuXLzBD28Zx

Obtén tus llaves Wompi

Para obtener tus par de llaves Wompi, sólo debes registrarte en nuestro dashboard de Comercios si aún no lo has hecho. ¡Es así de fácil!

Esta llave nos permite identificarte cada vez que se procesa un pago a través de Wompi. Si no tienes tu llave pública aún, haz clic acá para entender cómo obtener una llave pública de comercio.

¡Recuerda que hay llaves de sandbox y producción!

Las llaves de sandbox (entorno de pruebas) tienen el prefijo pub_test_, mientras que las de producción tienen el prefijo pub_prod_. Para transacciones con dinero real usa la llave de Producción; para hacer transacciones de prueba, mientras integras y desarrollas, usa la llave de Sandbox.

Paso 2: Genera una referencia única de pago

Para cada compra que tus clientes hagan en tu website, deberás generar una referencia única de pago (similar a como funciona un número de factura en el mundo real). De esta manera podrás hacer seguimiento a cada transacción que se complete en Wompi y evitarás duplicar transacciones por accidente. Esto quiere decir que una vez se complete una transacción, no podrás reutilizar una referencia que ya exista en tu base de datos.

Recomendamos usar referencias numéricas o alfanuméricas, que pueden o no incluir guiones (-) o guiones bajos (_). Los siguientes son ejemplos de referencias válidas:

• 3b4393bafed398ba2
• 54937
• 10384200283
• 58e281-177ab976cbf9-d162d2
• 38932_3293298
• 0f760951ed_a0086f

Paso 3: Genera una firma de integridad

Para validar la integridad de la información de la transacción y evitar alteraciones, Wompi utiliza un hash criptográfico asimétrico.

Para generar este hash criptográfico, busca el secreto de integridad accediendo al dashboard de comercios en "Desarrolladores > Secretos para integración ténica", se debería ver algo como esto:

Es importante que aclarar que este Secreto para Integridad es diferente de tu Llave Privada y Llave Pública.

  prod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6

Después de tener listo tu secreto de integración, deberas generar un hash SHA256 con la siguiente información (el orden importa):

1. Referencia de la transacción: sk8-438k4-xmxm392-sn2m
2. Monto de la transacción en centavos: 2490000
3. Moneda de la transacción: COP
4. Secreto de integridad: prod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6

Estos valores se concatenan:

  "<Referencia><Monto><Moneda><SecretoIntegridad>"

Así se vería con valores de ejemplo:

  "sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"

Importante, al usar el parámetro expiration-time se deberá concatenar como valor adicional:

1. Fecha de expiración: 2023-06-09T20:28:50.000Z

Los valores anteriores se concatenan con el valor adicional en el siguiente orden:

  "<Referencia><Monto><Moneda><FechaExpiracion><SecretoIntegridad>"

Así se verían con el valor adicional de ejemplo:

  "sk8-438k4-xmxm392-sn2m2490000COP2023-06-09T20:28:50.000Zprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"

Y lo encriptamos con SHA256:

Te recomendamos fuertemente crear este hash criptografico en tu servidor y nunca en tu frontend, pues expondrías el secreto de integración a un potencial atacante

En Ruby:

    #como se escribe
    Digest::SHA2.hexdigest($cadena_concatenada)
    #ejemplo
    Digest::SHA2.hexdigest("sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6") #"37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"

En Php:

  // Cómo se escribe
  hash ("sha256", $cadena_concatenada);
  // Ejemplo
  hash ("sha256", "sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"); //"37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"

En Javascript:

  var cadenaConcatenada = "sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"
  //Ejemplo
  const encondedText = new TextEncoder().encode(cadenaConcatenada);
  const hashBuffer = await crypto.subtle.digest('SHA-256', encondedText);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join(''); // "37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"

En Python:

  import hashlib
  # Ejemplo
  cadena_concatenada = "sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"
  m = hashlib.sha256()
  m.update(bytes(cadena_concatenada))
  m.digest()
  #"37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"

Este valor debemos enviarlo en la atributo signature:integrity:

<form>
  <script
    data-signature:integrity="37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"
    ...
    >
  </script>
</form>

Paso 4: URL de redirección

Al finalizar una transacción, opcionalmente, Wompi puede redirigir al usuario a una URL (que debe pertenecer a tu sitio web), en la cual podrás consultar el resultado final (status) de la transacción. Esto lo puedes hacer usando el id de la transacción, el cual estará disponible como un parámetro de la URL.

Así por ejemplo, si tu URL es:

https://mitienda.com.co/pagos/respuesta

La URL a la que Wompi redirigirá es similar a la siguiente:

https://mitienda.com.co/pagos/respuesta?id=01-1531231271-19365

Así, puedes usar el parámetro id disponible en la URL para verificar la transacción usando nuestro API apuntando a la URL https://production.wompi.co/v1/transactions/<ID_TRANSACCION>. Por ejemplo https://production.wompi.co/v1/transactions/01-1531231271-19365 (este ID puede NO ser real y sirve solo para dar un ejemplo)

Paso 5: Parámetros de la transacción

Para cada transacción puedes proveer parámetros como el monto a cobrar, la moneda en la que quieres cobrar, etc. Algunos de estos parámetros son obligatorios y otros son opcionales.

Parámetros obligatorios

Los siguientes son los parámetros obligatorios que debes tener en cuenta para crear una transacción:

• public-key (Llave pública de comercio): Llave pública de comercio.
• currency (Moneda): Moneda en la que vas a hacer el cobro. La única moneda disponible actualmente es COP (pesos colombianos).
• amount-in-cents (Monto en centavos): Monto a cobrar, en centavos. Por ejemplo si deseas cobrar $95.000 COP, deberás ingresar: 9500000
• reference (Referencia única de pago): Referencia única de pago.
• signature:integrity (Firma de integridad): Es un hash criptográfico que utilizamos para validar la integridad de la información de la transacción y evitar alteraciones.

Parámetros opcionales

Los siguientes son parámetros opcionales que, aunque no sean necesarios, proveen una mejor experiencia de integración:

• redirect-url (URL de redirección): Es la URL a la que el usuario será redirigido luego completar el proceso de pago, conteniendo el id de la transacción respectiva.
• shipping-address (Información de envío): Es la información de dirección de envío del cliente, donde recibirá los productos y/o servicios, si aplica. Los datos que se pueden enviar son los siguientes:
  • address-line-1: (Obligatorio) para la dirección del lugar de la entrega
  • address-line-2: para referencias extras
  • country: (Obligatorio) para el código ISO 3166-1 Alpha-2 (2 letras mayúsculas) del país donde se encuentra la dirección (ej: CO)
  • city: (Obligatorio) para especificar la ciudad donde se encuentra la dirección
  • phone-number: (Obligatorio) para el número de teléfono de quien recibe
  • region: (Obligatorio) para la región donde se encuentra la dirección
  • name: para el nombre de quien recibe
  • postal-code: para el código postal
• collect-shipping (Activar formulario de envío): Este parámetro activa la vista de información de envío, y si se diligenciaron los campos anteriores, aparecerán prellenados en la vista.
• customer-data (Información del pagador): Es la información del pagador, la cual se prellenara en la vista de "Ingresa tus datos". Los datos permitidos son:
  • email: para el correo electrónico del pagador
  • full-name: para el nombre completo del pagador
  • phone-number: para el número de teléfono del pagador, debe ir acompañado del campo phone-number-prefix
  • phone-number-prefix: para el prefijo o código del país del teléfono del pagador (ej: +57), debe ir acompañado del campo phone-number
  • legal-id: para el número de documento de identidad del pagador, este parámetro activa el campo de documento de identidad del pagador en la vista de "Ingresa tus datos" y debe ir acompañado del campo legal-id-type
  • legal-id-type: para el tipo de documento del pagador, este parámetro activa el campo de documento de identidad del pagador en la vista de "Ingresa tus datos" y debe ir acompañado del campo legal-id. Los tipos de documento permitidos son:
    • CC: Cédula de Ciudadanía
    • CE: Cédula de Extranjería
    • NIT: Número de Identificación Tributaria
    • PP: Pasaporte
    • TI: Tarjeta de Identidad
    • DNI: Documento Nacional de Identidad
    • RG: Carteira de Identidade / Registro Geral
    • OTHER: Otro
• collect-customer-legal-id: Activa el campo de documento de identidad del pagador, usando true como valor. Este parámetro activa el campo de documento de identidad del pagador en la vista de "Ingresa tus datos". Si se diligenciaron los campos de legal_id y legal_id_type de customer_data, se prellenara con dicha información
• tax-in-cents (Detalle de impuestos en pago): Es la información de impuestos en la que puedes detallar el tipo de impuesto y el monto del impuesto dentro del precio total de la transacción en centavos. Más adelante se explica la manera de usarlo en las distintas formas de integración. Los tipos de impuestos permitidos son los siguientes:
  • VAT: para el IVA (Impuesto de Valor Agregado)
  • CONSUMPTION: para el Impuesto al Consumo
• expiration-time: Fecha y hora en formato ISO8601 (UTC+0000), activa un contador regresivo indicando el tiempo restante para la expiración del inicio del pago

Los impuestos no se sumarán al monto de la transacción

Es importante resaltar que los impuestos enviados en el objeto taxes no se sumarán al total de la transacción.
Por ejemplo, en una transacción cuyo total (amount_in_cents) es de COP$119,000 y cuyo IVA es de COP$19,000, este último monto ya hace parte del total, implicando entonces que: la base sin impuestos ($100,000) + el IVA ($19,000) = el total ($119,000).
En otras palabras, Wompi no sumará $19,000 a los $119,000, sino que simplemente compartirá esta información tributaria con el respectivo procesador del pago.

Paso 6: Escoge un método de integración

Escoge una de las dos opciones de integración:

• Widget: Permite que tus clientes completen el pago dentro de tu sitio web en nuestro Widget.
• Web: Tus clientes completan el pago en nuestro Web Checkout.

Widget

Este es el método más simple para que tus clientes completen un pago sin salir de tu sitio web. Con tan solo unas líneas de HTML, un botón de pagos se mostrará automáticamente.

Al hacer clic en el botón, el cliente continúa el proceso de pago dentro de nuestro widget, sin salir de tu sitio web (si quieres un botón a la medida, lee la sección de Botón personalizado).

A continuación verás un ejemplo del botón generado con el mismo código que encuentras debajo:

<form>
  <script
    src="https://checkout.wompi.co/widget.js"
    data-render="button"
    data-public-key="pub_test_X0zDA9xoKdePzhd8a0x9HAez7HgGO2fH"
    data-currency="COP"
    data-amount-in-cents="4950000"
    data-reference="4XMPGKWWPKWQ"
    data-signature:integrity="37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"
    >
  </script>
</form>

El código que ves arriba tiene los parámetros mínimos necesarios para generar un botón de pago que permite a tu cliente pagar en nuestro widget. Así, sólo necesitas incluir una etiqueta <script> con los parámetros de la transacción, dentro de una etiqueta <form> en tu código, para generar el botón.

Sólo necesitas tener en cuenta dos cosas para generar el botón:

1. Incluye el parámetro data-render="button", que indica que quieres generar un botón automáticamente.
2. Para los parámetros listados arriba debes usar el prefijo data- en cada uno, para especificarlo (i.e. data-reference, data-currency, data-amount-in-cents, etc.) y usar guiones (-) en vez de guiones bajos (_) para los nombres de cada parámetro.
3. Para los parámetros de shipping-address, customer-data y tax-in-cents debes usar dos puntos (:) para especificar el tipo de información que se desea.

Un ejemplo con todos los parámetros se ve como el siguiente:

<form>
  <script
    src="https://checkout.wompi.co/widget.js"
    data-render="button"
    data-public-key="pub_test_X0zDA9xoKdePzhd8a0x9HAez7HgGO2fH"
    data-currency="COP"
    data-amount-in-cents="7890000"
    data-reference="37DNKF84S92N1S"
    data-signature:integrity="37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"
    data-redirect-url="https://transaction-redirect.wompi.co/check"
    data-expiration-time="2023-06-09T20:28:50.000Z"
    data-tax-in-cents:consumption="590000"
    data-tax-in-cents:vat="1290000"
    data-customer-data:email="lola@perez.com"
    data-customer-data:full-name="Lola Perez"
    data-customer-data:phone-number="3019777777"
    data-customer-data:phone-number-prefix="+57"
    data-customer-data:legal-id="123456789"
    data-customer-data:legal-id-type="CC"
    data-shipping-address:address-line-1="Carrera 123 # 4-5"
    data-shipping-address:address-line-2="apto 123"
    data-shipping-address:country="CO"
    data-shipping-address:city="Bogota"
    data-shipping-address:phone-number="3019988888"
    data-shipping-address:region="Cundinamarca"
    data-shipping-address:name="Pedro Perez"
    >
  </script>
</form>

Web Checkout

Este es el método más rápido para integrar Wompi en tu sitio web, usando únicamente un formulario HTML estándar:

<form action="https://checkout.wompi.co/p/" method="GET">
  <!-- OBLIGATORIOS -->
  <input type="hidden" name="public-key" value="LLAVE_PUBLICA_DEL_COMERCIO" />
  <input type="hidden" name="currency" value="MONEDA" />
  <input type="hidden" name="amount-in-cents" value="MONTO_EN_CENTAVOS" />
  <input type="hidden" name="reference" value="REFERENCIA_DE_PAGO" />
  <input type="hidden" name="signature:integrity" value="FIRMA_DE_INTEGRIDAD"/>
  <!-- OPCIONALES -->
  <input type="hidden" name="redirect-url" value="URL_REDIRECCION" />
  <input type="hidden" name="expiration-time" value="FECHA_EXPIRACION" />
  <input type="hidden" name="tax-in-cents:vat" value="IVA_EN_CENTAVOS" />
  <input type="hidden" name="tax-in-cents:consumption" value="IMPOCONSUMO_EN_CENTAVOS" />
  <input type="hidden" name="customer-data:email" value="CORREO_DEL_PAGADOR" />
  <input type="hidden" name="customer-data:full-name" value="NOMBRE_DEL_PAGADOR" />
  <input type="hidden" name="customer-data:phone-number" value="NUMERO_DE_TELEFONO_DEL_PAGADOR" />
  <input type="hidden" name="customer-data:legal-id" value="DOCUMENTO_DE_IDENTIDAD_DEL_PAGADOR" />
  <input type="hidden" name="customer-data:legal-id-type" value="TIPO_DEL_DOCUMENTO_DE_IDENTIDAD_DEL_PAGADOR" />
  <input type="hidden" name="shipping-address:address-line-1" value="DIRECCION_DE_ENVIO" />
  <input type="hidden" name="shipping-address:country" value="PAIS_DE_ENVIO" />
  <input type="hidden" name="shipping-address:phone-number" value="NUMERO_DE_TELEFONO_DE_QUIEN_RECIBE" />
  <input type="hidden" name="shipping-address:city" value="CIUDAD_DE_ENVIO" />
  <input type="hidden" name="shipping-address:region" value="REGION_DE_ENVIO" />
  <button type="submit">Pagar con Wompi</button>
</form>

De esta forma, sólo debes asegurarte de llenar correctamente los parámetros obligatorios e incluir este código en donde quieras que tus clientes vean el botón para completar el pago. Una vez hagan clic en él, serán llevados a nuestro Web Checkout donde podrán completar el pago de manera rápida y segura.

Paso 7: Escucha el evento de una transacción

Usa siempre los eventos para finalizar tu integración

Al haber integrado el Widget o Web Checkout en tu website, sólo resta que escuches un Evento en tu servidor, para enterarte cuando una transacción finalizó. No utilices la redirección como método de validación de tus transacciones, sino únicamente con propósitos informativos para tus usuarios.

Una vez un usuario haya finalizado una transacción, Wompi te informará a través de un Evento que la misma llegó a un estado final. Para ello deberás proveer una URL de Eventos (a webhook), donde Wompi te enviará un objeto JSON con la información completa de la transacción. Haz clic acá y visita la guía de Eventos para conocer en detalle todo sobre esta funcionalidad.

Transacción de pruebas

Esta información está en otra página

Encuentra toda la información que necesitas para hacer transacciones de prueba en:
Datos de prueba en Sandbox.

Botón personalizado (opcional)

Si quieres ofrecer una integración personalizada a tus clientes, como por ejemplo un botón con estilos propios, o abrir el widget dada cierta acción de un usuario, simplemente debes seguir los siguientes pasos:

Paso 1: Incluye el script del widget

Agrega esta etiqueta preferiblemente dentro del <head> de tu HTML:

<script type="text/javascript" src="https://checkout.wompi.co/widget.js"></script>

Paso 2: Configura los datos de la transacción

Configura una instancia del checkout con el objeto de configuración, cuyos campos se muestran a continuación con valores de ejemplo. Todos son obligatorios, excepto redirectUrl.

var checkout = new WidgetCheckout({
  currency: 'COP',
  amountInCents: 2490000,
  reference: 'AD002901221',
  publicKey: 'pub_fENJ3hdTJxdzs3hd35PxDBSMB4f85VrgiY3b6s1',
  redirectUrl: 'https://transaction-redirect.wompi.co/check', // Opcional
  expirationTime: '2023-06-09T20:28:50.000Z', // Opcional
  taxInCents: { // Opcional
    vat: 1900,
    consumption: 800
  }
  customerData: { // Opcional
    email:'lola@gmail.com',
    fullName: 'Lola Flores',
    phoneNumber: '3040777777',
    phoneNumberPrefix: '+57',
    legalId: '123456789',
    legalIdType: 'CC'
  }
  shippingAddress: { // Opcional
    addressLine1: "Calle 123 # 4-5",
    city: "Bogota",
    phoneNumber: '3019444444',
    region: "Cundinamarca",
    country: "CO"
  }
})

Paso 3: Abre el widget

Finalmente, en el momento en que quieras abrir el widget que configuraste anteriormente, simplemente debes llamar la función open pasándole como parámetro una función de respuesta (callback) que te entregará información sobre la transacción tan pronto esta finalice. Por ejemplo:

checkout.open(function ( result ) {
  var transaction = result.transaction
  console.log('Transaction ID: ', transaction.id)
  console.log('Transaction object: ', transaction)
})