Create payment session

Create a payment session for cross-chain cryptocurrency transactions

A payment session should be created when a user wants to send cryptocurrency from one blockchain to another, or convert between different tokens. Glide handles the routing, conversion, and transaction execution.

A session is valid for a limited time, during which the user should complete the payment process. If the user does not complete the payment within this time, the session will expire and the user will need to create a new session. If a payment is made for an expired session, the payment will be refunded.

The payment session enables users to pay in one currency on one blockchain while settling in a different currency on a potentially different blockchain, with all fees and conversion rates calculated upfront.

Import

import { createPaymentSession } from "@paywithglide/glide-js";

Usage

index.ts

import { createPaymentSession } from "@paywithglide/glide-js";
import { ethereum, polygon } from "@paywithglide/glide-js/chains";
import { usdc } from "@paywithglide/glide-js/currencies";
import { config } from "./config";
 
const session = await createPaymentSession(config, {
  paymentCurrency: usdc.on(ethereum),
  settleCurrency: usdc.on(polygon),
  recipientWallet: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  paymentAmount: "100", // Omit for arbitrary payment amounts
});
 
console.log("Session ID:", session.sessionId);
console.log("Payment action:", session.paymentAction);
console.log("Settlement amount:", session.sponsoredTransactionAmount);

Parameters

paymentCurrency^*

CAIP19

The cryptocurrency the user will use to pay, in CAIP-19 format (e.g., eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 for USDC on Ethereum).

settleCurrency^*

CAIP19

The cryptocurrency the recipient will receive, in CAIP-19 format. Can be the same as or different from paymentCurrency.

recipientWallet^*

string

The blockchain wallet address that will receive the settled funds. The address format depends on the settle currency's blockchain.

paymentAmount

nullable string

The amount the user will pay, specified as a string in human-readable format (not wei/smallest unit). Either paymentAmount OR settleAmount should be specified, but not both.

settleAmount

nullable string

The amount the recipient will receive, specified as a string in human-readable format. Mutually exclusive with paymentAmount.

stableDepositAddressKey

nullable string

An identifier for generating a stable deposit address. When the payment method is transfer, providing a consistent key ensures the same deposit address is returned for repeat sessions.

metadata

nullable string

Custom string metadata to attach to the session (e.g., order ID, user ID, JSON-encoded objects). Maximum length is typically 1024 characters.

Return Type

sessionId^*

string

The unique identifier of the session.

expiresAt^*

string

The timestamp at which the session will expire. Generally, this will be 10 minutes after the session is created.

expired^*

boolean

A boolean indicating whether the session has expired.

paymentStatus^*

PaymentStatus

The current status of the payment for the session. The session begins in the unpaid state and transitions to paid when the user completes their payment transaction.

paymentChainId^*

CAIP2

The chain id on which the user will pay for the transaction.

paymentChainName^*

string

The chain name on which the user will pay for the transaction.

paymentChainLogoUrl^*

string

The chain logo URL on which the user will pay for the transaction.

paymentCurrency^*

CAIP19

The currency in which the user pays in the CAIP-19 format.

paymentCurrencySymbol^*

string

The currency symbol in which the user pays.

paymentCurrencyLogoUrl^*

string

The currency logo URL in which the user pays.

paymentAmount^*

string

The amount of the payment required by the user to complete the transaction in a human-readable format.

paymentAmountUSD^*

string

The amount of the payment required by the user to complete the transaction in USD.

paymentTransactionHash

nullable Hex | null

The hash of the transaction that the user made to complete the payment.

paymentAction^*

'signAndSendTransaction' | 'signTypedData'

The action that the user must take to complete the payment.

unsignedTransaction

nullable EVMTransactionResponse | null

The transaction that the user must sign and send to the chain to complete the payment. It is set when the `paymentAction` is set to `signAndSendTransaction`.

unsignedTypedData

nullable PermitTypedData<Hex> | null

The typed data that the user must sign to complete the payment. It is set when the `paymentAction` is set to `signTypedData`.

sponsoredTransactionChainId^*

CAIP2

The chain id on which the transaction will be executed.

sponsoredTransactionChainName^*

string

The chain name on which the transaction will be executed.

sponsoredTransactionChainLogoUrl^*

string

The chain logo URL on which the transaction will be executed.

sponsoredTransactionStatus^*

TransactionStatus

The current status of the transaction that Glide is sending to the chain on behalf of the user.

sponsoredTransactionHash

nullable Hex | null

The hash of the transaction that Glide sent to the chain on behalf of the user.

sponsoredTransaction

nullable EVMTransaction | null

The transaction that Glide sent to the chain on behalf of the user.

sponsoredTransactionAmount^*

string

The amount required by the sponsored transaction, in a human-readable format.

sponsoredTransactionCurrency^*

CAIP19

The currency in which the sponsored transaction is executed, in CAIP-19 format.

sponsoredTransactionCurrencySymbol^*

string

The currency symbol in which the sponsored transaction will be executed.

sponsoredTransactionCurrencyLogoUrl^*

string

The currency logo URL in which the sponsored transaction will be executed.

sponsoredTransactionAmountUSD^*

string

The amount required by the sponsored transaction, in USD.

totalFeeUSD^*

string

The total fee covers the relayer fee and the destination transaction gas cost paid by the relayer.

The session object includes:

Payment details: Currency, amount, chain, and transaction hash
Settlement details: Final amount and destination after fees
Payment action: What the user needs to do (signAndSendTransaction, signTypedData, redirectToUrl, or transfer)
Fee breakdown: Service fees, gas fees, and total costs
Status tracking: Payment and transaction status fields for polling

Payment Actions

After creating a session, the paymentAction field determines what the user needs to do:

signAndSendTransaction

Most common action. User signs and sends a blockchain transaction using the unsignedTransaction field.

signTypedData

User signs EIP-712 typed data (permit) using the unsignedTypedData field. Used for gasless approvals.

redirectToUrl

User needs to complete payment through an external service (e.g., Coinbase onramp) using the redirectUrl field.

transfer

User manually transfers cryptocurrency to the depositAddress. Poll the session to detect when payment is received.

Examples

Settle a fixed amount

Ensure the recipient receives exactly 50 USDC:

const session = await createPaymentSession(config, {
  paymentCurrency: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  settleCurrency: "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  recipientWallet: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  settleAmount: "50", // Recipient gets exactly 50 USDC
});
 
console.log("User needs to pay:", session.paymentAmount);
console.log("Total fees:", session.totalFeeUSD);

With metadata

Track sessions with custom metadata:

const session = await createPaymentSession(config, {
  paymentCurrency: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  settleCurrency: "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  recipientWallet: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  paymentAmount: "100",
  metadata: JSON.stringify({
    orderId: "order-12345",
    userId: "user-789",
  }),
});
 
const orderInfo = JSON.parse(session.metadata);
console.log("Order ID:", orderInfo.orderId);

Stable deposit address

For recurring payments or saved addresses:

const userId = "user-123";
const depositKey = `deposit-${userId}`;
 
const session = await createPaymentSession(config, {
  paymentCurrency: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  settleCurrency: "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  recipientWallet: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  paymentAmount: "100",
  stableDepositAddressKey: depositKey,
});
 
if (session.paymentAction === "transfer" && session.depositAddress) {
  console.log("Send payment to:", session.depositAddress);
  // User can save this address for future payments
}

Native to token

Pay with native ETH, settle USDC:

import { eth, usdc } from "@paywithglide/glide-js/currencies";
import { ethereum } from "@paywithglide/glide-js/chains";
 
const session = await createPaymentSession(config, {
  paymentCurrency: eth.on(ethereum),
  settleCurrency: usdc.on(ethereum),
  recipientWallet: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  paymentAmount: "0.1", // Pay 0.1 ETH
});
 
console.log("Recipient will receive:", session.sponsoredTransactionAmount, "USDC");