Obtener una concesión de pago saliente para pagos futuros

A menudo, una transacción comienza cuando el cliente obtiene los datos del destinatario y solicita permiso al ASE del destinatario para enviar dinero. Sin embargo, Open Payments también admite un enfoque distinto, en el cual el cliente obtiene permiso del ASE del remitente para enviar dinero antes de saber quién será el destinatario. El modelo “pague a medida que navega” de Web Monetization usa este enfoque.

En este modelo, un usuario instala una extensión del navegador y visita un sitio con monetización web. La extensión utiliza Open Payments para emitir pagos salientes continuos al sitio, en nombre del usuario, mientras el usuario permanezca en el sitio. La extensión no sabe quién será el destinatario hasta que el usuario visita el sitio.

Para configurar la extensión, el usuario debe conectarla a la cuenta de su billetera. Este indica un monto máximo que está dispuesto a gastar y elige si ese monto se renovará de manera mensual. Luego, la extensión recibe una concesión de pago saliente del proveedor de la billetera del usuario, lo que permite que la extensión inicie pagos futuros.

En esta guía, usted asume el rol de desarrollador de una aplicación. La guía lo conduce por los pasos que realizará su aplicación para recibir una concesión de pago saliente con un monto de débito especificado, pero sin destinatarios conocidos. La situación hipotética de ejemplo ilustra cómo permitir que el usuario de su aplicación envíe pagos de hasta CAD 100 por mes durante tres meses.

Dependencias

Kit de desarrollo de software (software development kit, SDK) de Open Payments

Puntos finales

Pasos

1. Obtener los datos de la dirección de billetera

Supongamos que su usuario guardó su dirección de billetera en el perfil de su cuenta al configurar la aplicación. Llame a la API Obtener dirección de billetera para obtener los datos necesarios sobre la cuenta de la billetera del usuario.

TypeScript/JavaScript

const userWalletAddress = await client.walletAddress.get({
  url: 'https://cloudninebank.example.com/user'
})

2. Solicitar una concesión de autorización interactiva para un pago saliente

Utilice la información del servidor de autorización recibida en el paso anterior para llamar a la API Solicitud de concesión. El propósito de esta llamada consiste en obtener un token que permita que el cliente solicite la creación de recursos de pago saliente en la cuenta de la billetera de su usuario.

Además de los parámetros requeridos, en la solicitud incluya lo siguiente:

Objeto limits
- debitAmount: el monto máximo que el usuario puede enviar por intervalo. Cuando comienza el siguiente intervalo, el valor se restablece.
- interval: el intervalo de tiempo durante el cual la concesión es válida.

El usuario indica que desea realizar pagos de hasta CAD 100 por mes durante tres meses. El monto se restablece todos los meses y las partes no utilizadas no se acumulan.

TypeScript/JavaScript

const grant = await client.grant.request(
  {
    url: userWalletAddress.authServer,
  },
  {
    access_token: {
      access: [
        {
          identifier: userWalletAddress.id,
          type: 'outgoing-payment',
          actions: ['read', 'create'],
          limits: {
            interval: 'R3/2025-05-20T13:00:00Z/P1M'
            debitAmount: {
              assetCode: 'CAD',
              assetScale: 2,
              value: '10000',
            },
          },
        },
      ],
    },
    client: userWalletAddress.id,
    interact: {
      start: ['redirect'],
      finish: {
        method: 'redirect',
        uri: 'https://cloudninebank.example.com/finish/T8jw5Xy',
        nonce: NONCE,
      },
    },
  },
);

Acerca del intervalo

El intervalo que se emplea en esta guía es R3/2025-05-20T13:00:00Z/P1M. Recuerde que el usuario desea enviar pagos de hasta CAD 100 por mes durante tres meses. El intervalo se desglosa del siguiente modo:

R[3]/ es la cantidad de repeticiones: tres.
2025-05-20 es la fecha de inicio del intervalo repetido: 20 de mayo de 2025.
T13:00:00Z/ es la hora de inicio del intervalo repetido: 1:00 p. m. UTC.
[P1M] es el período entre cada intervalo: un mes. Si se emplea con R[3], se obtiene una concesión válida una vez por mes durante tres meses.

En conjunto, el usuario puede enviar hasta CAD 100 en estos períodos:

De la 1 p. m. UTC del 20 de mayo de 2025 a las 12:59 p. m. UTC del 20 de junio de 2025.
De la 1 p. m. UTC del 20 de junio de 2025 a las 12:59 p. m. UTC del 20 de julio de 2025.
De la 1 p. m. UTC del 20 de julio de 2025 a las 12:59 p. m. UTC del 20 de agosto de 2025.

3. Comenzar la interacción con el usuario

Una vez que el cliente recibe la respuesta del servidor de autorización, debe enviar al usuario al URI de interact.redirect de la respuesta. Esto da comienzo al flujo de interacción.

La respuesta también incluye un objeto de continue, que es fundamental para gestionar la interacción y obtener el consentimiento explícito del usuario para concesiones de autorizaciones de pagos salientes. El objeto de continue contiene un token de acceso y un URI que el cliente usará para finalizar la solicitud de concesión de autorización después de que el usuario haya completado su interacción con el proveedor de identidad (Identity provider, IdP). Esto asegura que el cliente pueda obtener de manera segura los permisos necesarios para proceder con el proceso de pago.

{
  "interact": {
    "redirect": "https://auth.interledger-test.dev/4CF492MLVMSW9MKMXKHQ",
    "finish": "4105340a-05eb-4290-8739-f9e2b463bfa7"
  },
  "continue": {
    "access_token": {
      "value": "33OMUKMKSKU80UPRY5NM"
    },
    "uri": "https://auth.interledger-test.dev/continue/4CF492MLVMSW9MKMXKHQ",
    "wait": 30
  }
}

4. Finalizar la interacción con el usuario

El usuario interactúa con el servidor de autorización a través de la interfaz del servidor y aprueba o rechaza la concesión de autorización.

Siempre que el usuario apruebe la concesión de autorización, el servidor de autorización realiza lo siguiente:

Envía al usuario al finish.uri anteriormente definido por su cliente. La manera en que el servidor envía al usuario al URI está fuera de alcance, pero las opciones comunes incluyen redireccionar al usuario desde una página web y lanzar el navegador del sistema con la URI específica.
Asegura la redirección al agregar un hash único, lo que le permite a su cliente validar la llamada de finish, y una referencia de interacción como parámetros de consulta al URI.

5. Solicitar una continuación de la concesión de autorización

En esta guía, se supone que el IdP cuenta con una interfaz de usuario en la que el usuario interactúa. Cuando la interacción finaliza, el usuario regresa a su aplicación. Ahora el cliente puede realizar una solicitud de continuación de la concesión.

Agregue la interact_ref devuelta en los parámetros de consulta del URI de redirección.

TypeScript/JavaScript

const grant = await client.grant.continue(
  {
    accessToken: CONTINUE_ACCESS_TOKEN,
    url: CONTINUE_URI,
  },
  {
    interact_ref: INTERACT_REF,
  },
);

Una respuesta exitosa proporciona a su aplicación un token de acceso. Ahora su aplicación puede emitir solicitudes de pago saliente hacia destinatarios futuros en función de la concesión. Cada solicitud debe hacer referencia al token de acceso.