Saltar al contenido principal
Todos los sistemas operativosNovedadesv1
Iniciar sesión

API directa

Cree una experiencia de pago propiedad del comerciante con las API del servidor DEUNA.

Última actualización: October 12, 2026
En esta página
Método de integración

Controla la interfaz y coordina los pagos desde tu backend.

Crea el recorrido del cliente en tu aplicación y usa las API de DEUNA para operaciones de pagos, usuarios, tarjetas y orquestación.

Interfaz
Frontend y backend propiedad del comercio
Modelo de entrega
API servidor a servidor con soporte del cliente cuando sea necesario
Ideal para
Equipos que necesitan el máximo control del producto
Comparar métodosAbrir referencia

Utilice la API Direct cuando tu equipo gestiona la interfaz de pago y realiza llamadas a DEUNA desde un backend de comercio confiable. Tu cliente recopila o tokeniza el instrumento de pago, tu backend crea el pago, y ambas capas gestionan cualquier acción del cliente necesaria antes del estado final de pago.

Siga la ruta de integración.#

1. Configure el accesoSeleccione la clave pública, la clave privada y, opcionalmente, el token Bearer del cliente correctos.2. Prepare el entornoEstablezca las URLs base, Postman, acceso a la red, reintentos, límites de velocidad y tiempos de espera del cliente.3. Recopile los detalles del pagoTokenice los datos de la tarjeta o recopile los campos requeridos por el método de pago seleccionado.4. Cree el pagoImplemente la solicitud Purchase V2, las respuestas, los encabezados y el contrato de idempotencia.5. Maneje cada estadoImplemente las acciones del cliente, el procesamiento pendiente, el éxito, el rechazo, la captura, la anulación y el reembolso.6. Reconcilie las actualizacionesReciba notificaciones de estado asíncronas y confirme el estado autorizado del pedido.

1. Configure el comerciante y el entorno#

Antes de escribir la solicitud de pago:

  1. Complete configuración de cuenta y obtenga las credenciales para el entorno de sandbox.
  2. Leer Claves de autenticación y API para separar las credenciales públicas del cliente, las credenciales privadas del backend y, opcionalmente, la identidad del cliente.
  3. Configure al menos una conexión de pago y una estrategia de enrutamiento elegibles. Utilice Capacidades de proveedores para confirmar el soporte para país, método, moneda y operación, y revise Estrategias de pago.
  4. Aplique los requisitos de entorno y red compartidos en Fundamentos de integración de API.
  5. Clonar las plataformas compatibles Colección de Postman cuando se desea inspeccionar las solicitudes de sandbox antes de implementar un cliente.

Los entornos de sandbox y producción utilizan URLs, credenciales, conexiones de proveedores y datos de pago diferentes. No se deben mezclar recursos entre entornos.

2. Recopilar la información de pago de forma segura#

El comerciante posee la interfaz Direct API, pero el manejo de los datos de la tarjeta sigue dependiendo de su ámbito PCI.

  • Si el cliente debe evitar el manejo de los detalles de la tarjeta en el backend del comerciante, utilice la plataforma compatible Flujo de tokenización de tarjetas y enviar el token del método de pago resultante al backend.
  • Si el proveedor de prevención de fraude configurado requiere datos del navegador o del dispositivo, implemente Flujo de huella digital del dispositivo a través de la API.
  • Para las billeteras y métodos de pago alternativos, comience con Capacidades de proveedores, y luego siga la guía de conexión para los requisitos necesarios. payment_source, specific_fields, redirección, código QR, cupón o comportamiento de devolución de llamada.
  • Si ya existe un token de pedido, el backend puede recuperarlo y obtener su configuración. Métodos de pago antes de procesarlo.

3. Crear y procesar el pago#

Las nuevas integraciones deben comenzar con POST /v2/merchants/orders/purchase. Admite dos modelos de solicitud válidos:

ModeloCuando usarloDocumentación
Orden en línea · RecomendadoCrea el pedido y procesa su pago en una única solicitud de compra V2.Contrato de solicitud de pago y Ejemplos de la industria
Token de orden existente · OpcionalCrea el pedido solo cuando otro canal o experiencia lo requiera order_token antes del pago.Crear orden, luego Procesa el pedido existente

Usa la Ejemplo de pago sandbox para el flujo backend más corto. El catálogo de endpoints es el inventario oficial de las operaciones publicadas y sus llamadores compatibles.

Para cada solicitud de cambio de pago compatible, genere una X-Idempotency-Key en el backend. Utilice la misma clave y el cuerpo idéntico (byte por byte) al intentar de nuevo una solicitud incierta. Siga el procedimiento completo. de solicitudes idempotentes, incluyendo su período de retención y manejo de conflictos.

4. Maneja la respuesta y la acción del cliente#

Una respuesta HTTP 2xx significa que la solicitud de la API ha sido aceptada o procesada; no prueba por sí solo que se ha realizado un pago. Lee order.payment.data.status y cualquier acción posterior.

Elige el ciclo de vida que se adapte al método seleccionado:

Flujo con tarjetaManeja la compra, la autorización, la revisión de riesgos, el cobro, la anulación, la devolución y los estados finales de la tarjeta.3D seguroPresenta un desafío de API directo compatible y evalúa el estado de pago resultante.flujo de trabajo APMManeja las redirecciones, códigos QR, vales, confirmación bancaria, cancelación y expiración.

No uses una URL de retorno del navegador, callback del SDK o redirección del proveedor como prueba de pago. Mantén la ejecución bloqueada mientras el pago está pendiente, en proceso, en revisión o esperando la acción del cliente.

5. Confirma los resultados asíncronos#

Configurar webhooks de estado de pedido y pago para el comerciante y el entorno. Verifica la firma, acepta la entrega repetida de forma idempotente y confirma la solicitud antes de ejecutar la lógica empresarial lenta.

Cuando la respuesta sincrónica se pierde o una notificación se retrasa, recupera el pedido original con GET /merchants/orders/{order_token}. Reconcilia el estado de pago recuperado antes de la ejecución o antes de crear un intento nuevo.

Para los tiempos de espera de la red, sigue Gestión de tiempos de espera del cliente. Un tiempo de espera del cliente no significa que el pago haya fallado.

6. Implementa operaciones post-pago#

Solo expone las operaciones compatibles con la conexión y el estado de pago actual:

CapturaCobra todo o parte de una autorización elegible.AnulaciónLibera una autorización elegible antes de cobrar.ReembolsoCrea un reembolso completo o parcial para un pago procesado.

Para un comportamiento de operación avanzado, continúa con Múltiples cobros parciales, Múltiples reembolsos parcialesy reembolsos asíncronos.

Lista de verificación de preparación para la producción#

  • Las claves privadas se almacenan solo en la configuración backend protegida y se eliminan de los registros.
  • Los credenciales sandbox y de producción, las URLs base, las conexiones y los datos están aislados.
  • Se implementa cada acción del cliente Estado del pago y requerido.
  • El backend conserva los identificadores de pedido, los cuerpos de solicitud y las claves idempotentes para la recuperación.
  • Se prueban las firmas de webhook, la entrega duplicada, la entrega retrasada y las actualizaciones fuera de orden.
  • El comportamiento del tiempo de espera del cliente sigue el acuerdo modelo de tiempo de espera y reconciliación.
  • 429 y los errores de la plataforma siguen guía de límites de velocidad y la Referencia de error.
  • Los controles de captura, cancelación y reembolso solo se muestran cuando están soportados por la conexión y el estado actual.
  • Los escenarios de éxito, denegación, 3DS, pendiente, timeout, reintento y fallo del proveedor son certificados antes de la producción.