Create an incoming payment

Once an authorized client obtains the requisite grant from the recipient’s authentication server, the client must create an incoming payment resource before any payments can be sent to the recipient’s wallet address.

These code snippets create an incoming payment of $10 USD at a given wallet address, allowing subsequent payments to be sent to that wallet address up to $10 USD.

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.

Create an incoming payment resource

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
})

// Get wallet address information
const walletAddress = await client.walletAddress.get({
  url: WALLET_ADDRESS
})

// Create incoming payment
const incomingPayment = await client.incomingPayment.create(
  {
    url: walletAddress.resourceServer,
    accessToken: INCOMING_PAYMENT_ACCESS_TOKEN
  },
  {
    walletAddress: WALLET_ADDRESS,
    incomingAmount: {
      value: '1000',
      assetCode: 'USD',
      assetScale: 2
    },
    expiresAt: new Date(Date.now() + 60_000 * 10).toISOString()
  }
)

// Output
console.log('INCOMING_PAYMENT_URL =', incomingPayment.id)

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::AuthenticatedResources;
use open_payments::client::api::UnauthenticatedResources;
use open_payments::client::utils::get_resource_server_url;
use open_payments::client::OpClientError;
use open_payments::snippets::utils::{create_authenticated_client, get_env_var, load_env};
use open_payments::types::{resource::CreateIncomingPaymentRequest, Amount};

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

// Prepare incoming payment request
let access_token = get_env_var("INCOMING_PAYMENT_ACCESS_TOKEN")?;
let wallet_address_url = get_env_var("WALLET_ADDRESS_URL")?;
let resource_server_url = get_resource_server_url(&wallet_address_url)?;

// Unwrap is safe here because we are adding a positive duration to the current time
let expires_at = Utc::now()
    .checked_add_signed(Duration::minutes(10000))
    .unwrap();

let request = CreateIncomingPaymentRequest {
    wallet_address: wallet_address_url,
    incoming_amount: Some(Amount {
        value: "1000".to_string(),
        asset_code: "EUR".to_string(),
        asset_scale: 2u8,
    }),
    expires_at: Some(expires_at),
    metadata: None,
};

// Create incoming payment
println!(
    "Incoming payment create request JSON: {}",
    serde_json::to_string_pretty(&request)?
);

let payment = client
    .incoming_payments()
    .create(&resource_server_url, &request, Some(&access_token))
    .await?;

// Output
println!("Created incoming payment: {payment:#?}");

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);

// Create incoming payment
$newIncomingPayment = $opClient->incomingPayment()->create(
    [
        'url' => $wallet->resourceServer,
        'access_token' => $INCOMING_PAYMENT_GRANT_ACCESS_TOKEN
    ],
    [
        'walletAddress' => $config->getWalletAddressUrl(),
        'incomingAmount' => [
            'value' => "130",
            'assetCode' => 'USD',
            'assetScale' => 2
        ],
        'metadata' => [
            'description' => 'Test php snippets transaction with $1,30 amount',
            'externalRef' => 'INVOICE-' . uniqid()
        ],
        'expiresAt' => (new \DateTime())->add(new \DateInterval('PT59M'))->format("Y-m-d\TH:i:s.v\Z")
    ]
);

// Output
echo 'INCOMING_PAYMENT_URL: ' . $newIncomingPayment->id . PHP_EOL;
echo 'INCOMING PAYMENT OBJECT:' . PHP_EOL . print_r($newIncomingPayment, true);

View full source

Go

Prerequisites

package main

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

  op "github.com/interledger/open-payments-go"
  rs "github.com/interledger/open-payments-go/generated/resourceserver"

)

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)
  }

  // Create incoming payment
  expiresAt := time.Now().Add(10 * time.Minute)
  incomingPayment, err := client.IncomingPayment.Create(context.TODO(), op.IncomingPaymentCreateParams{
    BaseURL:     RESOURCE_SERVER_URL,
    AccessToken: ACCESS_TOKEN,
    Payload: rs.CreateIncomingPaymentJSONBody{
      WalletAddressSchema: WALLET_ADDRESS_URL,
      IncomingAmount: &rs.Amount{
        Value:      "1000",
        AssetCode:  "USD",
        AssetScale: 2,
      },
      ExpiresAt: &expiresAt,
    },
  })
  if err != nil {
    log.Fatalf("Error creating incoming payment: %v\n", err)
  }

  // Output
  incomingPaymentJSON, err := json.MarshalIndent(incomingPayment, "", "  ")
  if err != nil {
    log.Fatalf("Error marshaling incoming payment: %v\n", err)
  }
  fmt.Println("INCOMING PAYMENT:", string(incomingPaymentJSON))
  fmt.Println("INCOMING PAYMENT URL =", *incomingPayment.Id)
}

Java

Prerequisites

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

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

// Get wallet address information
    var receiverWallet = client.getWalletAddress("https://cloudninebank.example.com/merchant");

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

// Output
log.info("INCOMING_PAYMENT: {}", incomingPayment);

References

• API specification