Mysten Labs TypeScript SDK Docs

This package is in active development and should be used with caution. APIs are experimental and subject to breaking changes without notice. We recommend thoroughly testing any implementation before using in production environments.

This guide will help you set up and start using the Payment Kit SDK in your Sui application.

Prerequisites

Before you begin, ensure you have:

A Sui wallet with testnet/mainnet SUI tokens
Basic understanding of TypeScript and the Sui blockchain

Installation

Install the Payment Kit SDK and the Sui TypeScript SDK:

npm install --save @mysten/payment-kit @mysten/sui

Setting Up the Client

The Payment Kit SDK extends the standard SuiClient to provide payment functionality. Here's how to set it up:

import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
import { paymentKit } from '@mysten/payment-kit';

// Create a Sui client with Payment Kit extension
const client = new SuiClient({
	url: getFullnodeUrl('testnet'),
	network: 'testnet',
}).$extend(paymentKit());

The client will automatically configure the correct package IDs for the network you're using (testnet or mainnet).

Your First Payment

Let's process a simple registry-based payment using the default payment registry:

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';

// Create or load your keypair
const keypair = Ed25519Keypair.generate();
const sender = keypair.getPublicKey().toSuiAddress();

// Create the payment transaction
const tx = client.paymentKit.tx.processRegistryPayment({
	nonce: crypto.randomUUID(), // Unique identifier for this payment
	coinType: '0x2::sui::SUI', // Coin type (SUI in this case)
	amount: 1n * MIST_PER_SUI, // 1 SUI (in MIST)
	receiver,
	sender: sender,
});

// Sign and execute
const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
	options: {
		showEffects: true,
		showEvents: true,
	},
});

console.log('Payment processed:', result.digest);

Understanding the Payment

In this example:

Nonce: A unique identifier (UUIDv4) that prevents duplicate payments when using a registry
Coin Type: The type of coin being transferred (SUI token)
Amount: The payment amount in the smallest unit (MIST for SUI)
Receiver: The address receiving the payment
Sender: The address sending the payment (must match the transaction signer)
Registry Name: The payment registry to use (defaults to DEFAULT_REGISTRY_NAME)

Verifying the Payment

After processing a payment, you can query the payment record to verify it exists:

// Query the payment record
const paymentRecord = await client.paymentKit.getPaymentRecord({
	nonce: crypto.randomUUID(),
	coinType: '0x2::sui::SUI',
	amount: 1n * MIST_PER_SUI,
	receiver,
});

if (paymentRecord) {
	console.log('Payment verified!');
	console.log('Transaction:', paymentRecord.paymentTransactionDigest);
	console.log('Epoch:', paymentRecord.epochAtTimeOfRecord);
} else {
	console.log('Payment not found');
}

Processing an Ephemeral Payment

If you don't need duplicate prevention or persistent storage, use ephemeral payments:

const tx = client.paymentKit.tx.processEphemeralPayment({
	nonce: crypto.randomUUID(),
	coinType: '0x2::sui::SUI',
	amount: 1n * MIST_PER_SUI,
	receiver,
	sender: sender,
});

const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
});

console.log('Ephemeral payment processed:', result.digest);

Ephemeral payments:

Don't create a PaymentRecord
Don't prevent duplicates
Still emit a PaymentReceipt event
Have lower gas costs

Working with Different Coin Types

Payment Kit supports any Sui coin type. Here's how to process payments with custom coins:

// Example with a custom coin type
const customCoinType = '0xabcd...::my_coin::MY_COIN';

const tx = client.paymentKit.tx.processRegistryPayment({
	nonce: crypto.randomUUID(),
	coinType: customCoinType,
	amount: 5000,
	receiver,
	sender: sender,
});

// Execute the transaction
const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
});

Error Handling

Always wrap payment operations in try-catch blocks:

try {
	const tx = client.paymentKit.tx.processRegistryPayment({...});
	const result = await client.signAndExecuteTransaction({
		transaction: tx,
		signer: keypair,
	});

	console.log('Success:', result.digest);
} catch (error) {
	if (error.message.includes('Duplicate')) {
		console.error('Payment already processed');
	} else if (error.message.includes('insufficient')) {
		console.error('Insufficient balance');
	} else {
		console.error('Payment failed:', error.message);
	}
}

Next Steps

Now that you understand the basics, explore more advanced features:

Payment Processing - Deep dive into payment models
Registry Management - Create and configure custom registries
SDK API Reference - Complete SDK API documentation

Getting Started