Verificar la titularidad de una dirección de billetera
Última revisión: 30 oct 2026
En Open Payments, las concesiones interactivas se utilizan con mayor frecuencia para obtener el consentimiento explícito antes de emitir un pago saliente. Las concesiones interactivas también se pueden usar para verificar que un usuario tiene acceso a su billetera sin realizar un pago. Un caso de uso, por ejemplo, es permitir que los usuarios se autoricen a sí mismos en una plataforma.
La verificación de que el usuario correcto tiene acceso a una dirección de billetera específica se realiza a través de un flujo de autenticación interactivo. En lugar de solicitar una concesión para realizar o recibir pagos (lo que requiere un access_token con permisos como outgoing-payment o incoming-payment), un cliente puede solicitar una concesión dirigida a un subject específico.
El servidor de autorización interactúa con el usuario a través del proveedor de identidad (IdP) para confirmar su identidad. El IdP verifica que el usuario tenga acceso a la dirección de billetera proporcionada en el campo subject.
Caso hipotético
Sección titulada «Caso hipotético»Para esta guía, asumirá el rol de un desarrollador de aplicaciones que trabaja para una plataforma de pagos. Su objetivo es garantizar que cada nuevo usuario tenga acceso a la dirección de billetera que proporciona al registrarse.
La guía explica cómo verificar que un nuevo usuario tiene acceso a la dirección de billetera https://cloudninebank.example.com/user utilizando una concesión basada en sujetos.
Puntos finales
Sección titulada «Puntos finales»- GET Get Wallet Address
- POST Grant Request
- POST Grant Continuation Request
1. Obtener los datos de la dirección de billetera
Sección titulada «1. Obtener los datos de la dirección de billetera»Primero, llame a la GET Get Wallet Address API para la dirección de billetera proporcionada por el usuario.
const userWalletAddress = await client.walletAddress.get({ url: 'https://cloudninebank.example.com/user'})let user_wallet_address = client .wallet_address() .get("https://cloudninebank.example.com/user") .await?;$userWalletAddress = $client->walletAddress()->get([ 'url' => 'https://cloudninebank.example.com/user']);userWalletAddress, err := client.WalletAddress.Get(context.TODO(), op.WalletAddressGetParams{ URL: "https://cloudninebank.example.com/user",})if err != nil { log.Fatalf("Error fetching user wallet address: %v\n", err)}coming sooncoming soonEjemplo de respuesta
{ "id": "https://cloudninebank.example.com/user", "assetCode": "CAD", "assetScale": 2, "authServer": "https://auth.cloudninebank.example.com/", "resourceServer": "https://cloudninebank.example.com/op"}2. Solicitar una concesión de autorización interactiva para un pago saliente
Sección titulada «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 POST Grant Request API.
Proporcione un subject con la dirección de la billetera en la lista de ID de sujetos.
Ejemplo de respuesta
{ "interact": { "redirect": "https://auth.cloudninebank.example.com/{...}", // uri to redirect the user to, to begin interaction "finish": "..." // unique key to secure the callback }, "continue": { "access_token": { "value": "..." // access token for continuing the outgoing payment grant request }, "uri": "https://auth.cloudninebank.example.com/continue/{...}", // uri for continuing the outgoing payment grant request "wait": 30 }}A continuación, se explica cómo especificar la estructura subject en su solicitud de concesión:
const grant = await client.grant.request( { url: userWalletAddress.authServer }, { subject: { sub_ids: [ { id: userWalletAddress.id, format: 'uri' } ] }, client: userWalletAddress.id, interact: { start: ['redirect'], finish: { method: 'redirect', uri: 'https://paymentplatform.example/finish/{...}', // where to redirect the user to after they've completed the interaction nonce: NONCE } } })let grant_request = GrantRequest::subject_only( Subject { sub_ids: vec![SubjectIdentifier { id: user_wallet_address.id.clone(), format: SubjectIdentifierFormat::Uri, }], }, Some(InteractRequest { start: vec!["redirect".to_string()], finish: Some(InteractFinish { method: "redirect".to_string(), uri: "https://paymentplatform.example/finish/{...}".to_string(), nonce: NONCE.to_string(), }), }),);
let pending_grant = client .grant() .request(&user_wallet_address.auth_server, &grant_request, None) .await?;$pendingGrant = $client->grant()->request( [ 'url' => $userWalletAddress->authServer, ], [ 'subject' => [ 'sub_ids' => [ [ 'id' => $userWalletAddress->id, 'format' => 'uri', ], ], ], 'client' => $userWalletAddress->id, 'interact' => [ 'start' => ['redirect'], 'finish' => [ 'method' => 'redirect', 'uri' => 'https://paymentplatform.example/finish/{...}', // where to redirect the user to after they've completed the interaction 'nonce' => NONCE, ], ], ],);var requestBody as.GrantRequestif err := requestBody.FromGrantRequestWithSubject(as.GrantRequestWithSubject{ Subject: as.Subject{ SubIds: []struct { Format as.SubjectSubIdsFormat `json:"format"` Id string `json:"id"` }{ {Format: as.Uri, Id: *userWalletAddress.Id}, }, }, Interact: as.InteractRequest{ Start: []as.InteractRequestStart{as.InteractRequestStartRedirect}, Finish: &struct { Method as.InteractRequestFinishMethod `json:"method"` Nonce string `json:"nonce"` Uri string `json:"uri"` }{ Method: as.InteractRequestFinishMethodRedirect, Uri: "https://paymentplatform.example/finish/{...}", // where to redirect the user to after they've completed the interaction Nonce: NONCE, }, },}); err != nil { log.Fatalf("Error building subject grant request: %v\n", err)}
pendingGrant, err := client.Grant.Request(context.TODO(), op.GrantRequestParams{ URL: *userWalletAddress.AuthServer, RequestBody: requestBody,})if err != nil { log.Fatalf("Error requesting subject verification grant: %v\n", err)}coming sooncoming soon3. Comenzar la interacción con el usuario
Sección titulada «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.
4. Finalizar la interacción con el usuario
Sección titulada «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.urianteriormente 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
Sección titulada «5. Solicitar una continuación de la concesión de autorización»Una vez que el usuario complete la interacción y sea redirigido de nuevo a su aplicación, llame a la POST Grant Continuation Request API para finalizar la verificación.
Emita la solicitud al continue.uri proporcionado en la respuesta de concesión de pago saliente inicial (paso 2).
Incluya la interact_ref devuelta en los parámetros de consulta del URI de redirección.
const userVerificationGrant = await client.grant.continue( { accessToken: pendingGrant.continue.access_token.value, url: pendingGrant.continue.uri }, { interact_ref: interactRef })let GrantResponse::WithInteraction { continue_, .. } = pending_grant else { eprintln!("Expected interactive grant"); return Ok(());};
let user_verification_grant = client .grant() .continue_grant( &continue_.uri, &interact_ref, Some(&continue_.access_token.value), ) .await?;$userVerificationGrant = $client->grant()->continue( [ 'access_token' => $pendingGrant->continue->access_token->value, 'url' => $pendingGrant->continue->uri, ], [ 'interact_ref' => $interactRef, ],);userVerificationGrant, err := client.Grant.Continue(context.TODO(), op.GrantContinueParams{ URL: pendingGrant.Continue.Uri, AccessToken: pendingGrant.Continue.AccessToken.Value, InteractRef: INTERACT_REF,})if err != nil { log.Fatalf("Error continuing grant: %v\n", err)}coming sooncoming soonEjemplo de respuesta
{ "access_token": { "value": "...", // final access token "manage": "https://auth.cloudninebank.example.com/token/{...}" // management uri for the access token }, "continue": { "access_token": { "value": "..." }, "uri": "https://auth.cloudninebank.example.com/continue/{...}" }}Si la solicitud de continuación se completa con éxito y devuelve los detalles del token de acceso, el proveedor de identidad (IdP) habrá verificado satisfactoriamente que el usuario es propietario de la dirección de billetera especificada.