[Description in English]

Para la version en Inglés de esta documentación, vea README_EN.md.

SDK para integración de BanWire Pago Pro con ReD. Revisar los archivos en la carpeta examples para ver los métodos de integración.

Para integrar utilizando sólo HTML, utiliza el siguiente formato:

<script
  type="text/javascript"
  src="https://sw.banwire.com/checkout.js"
  data-sandbox="true"
  data-user="pruebasbw"
  data-total="500.00"
  data-cust-fname="Ricardo"
  data-cust-mname="Gamba"
  data-cust-lname="Lavin"
  data-cust-email="prueba@banwire.com"
  data-success-page="http://google.com"
  data-error-page="http://facebook.com"
  data-pending-page="http://yahoo.com"
  data-concept="Concepto de pago"
  data-reference="Referencia de pago"
  data-notify-url="https://test.banwire.com/sw/examples/response.php"
  data-button-caption="Pagar ahora"
  data-button-class="btn-pay"
  data-secure-3d="false"
  data-international="false"
></script>

Para una integración más personalizada se pueden utilizar parámetros adicionales (opcionales):

<script
  type="text/javascript"
  src="https://sw.banwire.com/checkout.js"
  data-sandbox="true"
  data-user="pruebasbw"
  data-title="Mi Comercio"
  data-total="500.00"
  data-payment-options="visa,amex"
  data-review-order="true"
  data-international="true"
  data-secure-3d="false"
  data-loading-text="Espere..."
  data-success-page="https://test.banwire.com/sw/examples"
  data-notify-url="https://test.banwire.com/sw/examples/response.php"
  data-error-page="http://facebook.com"
  data-pending-page="http://yahoo.com"
  data-concept="Concepto de pago"
  data-reference="Referencia de pago"
  data-months="3,6,9,12"
  data-currency="MXN"
  data-exchange-rate=""
  data-cust-fname="Ricardo"
  data-cust-mname="Gamba"
  data-cust-lname="Lavin"
  data-cust-email="prueba@banwire.com"
  data-cust-phone="55555555"
  data-cust-addr="Circuito fuentes del pedregal 440 10"
  data-cust-zip="14140"
  data-cust-city="Mexico"
  data-cust-country="MEX"
  data-cust-state="DF"
  data-ship-addr="Direccion de envio"
  data-ship-zip="13145"
  data-ship-city="Mexico"
  data-ship-country="MX"
  data-ship-state="DF"
  data-button-caption="Pagar ahora"
  data-button-class="btn-pay"
  data-time="900"
  data-item-1-name="Primero"
  data-item-1-price="100.00"
  data-item-1-qty="2"
  data-item-2-name="Segundo"
  data-item-2-price="100.00"
  data-item-2-qty="3"
>
  /
</script>

Para pagos en donde el tarjetahabiente es representado por un tercero en posesión de los datos e información confidencial del tarjeta-habiente, se debe agregar el siguiente parámetro.

data-cust-represent="true"

Se pueden crear suscripciones a pagos recurrentes donde al cliente se le puede efecturar un número determinados de pagos fijos durante un periodo determinado de tiempo. Se deben agregar las siguientes variables:

data-recurring="true" data-recurring-interval="month" data-recurring-limit="10"
data-recurring-start="2014-08-21" data-recurring-total="100"

En donde la variable data-recurring-interval es el intervalo en el que se cobrará el pago y puede ser: "month" (mensualmente), "week" (semanalmente), "6months" (semestralmente), "annual" (anualmente), "3months" (trimestralmente) La variable data-recurring-limit determina el número de pagos a ejecutar antes que termine la suscripción. En caso de no definir esta variable, la suscripción nunca vencerá. En caso de no definir data-recurring-start, el pago inicial se efectuará de inmediato, en caso contrario el primer pago se realizará en la fecha especificada en esta variable en formato YYYY-MM-DD. En caso de no establecer la variable data-recurring-total, el monto de cada pago será el especificado en data-total. En caso de que se necesite efectuar un primer pago inmediato con un monto diferente a los pagos subsecuentes, se debe de ingresar el monto inicial a pagar en data-total y los pagos subsecuentes serán por el monto establecido en data-recurring-total

Es posible realizar una integración más personalizable utilizando Javascript directamente. Para hacerlo pimero se debe incluir el archivo JS en HEAD o BODY de la página:

<script
  type="text/javascript"
  src="https://sw.banwire.com/checkout.js"
></script>

Y utilizar el siguente formato para iniciar el servicio:

var SW = new BwGateway({
  // Quitar o establecer a false cuando pase a produccion
  sandbox: true,
  // Nombre de usuario de Banwire
  user: "pruebasbw",
  // Titulo de la entana
  title: "Mi Comercio",
  // Referencia
  reference: "testref01",
  // Concepto
  concept: "pago de prueba",
  // Opcional: Moneda
  currency: "MXN",
  // Opcional: Configuracion especial para pagos internacionales
  international: false,
  // Opcional: Habilitar Validacion 3D Secure
  secure3D: false,
  // Opcional: Tipo de cambio definido por el comercio (En caso de seleccionar una moneda que requiera mostrar el tipo de cambio a MXN. Solo informativo). Ejemplo: 15.00
  exchangeRate: "",
  // Total de la compra
  total: "100.00",
  // Opcional: Meses sin intereses
  months: [3, 6, 9, 12],
  // Arreglo con los items de compra
  items: [
    {
      name: "Articulo uno",
      qty: 1,
      desc: "Articulo de prueba numero uno",
      unitPrice: 10,
    },
    {
      name: "Articulo dos",
      qty: 2,
      desc: "Articulo numero dos de prueba",
      unitPrice: 40,
    },
    {
      name: "Otro articulo con nombre mas largo",
      qty: 2,
      desc: "Articulo numero tres de prueba con una descripcion larga",
      unitPrice: 40,
    },
  ],
  cust: {
    fname: "Ricardo", //Nombre del comprador
    mname: "Gamba", //Apellido paterno del comprador
    lname: "Lavin", //Apeliido materno del comprador
    email: "prueba@banwire.com", //Email del comprador
    phone: "55555555", //Número telefónico del comprador
    addr: "Direccion 440", //Dirección del comprador (calle y número)
    city: "Mexico", //Ciudad del comprador
    state: "DF", //Estado del comprador (2 dígitos de acuerdo al formato ISO)
    country: "MEX", //País del comprador (3 dígitos de acuerdo al formato ISO)
    zip: "14145", //Código de postal del comprador
  },
  ship: {
    addr: "Direccion 440", //Dirección de envío
    city: "Mexico", //Ciudad de envío
    state: "DF", //Estado de envío (2 dígitos de acuerdo al formato ISO)
    country: "MEX", //País de envío (3 dígitos de acuerdo al formato ISO)
    zip: "14145", //Código de postal del envío
  },
  // Cierre automático de la ventana. Por defecto es indefinido y no cerrará la ventana. (el valor es en segundos. valor minimo requerido 60 segundos.)
  time: 900, // Ejemplo de cierre de ventana automáticamente en 15 minutos
  // Opciones de pago, por defecto es "all". Puede incluir varias opciones separadas por comas
  paymentOptions: "all", // visa, mastercard, amex, paycash, oxxo,speifast,all
  // Mostrar o no pagina de resumen de compra
  reviewOrder: true,
  // Mostrar o no mostrar los campos de envio
  showShipping: true,
  // Solamente para pagos recurrentes o suscripciones
  recurring: {
    // Cada cuanto se ejecutará el pago "month","year" o un entero representando numero de días
    interval: "month",
    // Opcional: Limitar el número de pagos (si no se pone entonces no tendrá limite)
    limit: 10,
    // Opcional: Fecha del primer cargo (en caso de no especificar se ejecutará de inmediato)
    start: "2014-01-01", // Formaro YYYY-MM-DD
    // Opcional: En caso de que los pagos subsecuentes (después del primero)
    // tengan un monto distinto al inicial
    total: "50.00",
  },
  // URL donde se van a enviar todas las notificaciones por HTTP POST de manera asoncrónica
  notifyUrl: "https://www.mipagina.com/recibir.php",
  // Handler en caso de exito en el pago
  successPage: "http://google.com",
  onSuccess: function (data) {
    alert("¡Gracias por tu pago!");
  },
  // Pago pendiente OXXO
  pendingPage: "http://yahoo.com",
  onPending: function (data) {
    alert("El pago está pendiente por ser efectuado");
  },
  // Pago challenge
  challengePage: "http://challenge.com",
  onChallenge: function (data) {
    alert("Pago enviado a validaciones de seguridad");
  },
  // Handler en caso de error en el pago
  errorPage: "http://facebook.com",
  onError: function (data) {
    alert("Error en el pago");
  },
  // Cuando cierra el popup sin completar el proceso
  onCancel: function (data) {
    console.log("Se cancelo el proceso");
  },
});

function pagar() {
  // Podemos pagar con los valores por defecto
  SW.pay();

  /* O podemos modificar los valores antes de efectuar el pago
    SW.pay({
        total: 500,
        concept: "Concepto nuevo"
    });
    */
}

Se puede invocar el pago desde cualquier botón de pago:

<a href="#" onclick="pagar();" class="btn-pay">Pagar</a>

El sistema emitirá una serie de notificaciones en diferentes eventos del proceso que se detallarán a continuación.

Cada vez que se efectúa un pago exitoso, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

**** La variable sera agregada dentro la notificación solo en caso que se haya seleccionado un plan de pagos (pagos a meses).

Cada vez que un pago se envía a revisión, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se realize una solicitud de pago en OXXO, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se recibe un pago vía OXXO, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se realize una solicitud de pago en las tiendas de conveniencia con sistema Paycash, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se recibe un pago vía Paycash, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se realize una solicitud de pago en SPEIFAST, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se recibe un pago parcial vía SPEIFAST y no se cubre el monto total, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se recibe un pago vía SPEIFAST y si se cubre el monto total, el sistema enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se efectúa un pago recurrente exitoso, Banwire enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

Cada vez que se efectúa un pago recurrente declinado, Banwire enviará una notificación vía HTTP POST a la URL establecida en data-notify-url (HTML) o notifyUrl (Javascript) con las siguientes variables:

*** Por el momento está disponible solo para algunos usuarios.

Para cancelar una suscripción de pago recurrente se debe solicitar directamente al contacto soporte@banwire.com, dado que el servicio de cancelación está en mantenimiento.

Para realizar pruebas con Secure Window se debe activar el ambiente de sandbox y utilizar el usuario de pruebas 'pruebasbw', es posible simular el pago exitoso con la tarjeta de pruebas.

Ir a la página de ejemplos en vivo

Para pasar a producción el proceso es el siguiente, el representante de la cuenta debe enviar un correo a soporte@banwire.com solicitando su pase a modo de producción, de éste correo se les indicará las instrucciones a realizar en la integración para configurarla para modo de producción.

El parámetro 'hash' es un valor cifrado con el algoritmo SHA256 mediante una clave específica (API-SECRET) usando el método HMAC. Este parámetro se utilizará para poder verificar que el emisor de la notificación recibida está autorizado por el receptor, éste último deberá validar el parámetro Hash, asegurándose que el valor cifrado coincida con el que él calcula.

Todas las Respuestas y Notificaciones que son enviadas desde BanWire en los diferentes eventos del proceso de Secure Window incluyen el parámetro 'hash'.

API-SECRET es un valor único que se genera de forma aleatoria para cada cuenta de BanWire que se encuentran utilizando el API de Secure Window. BanWire sólo revelará ésta información al usuario autorizado de la cuenta (el manejo de ésta información quedará bajo responsabilidad y propio riesgo del usuario). Si se cree o se sabe que ésta información se conoce por un tercera o sufre algún tipo de riesgo, se debe informar inmediatamente a BanWire para que se pueda generar y proporcionar una nueva API-SECRET. Ésta información se proporcionará una vez el usuario tenga su proceso administrativo terminado, lo que incluye la firma del contrato con BanWire.

El parámetro 'hash' es el valor cifrado del parámetro 'id'(Identificador único de la transacción), el cual se incluye dentro de la notificación vía POST que envía BanWire a la URL del parámetro 'notifyUrl' en la integración. Ejemplo:

Ejemplo en PHP:

$hash = hash_hmac('sha256','14','aBc0123456789');