Configuración de cliente Node.js para la API de Open Payments

Crear un cliente robusto en Node.js para integrar la API de Open Payments es más simple de lo que parece si dominas los conceptos clave: recursos protegidos por concesiones, flujo de pago entre pares y manejo seguro de llaves. Aquí se explica, con claridad y foco práctico, cómo preparar tu entorno, instalar dependencias y configurar un cliente autenticado.

¿Qué es Open Payments y cómo funcionan sus recursos y concesiones?

Open Payments es un estándar de API que permite a terceros acceder de forma segura a billeteras digitales para consultar cuentas e iniciar pagos. Los endpoints exponen recursos protegidos por concesiones: dirección de billetera, pagos entrantes, cotizaciones y pagos salientes.

• Dirección de billetera: representa una cuenta de usuario como si fuera un correo electrónico.
• Pagos entrantes: fondos que recibe el destinatario.
• Cotización: costo de ingresar un pago entrante.
• Pago saliente: envío desde un remitente hacia un pago entrante.
• Concesiones: definen el acceso detallado de terceros a cada recurso.

¿Cuál es el flujo de pago entre pares?

Para un pago entre pares se sigue un proceso escalonado que requiere autorizaciones:

• Crear un pago entrante en la dirección de la billetera del destinatario.
• Crear una cotización en la dirección de la billetera del remitente.
• Crear un pago saliente en la dirección de la billetera del remitente.
• Debido a las concesiones, se necesitan autorizaciones previas para cada paso: de 3 pasos pasan a 6 con autorizaciones, y a 8 incluyendo validaciones.

¿Qué necesitas para crear un cliente en Node.js?

El cliente puede ser un e-commerce o una app financiera: cualquier software que integre la API de Open Payments para realizar solicitudes seguras. La clave está en gestionar correctamente una dirección de billetera pública, un par de llaves y el key ID.

¿Dónde obtener la dirección de billetera y llaves?

Todo se gestiona desde la test wallet de Interledger. Allí configuras cuentas y llaves de desarrollador.

• Direcciones de billetera: se toman de la test wallet.
• Ejemplos de alias: cliente “MBR”, remitente “Alicia Test”, receptor “Bob Test”.
• Generación de llaves: en configuración, llaves de desarrollador, cuenta en USD, generar llave pública y privada.
• Asigna un nombre: por ejemplo, “Tutorial cliente”.
• Copia la llave privada y guárdala en un archivo llamado private.key en tu proyecto.
• Obtén el key ID desde la test wallet y consérvalo para la configuración del cliente.

¿Qué versiones y herramientas recomienda?

• Usa Node.js en versión 22 LTS. Vida útil declarada hasta 2027.
• Editor recomendado: Visual Studio Code.
• Recursos de referencia: openpayments.dev, nodejs.org, wallet.interledger-test.dev y el repositorio en GitHub open-payments-example.

¿Cómo iniciar el proyecto y configurar el cliente autenticado?

Alista la carpeta del proyecto en tu equipo, abre una terminal en Visual Studio Code y crea la base del cliente. La instalación de la biblioteca oficial simplifica la firma y la autenticación.

¿Cómo preparar el entorno y dependencias?

• Verifica la versión de Node: debe ser 22 LTS.
• Inicializa el proyecto y crea package.json.
• Instala la biblioteca de Open Payments.

# Inicializar el proyecto
npm init -g

# Instalar la biblioteca oficial
npm install @interledger/open-payments

• Crea el archivo principal: index.js.
• Crea el archivo de la llave privada: private.key.

¿Cómo estructurar el archivo index.js y cargar la clave privada?

Importa dependencias, lee la llave privada y crea el cliente autenticado con los datos de tu test wallet.

import { createAuthenticatedClient } from '@interledger/open-payments'
import fs from 'fs'

// Cargar la llave privada desde el archivo
const privateKey = fs.readFileSync('private.key', 'utf-8')

// Instanciar el cliente autenticado
const client = await createAuthenticatedClient({
  walletAddress: '',
  privateKey,
  keyId: ''
})

// Direcciones de ejemplo tomadas de la test wallet
const remitente = ''
const receptor = ''

• Revisa con cuidado llaves, comas y cierres de objeto: evita errores de sintaxis.
• Si aparece un error, valida la configuración: walletAddress, privateKey, keyId.
• Recuerda que la biblioteca ya incluye la lógica de firma por defecto.

¿Cómo se conectan las piezas para el pago entre pares?

Con el cliente autenticado y las direcciones definidas, podrás implementar los tres pasos del flujo: crear pago entrante, cotización y pago saliente. Por las concesiones, planifica las autorizaciones previas y suma validaciones para llegar a los ocho pasos operativos.

¿Quieres que profundicemos en la creación de pagos entrantes, cotizaciones o pagos salientes en Node.js? Deja tus comentarios y cuéntanos qué necesitas ver en código a continuación.