Top-up flow

Top up a Carbon card through the Zebec Partner API.

The top-up flow lets a partner add funds to a user's Carbon card using crypto held in the user's wallet.

Flow overview

1. Discover programs — GET /partner/v1/topup/programs

2. Build a quote — GET /partner/v1/topup/quote

3. User signs and sends the on-chain transfer using the quote's payment instructions.

4. Preflight checks — POST /partner/v1/topup/preflight

5. Submit the top-up — POST /partner/v1/topup

6. Poll status — GET /partner/v1/topup/{orderId}

1. Discover programs

GET /partner/v1/topup/programs
Authorization: Bearer <accessToken>

Returns available Carbon programs, currencies, accepted tokens, and each token's sourceTokenMint.

2. Build a quote

GET /partner/v1/topup/quote?amount=...&sourceChain=...
Authorization: Bearer <accessToken>

The backend prices the top-up and returns:

• id — use this as quoteId in later requests.

• Payment instructions, including chain and contractAddress.

• A resolved cardId.

• A canonical signing message the end user must sign with their wallet.

Quotes are valid for 2 minutes. The expiresIn field is an absolute expiration timestamp in Unix milliseconds.

3. On-chain transfer

The user submits the on-chain token transfer using the chain and contractAddress returned in the quote's payment object. Keep the on-chain receipt (including txHash).

4. Preflight

POST /partner/v1/topup/preflight
Authorization: Bearer <accessToken>
{
  "quoteId": "..."
}

Validates KYC, balance, and the buyer wallet against the live quote. The result is cached by quoteId.

5. Submit

POST /partner/v1/topup
Authorization: Bearer <accessToken>
{
  "quoteId": "...",
  "receipt": { "deposit": { "txHash": "..." } },
  "userSignature": "..."
}

The backend verifies the signature against the buyer wallet, consumes the quote, and enqueues the order through the validator → OnBe pipeline.

Submit idempotency is keyed by the on-chain receipt.deposit.txHash for 7 days.

6. Poll status

GET /partner/v1/topup/{orderId}
Authorization: Bearer <accessToken>

Poll until the order reaches a terminal state.

Required scope

Top-up endpoints require the cards:topup scope.

For full request/response schemas, see the Swagger UI.