Credit Top-Up
PaymentKit enables flexible credit-based billing models by allowing customers to replenish their credit balances. To enable this, you must first configure your credit currency to be purchasable by linking it to a standard product and price.
Once configured, customers can perform manual top-ups or set up automatic recharges directly from their user-facing billing portal, with no additional UI development required from you. This guide walks through the one-time configuration process.
Before proceeding, ensure you have set up your credit-based billing system as described in the Credit-Based Billing guide.
Configure Credit Currency for Top-Up#
To allow customers to purchase credits, you first need to configure a credit currency. This involves linking it to a standard product and price that customers will purchase. This "top-up package" is priced in a real-world currency (e.g., USDC, ETH) but grants a specific amount of credits to the customer upon successful payment.
Step 1: Create a Top-Up Product and Price#
First, create a product of type credit and a price that represents the top-up package. This price must contain credit_config within its metadata to specify how many credits are granted upon purchase. This price will be used as the base_price_id in the next step.
import payment from '@blocklet/payment-js';
// Assume you have a meter configured for your credit-based service
const meter = { id: 'meter_xxxx', currency_id: 'pc_credit_xxxx' };
async function createTopUpPackage() {
try {
// Create a product for the credit package
const product = await payment.products.create({
name: '200,000 Credits Pack',
description: 'A package containing 200,000 credits for your account.',
type: 'credit', // The product type must be 'credit'
});
// Create a price for the product in a real-world currency
const price = await payment.prices.create({
product_id: product.id,
type: 'one_time',
unit_amount: '10',
currency_id: 'pc_usdc_xxxxxxxx', // Replace with your actual USDC currency ID
metadata: {
meter_id: meter.id,
credit_config: {
priority: 50,
valid_duration_value: 0, // 0 means credits never expire
valid_duration_unit: 'days',
currency_id: meter.currency_id, // The ID of the credit currency being granted
credit_amount: '200000', // The amount of credits to grant
},
},
});
console.log(`Created top-up product ${product.id} with price ${price.id}`);
return { product, price };
} catch (error) {
console.error('Error creating top-up package:', error.message);
}
}
createTopUpPackage();Step 2: Set the Recharge Configuration#
Once you have a price for your top-up package, use the updateRechargeConfig method to associate it with your credit currency. This tells PaymentKit which product to sell when a user wants to top up this specific credit.
Method payment.paymentCurrencies.updateRechargeConfig(id, data)
Parameters
Name | Type | Description |
|---|---|---|
|
| The ID of the credit currency to configure (e.g., |
|
| An object containing the recharge configuration. |
data Object Properties
Name | Type | Description |
|---|---|---|
|
| Required. The ID of the |
|
| Optional. A pre-existing Payment Link ID to use for the checkout process. |
|
| Optional. A custom checkout URL. If not provided, PaymentKit generates one by first checking for a |
Example
import payment from '@blocklet/payment-js';
async function configureCreditCurrency(creditCurrencyId, basePriceId) {
try {
const updatedCurrency = await payment.paymentCurrencies.updateRechargeConfig(
creditCurrencyId,
{
base_price_id: basePriceId,
}
);
console.log('Recharge config updated successfully for:', updatedCurrency.id);
} catch (error) {
console.error('Error updating recharge config:', error.message);
}
}
// Usage: configureCreditCurrency('pc_credit_xxxx', 'price_xxxx');Enabling the Customer Experience#
After you associate a base price with a credit currency using updateRechargeConfig, that currency is enabled for top-ups. Your work as a developer is complete. Your customers can now manage their credit balance through the standard, user-facing PaymentKit billing portal.
This portal allows them to:
- Manually Top-Up: Purchase the configured credit package at any time.
- Configure Auto-Recharge: Set up rules to automatically buy credits when their balance falls below a certain threshold.
The separation of concerns is illustrated below:
By completing the initial setup, you empower your users to manage their own credit balances without requiring you to build or maintain a custom billing interface.