Create an incoming payment grant request

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

The snippets below enable a client to request a grant for an incoming payment. The request to the authorization server must indicate the incoming-payment and the actions the client wants to take at the resource 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.

Request an incoming payment grant

TypeScript/JavaScript

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! Copy import { createAuthenticatedClient } from "@interledger/open-payments";

Initialize Open Payments client

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

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

Get wallet address information

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

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

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! Copy const grant = await client.grant.request( { url: walletAddress.authServer, }, { access_token: { access: [ { type: "incoming-payment", actions: ["list", "read", "read-all", "complete", "create"], }, ], }, }, );

Check grant state

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

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

Output

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

Copied! Copy console.log("INCOMING_PAYMENT_ACCESS_TOKEN =", grant.access_token.value); console.log( "INCOMING_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::api::UnauthenticatedResources;
use open_payments::client::AuthenticatedResources;
use open_payments::snippets::utils::{create_authenticated_client, get_env_var, load_env};
use open_payments::types::auth::{
    AccessItem, AccessTokenRequest, GrantRequest, GrantResponse, IncomingPaymentAction,
};

Copied! Copy use open_payments::client::api::UnauthenticatedResources; use open_payments::client::AuthenticatedResources; use open_payments::snippets::utils::{create_authenticated_client, get_env_var, load_env}; use open_payments::types::auth::{ AccessItem, AccessTokenRequest, GrantRequest, GrantResponse, IncomingPaymentAction, };

Initialize Open Payments client

// Authenticated client can be also used for unauthenticated resources
let client = create_authenticated_client()?;

Copied! Copy // Authenticated client can be also used for unauthenticated resources let client = create_authenticated_client()?;

Get wallet address information

let wallet_address_url = get_env_var("WALLET_ADDRESS_URL")?;
let wallet_address = client.wallet_address().get(&wallet_address_url).await?;

Copied! Copy let wallet_address_url = get_env_var("WALLET_ADDRESS_URL")?; let wallet_address = client.wallet_address().get(&wallet_address_url).await?;

Request incoming payment grant

let grant_request = GrantRequest::new(
    AccessTokenRequest {
        access: vec![AccessItem::IncomingPayment {
            actions: vec![
                IncomingPaymentAction::Create,
                IncomingPaymentAction::Read,
                IncomingPaymentAction::ReadAll,
                IncomingPaymentAction::List,
                IncomingPaymentAction::Complete,
            ],
            identifier: None,
        }],
    },
    None,
);

println!(
    "Grant request JSON: {}",
    serde_json::to_string_pretty(&grant_request)?
);

let response = client
    .grant()
    .request(&wallet_address.auth_server, &grant_request)
    .await?;

Copied! Copy let grant_request = GrantRequest::new( AccessTokenRequest { access: vec![AccessItem::IncomingPayment { actions: vec![ IncomingPaymentAction::Create, IncomingPaymentAction::Read, IncomingPaymentAction::ReadAll, IncomingPaymentAction::List, IncomingPaymentAction::Complete, ], identifier: None, }], }, None, ); println!( "Grant request JSON: {}", serde_json::to_string_pretty(&grant_request)? ); let response = client .grant() .request(&wallet_address.auth_server, &grant_request) .await?;

Output

match response {
    GrantResponse::WithToken { access_token, .. } => {
        println!("Received access token: {:#?}", access_token.value);
        println!(
            "Received access token manage URL: {:#?}",
            access_token.manage
        );
    }
    GrantResponse::WithInteraction { .. } => {
        unreachable!("Interaction not required for incoming payments");
    }
}

Copied! Copy match response { GrantResponse::WithToken { access_token, .. } => { println!("Received access token: {:#?}", access_token.value); println!( "Received access token manage URL: {:#?}", access_token.manage ); } GrantResponse::WithInteraction { .. } => { unreachable!("Interaction not required for incoming payments"); } }

View full Rust source

PHP

Prerequisites

Import dependencies

use OpenPayments\AuthClient;
use OpenPayments\Config\Config;

Copied! Copy use OpenPayments\AuthClient; use OpenPayments\Config\Config;

Initialize Open Payments client

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

Copied! Copy $config = new Config($WALLET_ADDRESS, $PRIVATE_KEY, $KEY_ID); $opClient = new AuthClient($config);

Get wallet address information

$wallet = $opClient->walletAddress()->get([
  "url" => $config->getWalletAddressUrl(),
]);

Copied! Copy $wallet = $opClient->walletAddress()->get([ "url" => $config->getWalletAddressUrl(), ]);

Request incoming payment grant

$grant = $opClient->grant()->request(
  [
    "url" => $wallet->authServer,
  ],
  [
    "access_token" => [
      "access" => [
        [
          "type" => "incoming-payment",
          "actions" => ["read", "complete", "create", "list"],
        ],
      ],
    ],
    "client" => $config->getWalletAddressUrl(),
  ],
);

Copied! Copy $grant = $opClient->grant()->request( [ "url" => $wallet->authServer, ], [ "access_token" => [ "access" => [ [ "type" => "incoming-payment", "actions" => ["read", "complete", "create", "list"], ], ], ], "client" => $config->getWalletAddressUrl(), ], );

Check grant state

if (!$grant instanceof \OpenPayments\Models\Grant) {
  throw new \Error("Expected non-interactive grant");
}

Copied! Copy if (!$grant instanceof \OpenPayments\Models\Grant) { throw new \Error("Expected non-interactive grant"); }

Output

$output->writeln("INCOMING_PAYMENT_GRANT: " . $grant->access_token->value);
$output->writeln(
  "INCOMING_PAYMENT_ACCESS_TOKEN_MANAGE_URL = " . $grant->access_token->manage,
);

Copied! Copy $output->writeln("INCOMING_PAYMENT_GRANT: " . $grant->access_token->value); $output->writeln( "INCOMING_PAYMENT_ACCESS_TOKEN_MANAGE_URL = " . $grant->access_token->manage, );

*/}

View full source

References

• API specification
• Grant negotiation and authorization