> For the complete documentation index, see [llms.txt](https://docs.zebec.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zebec.io/developer-docs/sdks/partner-card-sdk.md). # 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](/developer-docs/partner-api.md) for those operations. ## Installation ```bash npm install @zebec-network/partners-card-sdk ``` ```bash 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. {% hint style="warning" %} 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. {% endhint %} 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. ```ts 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. ```ts 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: ```ts 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. ```ts const recipient = Recipient.create( "customer123", // participantId: 1-20 alphanumeric characters "Sample", // firstName "Customer", // lastName "customer@example.com", // emailAddress "+15555550100", // 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()`. ```ts 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. ```ts 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. {% hint style="info" %} The older `purchaseCardWithUsdc()` method remains available for backward compatibility. New integrations should use `purchaseCard()`. {% endhint %} ## Solana integration Create `ZebecCardSolanaService` with a configured `ZebecCardV2Service` from `@zebec-network/zebec-card-v2-sdk`. ```ts 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. ```ts 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: "", }, 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](/developer-docs/partner-api.md) — authentication, OTP, card data, quotes, preflight, submission, and status. * [Partner API top-up flow](/developer-docs/partner-api/topup-flow.md) * [Partners Card SDK package](https://www.npmjs.com/package/@zebec-network/partners-card-sdk) * [Silver, Carbon, and Black card user guides](/zebec-product-information/cards.md)