Continue a grant request

The Grant Continuation Request API lets you continue an interactive grant request during or after user interaction.

An authorization server can require a user (typically the client’s end user) to approve the grant by interacting directly with the server. For example, by tapping an Approve button on a web page provided by the auth server. Outgoing payment grant requests require interactive grants.

After the grant is approved, the auth server sends the client an interaction reference (interact_ref). The client must send a continuation request containing the reference back to the auth server to obtain an access token.

Continue request timing

When a user completes the interaction with the identity provider, they should be redirected back to your client app. Now your client can make the grant continuation request. In scenarios where a user interface isn’t available, consider implementing a polling mechanism to check that the interaction has completed.

The code snippets below let an authorized client send a grant continuation request to an authorization server.

Before you begin

We recommend creating a wallet account on the test wallet. Creating an account allows you to test your client against the Open Payments APIs by using an ILP-enabled wallet funded with play money.

Issue grant continuation request

Authenticated client required

TypeScript/NodeJS

Prerequisites

Initial configuration

If you’re using JavaScript, only do the first step.

1. Add "type": "module" to package.json.

2. Add the following to tsconfig.json

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "ES2022"
     }
   }

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

// Initialize client
const client = await createAuthenticatedClient({
  walletAddressUrl: WALLET_ADDRESS,
  privateKey: PRIVATE_KEY_PATH,
  keyId: KEY_ID
})

// Continue grant
const grant = await client.grant.continue(
  {
    accessToken: CONTINUE_ACCESS_TOKEN,
    url: CONTINUE_URI
  },
  {
    interact_ref: interactRef
  }
)

// Check grant state
if (!isFinalizedGrant(grant)) {
  throw new Error('Expected finalized grant. Received non-finalized grant.')
}

// Output
console.log('OUTGOING_PAYMENT_ACCESS_TOKEN =', grant.access_token.value)
console.log(
  'OUTGOING_PAYMENT_ACCESS_TOKEN_MANAGE_URL =',
  grant.access_token.manage
)

For TypeScript, run tsx path/to/directory/index.ts. View full TS source

For JavaScript, run node path/to/directory/index.js. View full JS source

Rust

Prerequisites

// Import dependencies
use open_payments::client::AuthenticatedResources;
use open_payments::snippets::utils::{create_authenticated_client, get_env_var, load_env};
use open_payments::types::auth::ContinueResponse;

// Initialize client
let client = create_authenticated_client()?;

// Continue grant
let access_token = get_env_var("CONTINUE_ACCESS_TOKEN")?;
let continue_uri = get_env_var("CONTINUE_URI")?;
let interact_ref = get_env_var("INTERACT_REF")?;

let response = client
    .grant()
    .continue_grant(&continue_uri, &interact_ref, Some(&access_token))
    .await?;

// Output
match response {
    ContinueResponse::WithToken { access_token, .. } => {
        println!("Received access token: {:#?}", access_token.value);
        println!(
            "Received access token manage URL: {:#?}",
            access_token.manage
        );
    }
    ContinueResponse::Pending { .. } => {
        println!("Pending");
    }
}

View full source

PHP

Prerequisites

// Import dependencies
use OpenPayments\AuthClient;
use OpenPayments\Config\Config;

// Initialize client
$config = new Config(
    $WALLET_ADDRESS,
    $PRIVATE_KEY,
    $KEY_ID
);
$opClient = new AuthClient($config);

// Continue grant
$grant = $opClient->grant()->continue(
    [
        'access_token' => $CONTINUE_ACCESS_TOKEN,
        'url' => $CONTINUE_URI
    ],
    [
        'interact_ref' => $interactRef,
    ]
);

// Check grant state
if (!$grant instanceof \OpenPayments\Models\Grant) {
    throw new \Error('Expected finalized grant. Received non-finalized grant.');
}

// Output
echo 'OUTGOING_PAYMENT_GRANT_ACCES_TOKEN: ' . $grant->access_token->value . PHP_EOL;
echo 'OUTGOING_PAYMENT_ACCESS_TOKEN_MANAGE_URL: ' . $grant->access_token->manage . PHP_EOL;
echo 'GRANT OBJECT: ' . PHP_EOL . print_r($grant, true);

View full source

Go

Prerequisites

package main

// Import dependencies
import (
  "context"
  "encoding/json"
  "fmt"
  "log"

  op "github.com/interledger/open-payments-go"
)

func main() {
  // Initialize client
  client, err := op.NewAuthenticatedClient(WALLET_ADDRESS_URL, PRIVATE_KEY_BASE_64, KEY_ID)
  if err != nil {
    log.Fatalf("Error creating authenticated client: %v\n", err)
  }

  // Continue grant
  grant, err := client.Grant.Continue(context.TODO(), op.GrantContinueParams{
    URL:         CONTINUE_URI,
    AccessToken: CONTINUE_ACCESS_TOKEN,
    InteractRef: INTERACT_REF,
  })
  if err != nil {
    log.Fatalf("Error continuing grant: %v\n", err)
  }

  // Ensure the grant is finalized
  if grant.AccessToken == nil {
    log.Fatal("Expected finalized grant. Received non-finalized grant.")
  }

  // Output
  grantJSON, err := json.MarshalIndent(grant, "", "  ")
  if err != nil {
    log.Fatalf("Error marshaling grant: %v\n", err)
  }
  fmt.Println("GRANT:", string(grantJSON))
  fmt.Println("OUTGOING_PAYMENT_ACCESS_TOKEN =", grant.AccessToken.Value)
  fmt.Println("OUTGOING_PAYMENT_ACCESS_TOKEN_MANAGE_URL =", grant.AccessToken.Manage)
}

Java

Prerequisites

// Import dependencies
import org.interledger.openpayments.httpclient.OpenPaymentsHttpClient;
import org.interledger.openpayments.IOpenPaymentsClient;

// Initialize client
var client = OpenPaymentsHttpClient.defaultClient(
"WalletAddress",
"PrivateKeyPEM",
"KeyId"
);

// Get wallet addresses
var senderWallet = client.walletAddress().get("https://cloudninebank.example.com/customer");
var receiverWallet = client.walletAddress().get("https://cloudninebank.example.com/merchant");

// Create an incoming payment
var grantRequest = client.auth().grant().incomingPayment(receiverWallet);
var incomingPayment = client.payment().createIncoming(receiverWallet, grantRequest, BigDecimal.valueOf(11.25));

// Create a quote
var quoteRequest = client.auth().grant().quote(senderWallet);
var quote = client.quote().create(quoteRequest.getAccess().getToken(), senderWallet, incomingPayment, Optional.empty(), Optional.empty());

var urlToOpen = "https://example.com/redirect?paymentId=1234";

// Create an outgoing payment from quote
var opContinueInteract = client.auth().grant().continuation(
senderWallet,
quote.getDebitAmount(),
URI.create(urlToOpen),
"test"
);

// USER APPROVES REQUEST

// Finalize/continue grant request
var finalized = client.auth().grant().finalize(opContinueInteract, "Reference from USER interaction.");

// Output
log.info("FINALIZED: {}", finalized);

.NET

Prerequisites

// Import dependencies
using Microsoft.Extensions.DependencyInjection;
using OpenPayments.Sdk.Clients;
using OpenPayments.Sdk.Extensions;
using OpenPayments.Sdk.HttpSignatureUtils;

// Initialize client
var client = new ServiceCollection()
    .UseOpenPayments(opts =>
    {
        opts.UseAuthenticatedClient = true;
        opts.KeyId = CLIENT_ID;
        opts.PrivateKey = KeyUtils.LoadPem(CLIENT_SECRET);
        opts.ClientUrl = new Uri(CLIENT_WALLET_ADDRESS);
    })
    .BuildServiceProvider()
    .GetRequiredService<IAuthenticatedClient>();

// Continue grant
var grant = await client.ContinueGrantAsync(
    new AuthRequestArgs
    {
        Url = new Uri(CONTINUE_URI),
        AccessToken = CONTINUE_ACCESS_TOKEN,
    },
    new GrantContinueBody
    {
        InteractRef = interactRef,
    }
);

// Check grant state
if (grant.AccessToken == null)
    throw new Exception("Expected finalized grant. Received non-finalized grant.");

// Output
Console.WriteLine($"OUTGOING_PAYMENT_ACCESS_TOKEN = {grant.AccessToken.Value}");
Console.WriteLine($"OUTGOING_PAYMENT_ACCESS_TOKEN_MANAGE_URL = {grant.AccessToken.Manage}");

View full source

References

• API specification
• Grant negotiation and authorization