Saltar al contenido principal
Primeros pasosGuía

Un pago exitoso en sandbox es el punto de partida. Recorre estos cinco pasos con tus equipos de ingeniería y de operaciones antes de enviar transacciones reales.

Activa Live ModePublica una ruta de producciónVerifica los webhooksHaz un pago real y un reembolso
1

Activa Live Mode y cambia a las claves de producción

Tu organización empieza con acceso solo a Test Mode. Para obtener Live Mode, envía una solicitud de activación desde la página de inicio del dashboard. El estado de la organización cambia de “Inactive” a “Under Verification”, y Test Mode sigue disponible mientras Yuno verifica la cuenta. Consulta Entornos.Cuando Live Mode está habilitado:
  • Copia las claves de Live desde Developers. Yuno mantiene claves separadas para Test y Live. Consulta Credenciales de Developers.
  • Revisa el prefijo de la clave. Las claves de sandbox empiezan con sandbox_ y las de producción con prod_. El Yuno SDK elige el entorno a partir de este prefijo. Consulta Primeros pasos con el Yuno SDK.
  • Apunta tu servidor a la URL base de producción, que aparece en Developers.
  • Mantén la private-secret-key en tu servidor y fuera de lugares públicos, como un repositorio de GitHub. Consulta Autenticación.
2

Conecta un proveedor de producción y publica la ruta

El Yuno Test Payment Gateway funciona solo en sandbox, así que los pagos de producción necesitan una conexión con un proveedor real.
  1. Con el indicador de contexto en Live, abre Connections y conecta cada proveedor con el que vas a lanzar.
  2. Abre Routing y revisa la pestaña Not published. Ahí aparece cada método de pago que tiene una conexión pero no tiene ruta.
  3. Crea la ruta, agrega el paso del proveedor y haz clic en Publish. Consulta Routing.
  4. Abre Checkout builder, activa los métodos de pago que tienen una ruta publicada y haz clic en Publish settings. Los cambios quedan como Not published hasta que los publicas.
3

Configura el webhook de producción y los reintentos seguros

Confirma el resultado de cada pago en tu servidor, con un webhook o con la API de pagos, antes de entregar el pedido.
  • Configura un webhook de producción con una URL HTTPS pública que devuelva HTTP 200. Yuno reintenta una entrega que no recibe HTTP 200, así que el mismo evento puede llegar más de una vez. Los eventos de reembolso y de contracargo llevan el mismo data.payment.idempotency_key que su pago, así que registra cada evento procesado con su account_id, su type_event y su clave de idempotencia juntos, y omite un evento que ya esté registrado. Consulta Deduplicación.
  • Activa Use HMAC Authentication y verifica el encabezado x-hmac-signature contra el cuerpo sin procesar de la solicitud, antes de parsear el JSON, con el secreto configurado para ese webhook. Consulta Verificar firmas de webhook.
  • Envía un X-Idempotency-Key cuando crees un pago. Si el resultado no está claro (un timeout, un error de conexión o un 500), reintenta con la misma clave. Un 400 REQUEST_IN_PROCESS significa que la primera solicitud todavía se está ejecutando, así que reintenta con la misma clave después de unos segundos. Un 400 IDEMPOTENCY_DUPLICATED significa que no existe ningún pago para esa clave, así que corrige la solicitud y envíala con una clave nueva. Consulta Idempotencia.
  • Usa Retrieve payment para recuperar el estado de un pago cuando el resultado de un webhook o de una solicitud no está claro.
4

Decide sobre 3DS y tu alcance PCI

3D Secure. Tú decides si tus pagos con tarjeta usan 3DS2. El paso de 3DS se agrega a una ruta de Card antes del paso del proveedor, en Routing > Card Routes > 3DS Step. 3DS DIRECT también necesita datos del adquirente: un BIN de adquirente por marca de tarjeta, el ID de comercio, el MCC, el nombre y la URL del comercio, y el código de país. Consulta 3D Secure.PCI DSS. Con el Yuno SDK (o con los SDKs legacy Full, Lite o Secure Fields), los datos de la tarjeta van del navegador o de la app del cliente a Yuno y tus servidores solo reciben tokens, así que la mayoría de los comercios califica para SAQ A. Si tu servidor envía números de tarjeta sin procesar, como hace el workflow DIRECT del Quickstart, tus sistemas quedan dentro del alcance PCI DSS. Consulta Cumplimiento PCI.
5

Haz un pago real y un reembolso, y sigue los primeros pagos

Las tarjetas de prueba son del sandbox. En Live Mode, haz un pago de bajo monto con una tarjeta real a través de cada proveedor y método de pago que lances, y luego reembólsalo.
  • Reembolsa con Refund payments. Cada llamada de reembolso necesita un X-Idempotency-Key con un valor nuevo en cada intento. Espera a que un reembolso llegue a SUCCEEDED, DECLINED o ERROR antes de iniciar otro sobre la misma transacción.
  • Si un reembolso se confirma de inmediato o queda en PENDING, y si se permiten reembolsos parciales, depende del proveedor. Revisa el comportamiento de cada proveedor con el que lances.
  • Abre Payments en el dashboard en Live Mode para ver todos los pagos y transacciones, filtrarlos y exportar reportes. Consulta Payments.
  • Consulta el estado del servicio ante incidentes, y escribe a support@y.uno con el ID del pago cuando un resultado no coincida con lo que esperas.

Prueba más allá del camino feliz

Antes del lanzamiento, demuestra que tu aplicación maneja cada uno de estos casos. Usa el Yuno Testing Gateway en sandbox y las instrucciones de prueba de cada proveedor. Los resultados en sandbox no demuestran cómo se comporta cada proveedor en producción.

Siguientes pasos

  1. Solución de problemasReferencia La respuesta, su causa y la solución para los primeros errores de una integración nueva.
  2. WebhooksGuía Entrega, reintentos, deduplicación y las páginas para configurar y verificar un webhook.
  3. Flujo de pagoConcepto Cada paso de un pago, campo por campo.
  4. Crear pagoReferencia El esquema de la solicitud y de la respuesta de la llamada que crea un pago.