Flujos y arquitectura de Open Payments explicados paso a paso

Domina Open Payments con una visión clara y accionable: desde quién es quién en la arquitectura hasta cómo crear direcciones de billetera, pagos entrantes, cotizaciones y pagos salientes con consentimiento interactivo. Aquí entenderás los campos clave, el rol de cada servidor y el lenguaje común que hace interoperables los métodos de pago.

¿Qué arquitectura y roles componen Open Payments?

Open Payments se apoya en tres actores y cuatro servicios bajo la entidad que administra la cuenta. Este mapa mental te guía por los flujos sin perderte en detalles.

• Aplicación cliente: inicia solicitudes y consume la API.
• Usuario o cliente: se autentica y otorga consentimiento.
• Entidad que administra la cuenta: paraguas que integra cuatro piezas.
• Servidor de direcciones de billetera (wallet address server): guarda información de direcciones. Una dirección es un alias de cuenta y un endpoint para consultar datos.
• Servidor de recursos (resource server): almacena recursos de API: pagos entrantes, cotizaciones y pagos salientes.
• Servidor de autorización (authorization server): otorga permisos a la aplicación cliente para crear y acceder a recursos.
• Proveedor de identidad (identity provider, IdP): verifica que el usuario es quien dice ser cuando da su consentimiento.

La dirección es una URL que mejora visibilidad e interacción: un enlace simple y cliqueable. Al consultarla, devuelve datos básicos como moneda y las URLs de servidores de autorización y recursos. Este endpoint es público porque es el punto de inicio del sistema.

¿Cómo operan direcciones, pagos entrantes y cotizaciones?

Este bloque reúne los flujos más usados: dirección de billetera, creación de pagos entrantes y generación de cotizaciones.

¿Qué es una dirección de billetera y para qué sirve?

• Alias de cuenta y punto de consulta. Una dirección concentra identidad y descubrimiento de servicios.
• Punto público de arranque. Expone moneda y URLs de servidores relevantes.
• Mejor experiencia. Sustituye números largos por enlaces compartibles.

¿Cómo se crea un pago entrante y qué modalidades existen?

El pago entrante se crea del lado del receptor. Flujo resumido:

1. La aplicación cliente pide permiso al authorization server del receptor.
2. Si se aprueba, recibe un ** access token**.
3. Con el token, crea el pago entrante en el resource server.

Modalidades del pago entrante: - ** FixReceive: el receptor recibe una cantidad exacta. - ** FixSend: el remitente envía una cantidad fija y el receptor recibe lo que llegue tras comisiones.

Campos clave para la solicitud del pago entrante: - ** wallet address: la URL del receptor. - ** incoming amount: valor, moneda y escala (por ejemplo, 2). - ** expires_at: fecha de expiración. - ** metadata: descripción, por ejemplo “invoice número 76”.

Ejemplo ilustrativo de solicitud:

{
  "wallet_address": "https://example.com/receptor",
  "incoming_amount": {
    "value": "1000",
    "currency": "USD",
    "scale": 2
  },
  "expires_at": "2025-12-31T23:59:00Z",
  "metadata": {
    "description": "invoice número 76"
  }
}

La respuesta del pago entrante incluye: - Tipo de pago esperado. - Método de pago: efectivo, tarjeta de crédito, débito, transferencia, tarjeta de regalo o móvil.

Open Payments actúa como traductor universal: distintos métodos de pago “hablan un mismo lenguaje”.

¿Cómo se gestionan las cotizaciones del lado remitente?

La cotización se crea del lado del remitente para saber cuánto costará el pago.

1. El cliente pide acceso al authorization server y recibe un ** access token**.
2. Con el token, crea la cotización en el resource server.

La respuesta incluye: monto total, comisiones e ID de la cotización.

Campos clave de la cotización: - ** wallet address: URL del remitente. - receiver: URL de la otra billetera. - method: por ejemplo, ILP o protocolo Interledger.

Ejemplo ilustrativo de solicitud y respuesta mínima:

// Solicitud
{
  "wallet_address": "https://example.com/remitente",
  "receiver": "https://example.com/receptor",
  "method": "ILP"
}

// Respuesta
{
  "quote_id": "q-12345",
  "total_amount": "1030",
  "fees": "30"
}

¿Cómo funciona la concesión y el pago saliente con consentimiento?

El flujo de pagos salientes se basa en una concesión con interacción del usuario. No es obligatorio especificar datos del destinatario al crear la concesión, pero es opcional para fijar límites y valores del receptor.

¿Qué pasos sigue la concesión interactiva?

• La aplicación cliente realiza una solicitud de concesión para el pago saliente.
• El ASK devuelve una URL de redirección para la interacción.
• Se redirige al ** IdP** para autenticación y consentimiento del usuario.
• La concesión queda en espera hasta que el usuario complete la interacción.
• Se reanuda la solicitud original o se consulta el punto final de continuación para finalizar en segundo plano.
• Si todo es correcto, el authorization server entrega un ** access token**.
• Con el token, el cliente crea el pago saliente en el resource server.
• En ese momento, la entidad del remitente y la del receptor liquidan el pago.

¿Qué habilidades y conceptos aplicarás al implementar?

• Modelar recursos de API: pagos entrantes, cotizaciones y pagos salientes.
• Gestionar ** access tokens y permisos con el authorization server.
• Diseñar concesiones con consentimiento interactivo mediante redirección al IdP.
• Diferenciar ** FixReceive y ** FixSend para definir montos.
• Configurar ** metadata, descripciones e ** expires_at para control operativo.
• Interpretar montos totales, comisiones e IDs de cotización.
• Usar métodos de pago heterogéneos bajo un mismo lenguaje, incluido ILP/Interledger.
• Exponer una dirección como URL pública para descubrimiento de moneda y endpoints de servicios.

¿Te quedaron preguntas o quieres ver más casos prácticos en el backend? Déjalas en los comentarios: estaré atenta para ayudarte a afianzar estos flujos y pasar a “ensuciarnos las manos” con código.