¿Cómo conectar mi servicio de pagos mediante la API?

La API de pagos está disponible solo con el plan Business. Se aplica una comisión de $0.25 por transacción al usar la API de pagos. Esta comisión se deducirá del saldo de tu cuenta de Bukza.

Puedes conectar cualquier servicio de pago a Bukza usando la API de pagos. Para esto, necesitarás tu propio servidor que actúe como intermediario entre Bukza y tu servicio de pago. Se requieren conocimientos de programación.

Ten en cuenta que esta API puede estar sujeta a cambios en el futuro.

¿Cómo activo la API?

Para activar la API de pagos, envía una solicitud a support@bukza.com. En tu mensaje, indica la URL de tu servidor donde Bukza debe enviar las solicitudes. Te proporcionaremos tu ID de usuario y la clave necesaria para generar el hash de firma.

Ejemplo de integración lista para usar

Puedes ver un ejemplo de código fuente en JavaScript en el editor de código online aquí.

Para probar este ejemplo con tu cuenta, sigue estos pasos:

Crea una cuenta en Glitch.
Crea un remix de nuestro ejemplo de integración aquí haciendo clic en el botón "Remix". Esto creará tu propia aplicación con el mismo código fuente.
Luego, abre la TERMINAL en Glitch y ejecuta el comando: npm ci. Esto instalará las dependencias necesarias.
Escríbenos a support@bukza.com con la dirección de tu nueva aplicación. Configuraremos esta dirección como la URL de tu servidor y te enviaremos el bukza_user_id y bukza_key.
Abre el archivo .env de tu aplicación e ingresa los valores de bukza_user_id y bukza_key. Este archivo no es visible para otros usuarios de Glitch.
Ve a tu cuenta de Bukza. En el formulario de procesamiento de pagos, activa "Pedidos con procesamiento automático de pagos" y establece el monto de anticipo requerido.
Completa un pedido usando el widget, asegurándote de usar el correo electrónico de tu cuenta. Cuando uses el correo electrónico de tu cuenta para completar el pedido, no se te cobrará ninguna comisión por usar la API de pagos.
Durante las pruebas, revisa la pestaña "Logs" en Glitch. Aquí encontrarás los registros de solicitudes recibidas y enviadas.
Implementa la visualización de tu formulario de pago y gestiona las respuestas de tu sistema de pago en los archivos server.js e index.hbs. No insertes tus claves o contraseñas en ningún archivo excepto en el archivo .env. Los archivos del proyecto y todo su historial de cambios son accesibles para otros usuarios de Glitch.

Opciones de integración

Puedes implementar una de estas dos opciones:

"Con preautorización" — esta opción evita la sobreventa. Cuando se completa el pedido, el monto primero se preautoriza en la tarjeta y luego verificamos que el pedido siga disponible y que el precio no haya cambiado. Si el pedido ya no está disponible, la preautorización se cancela de inmediato.

Con esta opción de integración, puedes capturar los fondos manualmente más tarde. Puedes verificar la reserva tú mismo y decidir si capturas los fondos o cancelas la preautorización.
"Modo simplificado" — esta opción no utiliza preautorización. En este caso, los fondos se capturan inmediatamente al completar el pedido. Igualmente verificamos la disponibilidad y el monto del pedido, y si hay algún problema, se agregará una advertencia para el administrador en el mensaje de "Nuevo pedido".

Usa esta opción si tu servicio de pago no soporta preautorización.

¿Cómo genero el hash de firma?

Los siguientes parámetros siempre se incluyen en las solicitudes:

userId — tu ID en el sistema Bukza, por ejemplo, 11223.
orderNumber — el número de pedido en Bukza, por ejemplo, "574285869".
command — el nombre del comando a ejecutar. Valores posibles: "GetPaymentData", "CaptureCallback", "AuthorizeCallback", "Cancel", "Capture" o "Refund".
data — datos adicionales del comando, como el número de transacción en tu sistema de pago: "18493853499".
amount — el monto del pago, por ejemplo, 99.75.
timestamp — el número de segundos desde la época Unix, por ejemplo, 1596706182. Para ejemplos en diferentes lenguajes de programación, consulta: https://www.epochconverter.com.

Para crear o verificar la firma de la solicitud, concatena todos estos parámetros en una sola cadena (sin espacios ni signos de suma), calcula el HMAC SHA256 usando tu clave y convierte el resultado a una cadena base64:

hash = base64(hmacSha256(userId + orderNumber + command + data + amount + timestamp), key);

Ejemplos de implementación en diferentes lenguajes de programación: https://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-different-languages/

Puedes comprobar el cálculo aquí: http://jsfiddle.net/dwyrk513/1/

Notas importantes:

Al convertir el valor de amount a cadena, usa un punto como separador decimal si hay parte fraccionaria.
Al recibir solicitudes, Bukza verifica que el timestamp coincida con la hora actual del servidor y no difiera en más de 5 minutos.
Al recibir solicitudes de Bukza, te recomendamos que también verifiques el hash y el timestamp de la misma manera.

Opción #1 "Con preautorización"

1.1. Cuando se completa el pedido, Bukza envía una solicitud POST a la URL de tu servidor con el siguiente cuerpo:

{
    userId:11223,
    orderNumber:"574285869",
    command: "GetPaymentData",
    data: "",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "p2t1xcpBiXLPPDdB129vUctRAgGbzQgRcnX4IiZ0bNE="
    email: "john@example.com",
    phone: "+11111111111",
    culture = "en",
    checkStateToken = "eyJVc2VySWQiOjIsIk9yZGVyS...Ws9In0%3D"
}

En respuesta a esta solicitud, debes enviar los datos en el siguiente formato:

{
url: "https://yoursite.ru/amount=99.75&orderNumber=574285869&bukzaCulture=ru&bukzaUser=11223&bukzaCheckStateToken=eyJVc2VySWQiOjIsIk9yZ",
redirect: false
}

url — la dirección generada de la página de pago. Esta página puede estar alojada en tu servidor o en el servidor de tu pasarela de pago.
redirect — determina si el usuario debe ser redirigido completamente a la URL indicada. Si es false, el formulario de pago aparecerá dentro del widget en un iframe. Puedes ajustar el tamaño del iframe usando CSS en la configuración del widget.
checkStateToken se agrega a la url como el parámetro bukzaCheckStateToken. Este parámetro te permite verificar el estado del pedido en tu página de pago. Lee más sobre esto aquí.

1.2. El cliente ahora ve tu formulario de pago y completa el pago. Debes recibir una notificación de tu pasarela de pago en tu servidor. Después de recibir esta notificación, envía inmediatamente una solicitud POST a https://public.bukza.com/api/pay. Cuerpo de la solicitud:

{
    userId:11223,
    orderNumber:"574285869",
    command: "AuthorizeCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "2kkjjx/grcar6B9yknqUMP6eOdMw4yJwa60Uc8fisNA=",
    comment: "Cualquier comentario sobre el pago. Esto será visible en la interfaz del administrador. No se usa en el cálculo de la firma de la solicitud."
}

1.3. Dependiendo de la disponibilidad del pedido y los parámetros de procesamiento, Bukza puede hacer lo siguiente: cancelar la preautorización, capturar los fondos de inmediato o simplemente registrar el pedido dejando los fondos preautorizados. En este último caso, puedes cancelar o capturar el pago tú mismo en la interfaz del Administrador. En todos los casos, Bukza enviará solicitudes a tu servidor, que luego deberás reenviar a tu pasarela de pago.

Para cancelar la preautorización, Bukza te envía una solicitud con el siguiente cuerpo:

{
    userId:11223,
    orderNumber:"574285869",
    command: "Cancel",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "ejIS+AiPRSH9qXV/bBcAf7OSViCVUtj/hYPsL4aYpNM="
    email: "john@example.com",
    phone: "+11111111111",
}

Para capturar fondos preautorizados, Bukza te envía una solicitud con el siguiente cuerpo:

{
    userId:11223,
    orderNumber:"574285869",
    command: "Capture",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "JE4fRRLObEzCYk7aRFaW81DZw3sTXTOXsEcq3r8zm+Y="
    email: "john@example.com",
    phone: "+11111111111",
}

Debes responder con el estado HTTP 200 (SUCCESS) a cualquier solicitud de este tipo.

Opción #2 "Modo simplificado"

2.1. Cuando se completa el pedido, Bukza también envía una solicitud POST a la URL de tu servidor, igual que en el paso 1.1.

2.2. El cliente ahora ve tu formulario de pago y completa el pago. Debes recibir una notificación de tu pasarela de pago en tu servidor. Después de recibir esta notificación, envía inmediatamente una solicitud POST a https://public.bukza.com/api/pay. Cuerpo de la solicitud:

{
    userId:11223,
    orderNumber:"574285869",
    command: "CaptureCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "eUKOwld1sEK3axhF9ZAy0WugXMJW+9nrs4BRlvnCeb0=",
    comment: "Cualquier comentario sobre el pago. Esto será visible en la interfaz del administrador. No se usa en el cálculo de la firma de la solicitud."
}

Reembolsar

Puedes usar la interfaz del Administrador para emitir un reembolso para un pago específico. El reembolso puede ser total o parcial. Cuando se procesa un reembolso, Bukza envía una solicitud a tu servidor. Luego debes enviar la solicitud correspondiente a tu pasarela de pago. Cuerpo de la solicitud desde Bukza:

{
    userId:11223,
    orderNumber:"574285869",
    command: "Refund",
    data: "18493853499",
    amount: 50.75,
    timestamp: 1596706182,
    hash: "E62WH04cKUjAvQ0dmirYMc16mCGN96YyQfrft8vLj0A="
    email: "john@example.com",
    phone: "+11111111111",
}

Debes responder con el estado HTTP 200 (SUCCESS) a cualquier solicitud de este tipo.