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.

payerAccount

nullable string

The account of the user that will pay for the session, when known upfront.

walletSecret

nullable string

The wallet secret that was used when creating the wallet. Required if the payer wallet was created on Glide.

enableRefundEmails

nullable boolean

When set to true, the payer will receive an email if their payment is refunded.

payerEmail

nullable string

The email address of the payer, used for refund notifications.

widgetConfig

nullable object

Configuration for Glide-hosted payment pages. Contains an optional appMetadata object (id, name, logoUrl, faviconUrl) and an optional theme object with custom theme values.

commissionUSD

nullable string

The commission amount in USD that will be added on top of the payment amount and will be paid out to the developer.

commissionRates

nullable CommissionRates

Commission rates per currency tier (tier1, tier2, tier3) that will be added on top of the payment amount and paid out to the developer, as a percentage of the transaction amount (e.g., "0.5" = 0.5%). Cannot be used with commissionUSD.

dryMode

nullable boolean

When set to true, the session is created in dry mode for testing and no real payment is processed.

Return Type

sessionId^*

string

The unique identifier of the session.

createdAt^*

string

The timestamp at which the session was created.

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.

etaInSeconds^*

number

Number of seconds it is expected to take for the sponsored transaction after the user has paid for the transaction.

payerAccount

nullable string

The account id that will pay for the transaction. It can be the wallet address when the payment method is wallet.

paymentStatus^*

PaymentStatus

The current status of the payment for the session, one of `unpaid`, `waiting_confirmations`, `paid`, `pending_refund`, or `refunded`. 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.

paymentCurrencyTier^*

'tier1' | 'tier2' | 'tier3'

The currency tier 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.

paymentTransactionUrl

nullable string | null

The explorer URL for the payment transaction.

paymentAction^*

'signAndSendTransaction' | 'signTypedData' | 'redirectToUrl' | 'transfer'

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`.

unsignedSolanaTransaction

nullable { message: string } | { transaction: string } | null

The base64-encoded Solana message or transaction that the user must sign and send to complete the payment. It is set when the payment is made on Solana and 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`.

redirectUrl

nullable string | null

The URL that the user must be redirected to complete the payment. It is set when the `paymentAction` is set to `redirectToUrl`.

depositAddress

nullable Hex | null

The deposit address that the payment must be sent to. It is set when the `paymentAction` is set to `transfer`.

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, one of `created`, `submitted`, `signed`, `pending`, `success`, `failed`, or `dropped`.

sponsoredTransactionHash

nullable Hex | null

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

sponsoredTransactionUrl

nullable string | null

The explorer URL for the sponsored transaction.

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.

serviceFeeUSD^*

string

The Glide service fee in USD for this transaction.

gasFeeUSD^*

string

The gas fee, estimated required for the transaction, in USD.

paymentTransactionGasFeeUSD^*

string

The gas fee the user pays to execute their payment transaction, in USD.

totalFeeUSD^*

string

The total fee including gas fee, service fee, commission, and payment transaction gas fee, in USD.

metadata^*

string

The metadata associated with the session.

gasRefuelAmount

nullable string

The amount of gas refueled, in the native currency.

gasRefuelUSD

nullable string

The USD value of the gas refueled.

gasRefuelTransactionStatus

nullable TransactionStatus

The status of the gas refuel transaction.

gasRefuelTransactionHash

nullable Hex

The hash of the gas refuel transaction.

gasRefuelTransactionUrl

nullable string

The explorer URL for the gas refuel transaction.

refundTransactionHash

nullable string

The hash of the refund transaction, if the payment was refunded.

refundTransactionUrl

nullable string

The explorer URL for the refund transaction.

refundAddress

nullable string

The address the refund was sent to.

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