Continue a grant request

During a grant request flow, an authorization server can require an individual (typically a 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.

After the individual approves the grant, the auth server sends the client an interaction reference. The client must send a continuation request containing the reference back to the authorization server to obtain an access token.

These code snippets enable an authorized client to send a grant continuation request to the authorization server.

Continue request timing

After the user completes their interaction with the identity provider (IdP), they should be redirected back to your application. At this point, you can make the grant continuation request. In scenarios where a user interface is not available, consider implementing a polling mechanism to check for the completion of the interaction.

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

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.getWalletAddress("https://cloudninebank.example.com/customer");
var receiverWallet = client.getWalletAddress("https://cloudninebank.example.com/merchant");

// Create an incoming payment
var grantRequest = this.client.createGrantIncomingPayment(receiverWallet);
var incomingPayment = this.client.createIncomingPayment(receiverWallet, grantRequest, BigDecimal.valueOf(11.25));

// Create a quote
var quoteRequest = this.client.createGrantQuote(senderWallet);
var quote = this.client.createQuote(quoteRequest.getAccess().getToken(), senderWallet, incomingPayment);

var urlToOpen = "http://localhost:%d?paymentId=1234".formatted(port);

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

// USER APPROVES REQUEST

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

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

References

• API specification
• Grant negotiation and authorization