Skip to content
GitHub

Create a grant request

Before a client can call most of the Open Payments APIs, it must receive a grant from the appropriate authorization server.

The request to the authorization server must indicate the access type (incoming-payment, quote, or outgoing-payment) and actions the client wants to take at the resource server.

The snippets below enable a client to request a grant for each resource type.

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.

Request an incoming payment grant

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";
Copied!

Initialize Open Payments client

const client = await createAuthenticatedClient({
  walletAddressUrl: WALLET_ADDRESS,
  privateKey: PRIVATE_KEY_PATH,
  keyId: KEY_ID,
});
Copied!

Get wallet address information

const walletAddress = await client.walletAddress.get({
  url: WALLET_ADDRESS,
});
Copied!

Request incoming payment grant

const grant = await client.grant.request(
  {
    url: walletAddress.authServer,
  },
  {
    access_token: {
      access: [
        {
          type: "incoming-payment",
          actions: ["list", "read", "read-all", "complete", "create"],
        },
      ],
    },
  },
);
Copied!

Check grant state

if (isPendingGrant(grant)) {
  throw new Error("Expected non-interactive grant");
}
Copied!

Output

console.log("INCOMING_PAYMENT_ACCESS_TOKEN =", grant.access_token.value);
console.log(
  "INCOMING_PAYMENT_ACCESS_TOKEN_MANAGE_URL = ",
  grant.access_token.manage,
);
Copied!

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

Request a quote grant

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";
Copied!

Initialize Open Payments client

const client = await createAuthenticatedClient({
  walletAddressUrl: WALLET_ADDRESS,
  privateKey: PRIVATE_KEY_PATH,
  keyId: KEY_ID,
});
Copied!

Get wallet address information

const walletAddress = await client.walletAddress.get({
  url: WALLET_ADDRESS,
});
Copied!

Request quote grant

const grant = await client.grant.request(
  {
    url: walletAddress.authServer,
  },
  {
    access_token: {
      access: [
        {
          type: "quote",
          actions: ["create", "read", "read-all"],
        },
      ],
    },
  },
);
Copied!

Check grant state

if (isPendingGrant(grant)) {
  throw new Error("Expected non-interactive grant");
}
Copied!

Output

console.log("QUOTE_ACCESS_TOKEN =", grant.access_token.value);
console.log("QUOTE_ACCESS_TOKEN_MANAGE_URL = ", grant.access_token.manage);
Copied!

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

Request an outgoing payment grant

In Open Payments, outgoing payments require explicit consent, usually by the client’s user, before a grant can be issued. Consent is obtained through an interactive grant.

Open Payments also requires any authorization server that issues interactive grants to integrate with an identity provider (IdP). When the client requests the outgoing payment grant, the authorization server provides the client with the IdP URI the client should redirect to.

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";
Copied!

Initialize Open Payments client

const client = await createAuthenticatedClient({
  walletAddressUrl: WALLET_ADDRESS,
  privateKey: PRIVATE_KEY_PATH,
  keyId: KEY_ID,
});
Copied!

Get wallet address information

const walletAddress = await client.walletAddress.get({
  url: WALLET_ADDRESS,
});
Copied!

Request outgoing payment grant

const grant = await client.grant.request(
  {
    url: walletAddress.authServer,
  },
  {
    access_token: {
      access: [
        {
          identifier: walletAddress.id,
          type: "outgoing-payment",
          actions: ["list", "list-all", "read", "read-all", "create"],
          limits: {
            debitAmount: {
              assetCode: quote.debitAmount.assetCode,
              assetScale: quote.debitAmount.assetScale,
              value: quote.debitAmount.value,
            },
          },
        },
      ],
    },
    interact: {
      start: ["redirect"],
      finish: {
        method: "redirect",
        uri: "http://localhost:3344",
        nonce: NONCE,
      },
    },
  },
);
Copied!

Check grant state

if (!isPendingGrant(grant)) {
  throw new Error("Expected interactive grant");
}
Copied!

Output

console.log("Please interact at the following URL:", grant.interact.redirect);
console.log("CONTINUE_ACCESS_TOKEN =", grant.continue.access_token.value);
console.log("CONTINUE_URI =", grant.continue.uri);
Copied!

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

References