CleverCards API Onboarding Guide

Welcome to the CleverCards Platform. This guide will help you get started with the CleverCards B2B API, which allows you to issue, manage, and fund digital prepaid cards directly from your application or backend systems.

🔑 What is CleverCards?

CleverCards is a digital-first payment platform enabling businesses to deliver real-time, controlled digital payments through secure prepaid Mastercards. Our API allows you to embed this functionality natively into your platform—whether for employee expenses, incentives, insurance payouts, or instant earnings access.

🚀 Getting Started

1. Obtain API Credentials

To begin using the API, you'll need:

• API Key
• User Credentials

Contact your CleverCards integration manager or onboarding contact by sending an email to [email protected] to get these securely provisioned.

2. Authentication

Use the /login endpoint to authenticate:

POST /login
Headers:
  X-API-Key: <your_api_key>
Body:
{
  "username": "your-username",
  "password": "your-password"
}

The response will return a bearer token. Include it in the Authorization header in all subsequent requests:

{
accessToken: <your_token>
}

3. Core Concepts

The CleverCards API revolves around several key entities. Understanding these will help you navigate and implement card issuance and management effectively.

🔹 Card Token Draft

A Card Token Draft is a configurable placeholder for digital value. You define its properties—such as amount, recipient, and metadata—before finalizing it into a usable card token. Drafts enable validation and approval workflows before issuance.

Typical use case: preparing rewards or disbursements that require review before being sent.

🔹 Card Token

A Card Token represents finalized digital value that can be delivered to a recipient and redeemed for a card. Tokens are created either from a draft or directly (for simple flows), and are sent via email or other configured channels.

Typical use case: sending a card token as a digital reward or payout.

🔹 Card Account

A Card Account is a limited-purpose account that holds funds linked to a digital card. It supports either a prepaid balance or spending limits, depending on the configuration.

Features include:

• Real-time balance tracking
• Transaction history
• Fund loading and unloading

🔹 Company Account

The Company Account represents your organization within the CleverCards Platform. It provides funding, configuration, and operational control for all issued cards.

Capabilities:

• Manage API access
• Monitor issued tokens
• Configure webhook and funding rules

🔹 Card

A Card is a digital Mastercard provisioned to an end user. It is linked to a Card Account and can be used online or in-store via wallets like Apple Pay or Google Pay.

Key attributes:

• Issued instantly upon token redemption
• Controlled via funding and usage limits
• Supports push-to-wallet delivery

4. Basic API Workflow

The following steps describe the typical flow to create, issue, and manage CleverCards using the API:

✅ Step 1: Create a Card Token Draft

Use this endpoint to define the card value, recipient, and delivery settings. This draft acts as a placeholder before issuance.

Endpoint:

POST /card-token-draft

Headers:

Authorization: Bearer <token>
CompanyAccountId: <your_company_account_id> X-API-Key: <your_api_key>

Example Request Body:

{
  "clientProductId": "product_abc123",
  "amount": {
    "value": 100,
    "currency": "EUR"
  },
  "externalReference": "Order_1001",
  "emailSubject": "Here is your new card",
  "cardHolder": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "mobile": "+353871234567"
  }
}

🧪 Test Scenarios
We recommend testing the following during onboarding:

✅ Token draft creation & updates

✅ Token finalization and delivery

Contact: [email protected]