Top-up flow
Top up a Carbon card through the Zebec Partner API.
This is the shared lifecycle for every token returned by GET /partner/v1/topup/programs. The payment itself is chain-specific; use the quote as the authority for the chain, network, token, amount, and payment instructions.
For implementation examples, see EVM, Solana, Canton, or Zano.
Flow overview
Discover the partner's enabled programs and tokens.
Request a short-lived quote.
Run preflight checks for the wallet that will pay.
Send the chain-native payment described by the quote.
Sign the quote's canonical signing message and submit the receipt.
Poll the returned order until it reaches a terminal state.
1. Discover programs
GET /partner/v1/topup/programs
Authorization: Bearer <accessToken>The response contains the available Carbon programs, target currencies, and the tokens enabled for the authenticated partner. Choose a token, then retain its chain, sourceTokenMint, and decimals for the quote request. Do not hardcode an address, mint, network, or token precision.
{
"programs": [
{
"programId": "carbon-intl",
"displayName": "Carbon International",
"currencies": ["USD"],
"acceptedTokens": [
{
"symbol": "USDC",
"chain": "SOLANA",
"contractAddress": "<token-address-or-mint>",
"sourceTokenMint": "<token-address-or-mint>",
"decimals": 6,
"platformFeePercentage": "0.025"
}
]
}
],
"currencies": { "USD": { "rate": 1, "symbol": "$" } }
}2. Build a quote
Copy sourceChain and sourceTokenMint from the selected accepted-token entry. A quote is single-use and valid for two minutes; expiresIn is its Unix-millisecond expiration time.
Save the following values:
id— use asquoteId.cardId,requestedAmount, andpayment— bind the payment to this quote.payment.chain,payment.network,payment.contractAddress,payment.tokenAmount, andpayment.tokenDecimals— exact payment inputs.signingMessage— sign this exact, unmodified UTF-8 message after payment.Any additional rail-specific fields, such as a destination address, payment ID, contract route, or swap data.
payment.tokenAmount is a base-unit string. Interpret it using payment.tokenDecimals, not a token precision stored in your app.
3. Preflight
Run preflight before submitting a payment. Include the wallet identifier that will send the payment; it must match the receipt submitted later.
Proceed only when canProceed is true. A fail check makes it false; a warn is informational. The successful result is tied to the quote, expires with it, and is consumed when the top-up is submitted.
4. Send the payment
Execute the payment with the user's wallet, using the values returned by the quote. Wait until the wallet reports a confirmed transaction identifier (txHash).
EVM and Solana: use the Partners Card SDK's
purchaseCard()method. It selects and submits the quote-authorized card purchase path.Canton, Zano, and other supported rails: use the wallet's native token transfer function, supplying the quote's network, token, destination, and base-unit amount exactly as returned.
Ethereum, Base, BNB Smart Chain, Polygon
Solana
Canton
Zano
5. Sign and submit
After the payment is confirmed, sign the exact signingMessage from the quote and submit the receipt. Use the signature scheme appropriate to the quoted chain; the chain examples show the required identifiers and encodings.
For Canton, include cantonAlgorithm when the wallet does not use the default ed25519 algorithm. The server derives chain and token metadata from the quote, so do not add a client-defined token, network, or payment ID.
The endpoint returns 202 Accepted:
Submits are idempotent for seven days by receipt.deposit.txHash. Reuse the same receipt only to retry an interrupted request; do not use a confirmed transaction for another quote.
6. Poll status
Poll statusUrl until the order reaches a terminal status. Do not infer card balance changes from transaction broadcast alone; the top-up completes through the validation and card-provider pipeline.
Errors and retries
Request a new quote after expiry, a failed preflight, or a failed payment.
Correct a signature or receipt error, then start again with a new quote and preflight because preflight is one-shot.
Retry temporary network failures with the same
txHash; do not send the payment again until you have confirmed whether it settled.Treat the partner sandbox Swagger UI as the source for complete schemas and current error responses.
Last updated