Partners Card SDK

Integrate Zebec virtual card purchases and Carbon card top-ups on EVM and Solana.

The Zebec Partners Card SDK lets partners quote and purchase Zebec virtual cards. It supports Ethereum, BNB Smart Chain, Polygon, and Base through ZebecCardEvmService. Solana integrations use ZebecCardSolanaService with the companion @zebec-network/zebec-card-v2-sdk.

The SDK handles wallet transactions and coordinates the purchase result with the Partner API. Keep authentication, end-user OTP, delegated access tokens, quote requests, preflight checks, and status polling in your Partner API client. See the Partner API docs for those operations.

Installation

npm install @zebec-network/partners-card-sdk

yarn add @zebec-network/partners-card-sdk

Authentication and security

Zebec supplies partners with an API key and encryption key. The SDK keeps these constructor parameters for compatibility with integrations that use its legacy API client.

Do not commit either credential or expose them in browser-delivered source code. The SDK does not perform end-user login, OTP verification, OAuth, or an access-token exchange.

Partner API environments:

Environment	Base URL
Production	https://api.superapp.zebec.io
Sandbox	https://dev-super.api.zebec.io

For the current Partner v1 API, supply a purchaseApiAdapter. It connects your authenticated Partner API client to the SDK's on-chain purchase workflow without adding authentication state to the SDK.

const service = new ZebecCardEvmService(
	signer,
	56,
	{ apiKey, encryptionKey },
	{
		purchaseApiAdapter: {
			ping: () => partnerApi.healthCheck(),
			fetchZebecCardPrograms: (countryCode) =>
				partnerApi.getCardPrograms(countryCode),
			purchaseCard: (orderRequest) =>
				partnerApi.submitConfirmedPurchase(orderRequest),
		},
	},
);

The adapter methods in this example belong to your Partner API client. Existing integrations should omit purchaseApiAdapter only when their deployment still supports the SDK's legacy routes and authentication format. The current Super App hosts do not expose the legacy /orders/* routes.

EVM integration

Supported chains

Chain	Chain ID	SDK enum
Ethereum	1	SupportedEvmChain.Mainnet
Sepolia	11155111	SupportedEvmChain.Sepolia
Base	8453	SupportedEvmChain.Base
BNB Smart Chain	56	SupportedEvmChain.Bsc
BNB Smart Chain Testnet	97	SupportedEvmChain.BscTestnet
Polygon	137	SupportedEvmChain.Polygon
Polygon Amoy	80002	SupportedEvmChain.PolygonAmoy

Set sandbox: true when using a testnet. Production mode accepts only mainnet chains, and sandbox mode accepts only testnet chains.

Create a service

Create ZebecCardEvmService with an Ethers signer, a supported chain ID, and credentials supplied by Zebec.

import {
	Recipient,
	ZebecCardEvmService,
} from "@zebec-network/partners-card-sdk";

// Provide an ethers Signer from your secure signing integration.

const service = new ZebecCardEvmService(
	signer,
	56,
	{ apiKey, encryptionKey },
	{ purchaseApiAdapter },
);

For a testnet service:

const service = new ZebecCardEvmService(
	signer,
	97,
	{ apiKey, encryptionKey },
	{ sandbox: true, purchaseApiAdapter },
);

Create a recipient

Recipient.create() validates the partner's participant ID and the cardholder's contact details.

const recipient = Recipient.create(
	"customer123",             // participantId: 1-20 alphanumeric characters
	"Sample",                  // firstName
	"Customer",                // lastName
	"[e-mail]",    // emailAddress
	"[phone]",            // mobilePhone
	"en-US",                   // language
	"San Francisco",           // city
	"CA",                      // state
	"94105",                   // postalCode
	"USA",                     // ISO 3166-1 alpha-3 country code
	"123 Market Street",       // address1
);

address2 is an optional final argument. Each address line can contain up to 50 characters, and the email address can contain up to 80 characters.

Quote and purchase

With the current Partner v1 API, request the quote and run preflight through your Partner API client. Then pass the quote unchanged to purchaseCard().

const programDetails = await service.fetchZebecCardProgram("USA");
if (!programDetails.availablePrograms.length) {
	throw new Error("No card program is available for this recipient");
}

const cardProgramId = programDetails.availablePrograms[0].id;
const amount = "25";
const sourceChain = "BINANCE";
const sourceTokenMint = "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d";

const quote = await partnerApi.getTopupQuote({
	amount,
	currencyCode: "USD",
	sourceChain,
	sourceTokenMint,
});

await partnerApi.preflightTopup({ quoteId: quote.id, cardProgramId });

const { orderDetail, receipt } = await service.purchaseCard({
	amount,
	cardProgramId,
	recipient,
	quote,
	token: { symbol: "USDC" },
});

console.log("transaction:", receipt.hash);
console.log("order:", orderDetail);

purchaseCard():

1. Validates the quote, recipient, supported card program, wallet balance, and contract limits.

2. Approves ERC-20 spending when the existing allowance is too low.

3. Selects a direct purchase or DEX swap-and-buy path from the quote and token metadata.

4. Waits for the on-chain receipt and passes the confirmed purchase to purchaseApiAdapter.purchaseCard().

For a non-USDC token, provide its contract address. The quote must include executable swap data from the Partner API.

const result = await service.purchaseCard({
	amount: sourceTokenAmount,
	cardProgramId,
	recipient,
	quote,
	token: {
		symbol: "VELO",
		address: "0xf486ad071f3bee968384d2e39e2d8af0fcf6fd46",
	},
});

The SDK rejects missing swap routes, mismatched tokens or chains, unsafe receivers, and card loads outside the contract limits before token approval.

The older purchaseCardWithUsdc() method remains available for backward compatibility. New integrations should use purchaseCard().

Solana integration

Create ZebecCardSolanaService with a configured ZebecCardV2Service from @zebec-network/zebec-card-v2-sdk.

import { ZebecCardSolanaService } from "@zebec-network/partners-card-sdk";

const service = new ZebecCardSolanaService(
	cardV2Service,
	{ apiKey, encryptionKey },
	{ network: "mainnet-beta" },
);

Use network: "devnet" together with sandbox: true for sandbox testing. The Solana service uses the same fetchQuote() and purchaseCard() workflow and selects direct or swap execution from the quote and token metadata.

const quote = await service.fetchQuote({
	token: "USDC",
	amount: "25",
	type: "EXACT_OUT",
	targetCurrency: "USD",
});

const { signature, orderDetail } = await service.purchaseCard({
	amount: "25",
	quote,
	token: {
		symbol: "USDC",
		mintAddress: "<USDC_MINT_ADDRESS>",
	},
	cardProgramId,
	recipient,
});

Legacy quote methods

fetchQuote() and fetchQuoteForToken() on the EVM service use the SDK's built-in legacy API client. Use them only if your deployment supports the legacy routes. For the current Partner v1 API, obtain the quote through your authenticated Partner API client and pass it unchanged to purchaseCard().

Related

• Partner API — authentication, OTP, card data, quotes, preflight, submission, and status.

• Partner API top-up flow

• Partners Card SDK package

• Silver, Carbon, and Black card user guides