Ir al contenido
ES
Iniciar sesión Regístrate
Docs

Recursos oficiales

Módulo zittme Pay

zittme Pay es el módulo de pasarela de pagos de Zittme. Procesa en un solo lugar los pagos de otros módulos como comercio y reservas, y ofrece gestión del historial de pagos, cancelaciones y registros. Los módulos de terceros también pueden cobrar con zittme Pay si siguen la convención establecida.

Instalación

  1. Instala el módulo zittme Pay desde la tienda.
  2. En Administración > zittme Pay usa las pestañas Configuración · Pasarelas · Historial de pagos · Registros.

    3. Todas las opciones de la pestaña Configuración

    OpciónDescripción
    ActivarEnciende o apaga toda la función de pagos
    Modo de pruebaRevisa el flujo de pago sin autorizaciones reales. Usa también claves de prueba en las pasarelas
    MonedaKRW por defecto
    Prefijo del número de pedidoMarca para reconocer tus pedidos en el panel del procesador de pagos (hasta 8 letras o números)
    Permitir cancelación parcialSi se puede cancelar solo una parte del importe. Si lo desactivas, solo se permite la cancelación total
    Lista de motivos de cancelaciónMotivos que se eligen al cancelar. Escribe uno por línea
    Plazo de cancelación automática en el procesador (días)Pasado este tiempo desde el pago, ya no se intenta cancelar en el procesador y se pasa a reembolso manual, porque los pagos con tarjeta ya liquidados no se pueden cancelar en el procesador. 0 significa sin límite
    Permitir cancelación forzada de pagos confirmadosPermite al administrador cancelar pagos con compra confirmada. Si lo desactivas, después de confirmar no se cancelan por ninguna vía
    Correo de avisos al administradorDirección que recibe los avisos
    Eventos de avisoSi se envía aviso al completar el pago / al cancelar, por separado
    Días de conservación de registrosTiempo que se guardan los registros de pago (0 = indefinido)
    Lista de IP permitidas para webhooksLimita las IP desde las que se reciben webhooks de las pasarelas. Si la dejas vacía, no hay límite
    Aviso en la pantalla de pagoTexto que se muestra al pie de la pantalla de pago, como el número de registro de venta a distancia
    Skin de la pantalla de pagoElige el skin de las pantallas de pago y de resultado

    Pestaña Pasarelas (métodos de pago)

    Activa los métodos de pago que vas a usar e ingresa los datos de cada uno.

    Toss Payments (tarjetas, etc.)

    OpciónDescripción
    Clave de clienteSe emite en el centro de desarrolladores de Toss Payments
    Clave secretaIgual que la anterior. Nunca la expongas

    Te recomendamos revisar el flujo con claves de prueba + modo de prueba y después cambiar a claves en vivo. Si el tipo de clave (prueba/en vivo) no coincide con el modo, la autorización falla.

    KG Inicis

    OpciónDescripción
    ID de comercio (MID)Se emite en el panel de comercios de Inicis
    Sign KeySe usa para firmar la ventana de pago
    INIAPI KeyClave exclusiva para cancelaciones y reembolsos. Se emite aparte en el panel de comercios

    En modo de prueba puedes revisar hasta la ventana de pago, incluso antes de firmar contrato, con las claves de la tienda de prueba pública (mid INIpayTest). Si la comunicación de autorización se corta o el importe no coincide, se hace una cancelación de red automática para evitar cobros duplicados.

    NHN KCP

    OpciónDescripción
    Código de sitio (site_cd)Lo emite KCP. Para pruebas, T0000
    Certificado de servicioPega tal cual el contenido del archivo PEM que obtuviste en el centro de certificados del panel de KCP
    Clave privada de la tienda · contraseñaSe usan solo para la firma electrónica de solicitudes de cancelación y reembolso

    NICEPAY

    OpciónDescripción
    Client IDSe emite en el centro de desarrolladores de NICEPAY (developers.nicepay.co.kr)
    Secret KeyIgual que el anterior

    Con solo registrarte en el centro de desarrolladores obtienes claves de sandbox, así que puedes probar el flujo de pago y cancelación antes del contrato. Si el modo de prueba está activado, se conecta automáticamente al servidor sandbox.

    PortOne (V2)

    OpciónDescripción
    Store IDSe emite en la consola de PortOne (portone.io)
    Clave de canalCon qué procesador se cobra se define en la configuración de canales de la consola de PortOne
    V2 API SecretSe usa para autorizaciones y cancelaciones del servidor

    Con un solo driver puedes usar varios procesadores conectados a PortOne. Para probar, ingresa las claves de un canal de prueba.

    PayPal (pagos internacionales)

    OpciónDescripción
    Client ID · SecretSe emiten en una app de la consola de desarrolladores de PayPal (developer.paypal.com). En modo de prueba usa las claves de una app sandbox
    Moneda de cobroPayPal no admite KRW. Los pedidos en wones se convierten a esta moneda para cobrar (USD por defecto)

    La conversión usa el tipo de cambio común de abajo, y los reembolsos se hacen con el tipo de cambio del momento del pago. Los pedidos en moneda extranjera (multimoneda de comercio) se cobran directamente en esa moneda, sin conversión.

    Conekta (México · Latinoamérica)

    Con la página de pago alojada de Conekta, procesador de pagos mexicano, recibes tarjetas, efectivo (tiendas OXXO) y transferencias (SPEI). Al pulsar Pagar se abre la página de pago de Conekta y, al terminar, se regresa al sitio. El efectivo y las transferencias regresan en estado "Depósito pendiente", con solo la referencia o la cuenta emitida, y el depósito real se confirma por webhook.

    OpciónDescripción
    Clave privada de ConektaClave privada (empieza con key_) creada en el panel de Conekta > Desarrolladores > API Keys. La clave pública no se usa
    Dirección del webhookRegistra la dirección que aparece en pantalla en el panel de Conekta > Desarrolladores > Webhooks. Es indispensable para confirmar depósitos en efectivo y transferencias
    Métodos de pagoElige los métodos que se abren en la página de pago: tarjeta / efectivo (OXXO) / transferencia (SPEI). Si lo dejas vacío, se abren todos
    Moneda de cobroMoneda a la que se convierten los pedidos en wones. MXN por defecto. OXXO y SPEI solo admiten MXN, y el cobro con tarjeta en USD depende del tipo de cuenta de Conekta
    Permitir pedidos en wonesSi lo activas, los pedidos en wones se convierten con el tipo de cambio común para cobrar. La tabla de tipos de cambio debe tener una fila para la moneda de cobro (MXN)

    Obtener claves de prueba

    1. Regístrate en panel.conekta.com y entra con "Explorar panel"; se crea una empresa de prueba sin revisión del negocio.
    2. Activa "Modo pruebas" abajo a la izquierda y, en Desarrolladores > "Consultar API Keys de prueba", crea la clave privada con "Crear nueva llave privada". La clave privada solo se muestra una vez al crearla, así que cópiala de inmediato.
    3. Ingresa la clave privada en la pestaña Pasarelas y pulsa "Probar conexión"; se muestra el modo (sandbox / en vivo). Las claves de prueba no tienen un prefijo distinto, así que el modo se determina por la respuesta de Conekta. Antes de crear el primer pedido puede aparecer "Requiere verificación".
    4. En Desarrolladores > Webhooks > "Crear Webhook" ingresa la dirección del webhook de arriba y activa todos los eventos. Llegue el evento que llegue, zittme Pay vuelve a consultar el pedido en la API de Conekta para confirmarlo, así que una notificación falsificada no puede confirmar un pago.

      5. Pagos de prueba

      • Tarjetas aprobadas: 4242 4242 4242 4242 (Visa), 5555 5555 5555 4444 (Mastercard). Nombre y CVC cualquiera, fecha de vencimiento futura.
      • Tarjeta rechazada: 4000 0000 0000 0002; fondos insuficientes: 4000 0000 0000 0127.
      • Para transferencias (SPEI), llama con la CLABE emitida a la API de notificación de depósitos de sandbox de Conekta (/sandbox/spei/payment_notifications) y el depósito se procesa. El efectivo (OXXO) se marca como depositado automáticamente en sandbox tras un momento.

      Claves en vivo

      Según los términos de Conekta, una cuenta en vivo requiere un negocio constituido conforme a las leyes mexicanas (con RFC) y una cuenta de liquidación en México. Cuando termine la revisión, solo ingresa la clave en vivo del panel en el mismo campo. Los reembolsos por API solo aplican a pagos con tarjeta; los pagos en efectivo y por transferencia pasan a reembolso manual.

      Transferencia bancaria

      OpciónDescripción
      Cuentas de depósitoRegistra varias cuentas con banco · número de cuenta · titular. El comprador elige la cuenta al hacer el pedido
      Plazo de depósito (días)De 1 a 30 días. Los pedidos sin depósito vencidos pasan a cancelación automática

      El administrador confirma los depósitos en el historial de pagos, y al confirmarlos el pedido del módulo integrado pasa a pagado.

      Tipo de cambio común

      En la pestaña Pasarelas administras el tipo de cambio por moneda (KRW por 1 unidad de la moneda). Es la referencia única que comparten la conversión de pagos de zittme Pay y los precios multimoneda del módulo de comercio.

      OpciónDescripción
      Tabla de tipos de cambioRegistra el código de moneda (USD, etc.) y el tipo de cambio
      Fijar manualmenteLas monedas marcadas no se sobrescriben con la actualización automática
      Actualización automáticaSe actualiza una vez al día. Elige la fuente: open.er-api.com (sin clave) o el Export-Import Bank of Korea (requiere clave de API)

      Si la actualización automática falla, se mantiene el último valor correcto, y cada pedido guarda el tipo de cambio del momento del pago, así que no le afectan los cambios posteriores.

      Pagos en moneda extranjera

      Cuando un módulo integrado, como comercio, envía un pedido en moneda extranjera, se cobra en esa moneda. Los métodos de pago que no admiten la moneda del pedido no aparecen en la pantalla de pago (los procesadores coreanos solo admiten KRW; PayPal admite 24 monedas principales). Los importes se muestran automáticamente con el símbolo y los decimales de cada moneda.

      Flujo de pago

      1. En el formulario de pedido del módulo integrado (comercio, etc.) se elige el método de pago y se pulsa Pagar.
      2. Tarjeta: autorización en la ventana de pago de Toss Payments → pantalla de resultado. / Transferencia bancaria: pantalla de resultado con los datos de la cuenta y el plazo de depósito → pagado cuando el administrador confirma el depósito.
      3. Los cambios de estado del pago se reflejan de inmediato en el módulo integrado y se verifican también por el webhook de la pasarela.

        4. Número de pedido y número de pago

        Ver dos números confunde al comprador, así que se muestran con esta regla.

        NúmeroLo emiteCómo se muestra
        Número de pedidoEl módulo que solicita el pago (comercio · reservas, etc.)Grande y como principal en la pantalla de pago, la de resultado y el historial
        Número de pagozittme PayPequeño, como dato secundario. Es la referencia para consultas de pago y cancelaciones

        Historial de pagos y cancelaciones

        • Historial de pagos: busca todos los pagos por estado · periodo · método de pago, y consulta en cada uno los datos de autorización, el número de pedido del módulo integrado y el historial de procesamiento.
        • Cancelación: desde cada pago ejecuta la cancelación total o parcial (si está permitida). Los pagos con tarjeta se cancelan a través de la pasarela, y las transferencias bancarias se registran como reembolso. El motivo se elige de la lista de motivos de la configuración.
        • Pagos que superaron el plazo de cancelación automática: se indica que se procesen como reembolso manual en lugar de cancelar en el procesador.
        • Registros: se guardan las solicitudes/respuestas de las pasarelas y los webhooks recibidos, y se depuran al pasar el tiempo de conservación. Consúltalos al investigar problemas de pago.

        Cómo leer los registros

        En la pestaña Registros se acumula en orden cronológico lo que se intercambió con el procesador de pagos. Si un pago falló o no se confirma un depósito, empieza por aquí.

        En la columna de respuesta aparece un resumen de una línea en lugar del original.

        • Si el procesador envió un motivo de fallo, se muestra ese texto tal cual. Por ejemplo, 카드 한도 초과 (límite de tarjeta excedido) o 유효하지 않은 카드번호 (número de tarjeta no válido).
        • En los pagos por transferencia bancaria se muestran ordenados la cuenta emitida · el nombre del depositante · el plazo de depósito.
        • Si no hay nada que resumir, se muestra el inicio del original recortado.

        Si necesitas el original completo, pasa el mouse sobre el resumen. Aparece la respuesta tal como la envió el procesador. Adjunta ese original cuando hagas una consulta.

        Si la respuesta está vacía, la solicitud no llegó al procesador. Revisa las credenciales en la pestaña Pasarelas y si el servidor bloquea las conexiones externas.

        Integración con módulos de terceros (desarrolladores)

        La convención para cobrar con zittme Pay desde otro módulo es sencilla.

        1. Al llamar a la creación del pago (createOrder), pasa el número de pedido de tu módulo en el parámetro source_code.
        2. Así, en la pantalla de pago, la de resultado y el historial de administración, ese número se muestra como "Número de pedido" principal, y el código de zittme Pay se muestra como "Número de pago".
        3. En las callbacks de pago completado y cancelación, actualiza el estado del pedido en tu módulo.

          4. Los módulos de comercio y reservas son las implementaciones de referencia de esta convención. Para las convenciones generales de desarrollo de módulos, consulta también el documento "Crear módulos" de la guía para desarrolladores.

          Preguntas frecuentes

          • El pago de prueba no funciona: revisa si está activado el modo de prueba y si las claves de Toss Payments son de prueba.
          • Los pedidos por transferencia bancaria siguen en pago pendiente: en las transferencias, el pago se completa cuando el administrador pulsa confirmar depósito. Si configuras un plazo de depósito, los pedidos abandonados sin depósito se limpian solos.
          • No veo el botón de cancelación parcial: si en la configuración está desactivado Permitir cancelación parcial, solo se puede cancelar el total.
          • Falla la cancelación de un pago con tarjeta antiguo: los pagos ya liquidados por el procesador no se pueden cancelar con tarjeta. Según el plazo de cancelación automática configurado, procésalo como reembolso manual.
          • No llegan los webhooks: revisa que las IP de la pasarela estén en la lista de IP permitidas para webhooks. Si la dejas vacía, se reciben sin límite.
          • Un método de pago nuevo no aparece en la pantalla de pago: solo aparece si lo activas en la pestaña Pasarelas e ingresas sus claves. Si las claves están vacías, no se muestra en la lista.
          • PayPal está inactivo: además del Client ID · Secret, debe estar registrado en el tipo de cambio común el tipo de la moneda de cobro (USD por defecto).
          • Cambio el skin de la pantalla de pago y vuelve al anterior: se corrigió en 0.2.0. Actualiza el módulo.
          • Al regresar después de pagar aparece "이 요청에 사용할 수 없는 HTTP 메소드입니다" (método HTTP no permitido para esta solicitud): pasa en 0.2.9 o anterior con procesadores como Conekta o PortOne, cuya ventana de pago va a otro sitio y regresa por GET. Desde 0.2.10 la callback acepta GET y POST, así que actualiza zittme Pay en Administración > Recursos. El pago en sí se procesó bien en el procesador, así que los pedidos con error quedan como autorizados si los vuelves a consultar en el historial de pagos.