m
mCards|Documentation
API ReferenceSDKs

Getting Started with the mCards API

Welcome to the mCards Developer Platform. This guide walks you through setting up your first integration — from authentication to making your first API call.

Prerequisites

  • An mCards partner account with API credentials
  • Your HMAC API key and secret (found in your partner dashboard)
  • Node.js >= 16 (for TypeScript SDK) or Python >= 3.9 (for Python SDK)

Step 1: Install the SDK

TypeScript / JavaScript

bash
npm install @mcards/sdk

Python

bash
pip install mcards-sdk

Step 2: Authenticate

The mCards API supports two authentication methods:

HMAC-SHA256 (Server-to-Server)

Best for backend integrations. Uses your API key and secret to sign every request.

TypeScript:

typescript
import { McardsSdk } from '@mcards/sdk';

const client = new McardsSdk({
  apiKey: process.env.MCARDS_API_KEY,
  apiSecret: process.env.MCARDS_API_SECRET,
});

Python:

python
from mcards_sdk import McardsSdk

client = McardsSdk(
    api_key=os.environ["MCARDS_API_KEY"],
    api_secret=os.environ["MCARDS_API_SECRET"],
)

OAuth2 Bearer Token (Client Applications)

Best for frontend apps or when you need scoped access.

TypeScript:

typescript
const client = new McardsSdk();

// Exchange credentials for a token
const { data: token } = await client.oauth.createToken(
  'your-client-id',
  'your-client-secret',
  'partner:read wallets:read cards:read'
);

// Set the token for subsequent requests
client.setBearerToken(token.access_token);

Python:

python
client = McardsSdk()

# Exchange credentials for a token
token = client.oauth.create_token(
    client_id="your-client-id",
    client_secret="your-client-secret",
    scope="partner:read wallets:read cards:read",
)

# Set the token for subsequent requests
client.set_bearer_token(token.data["access_token"])

Step 3: Make Your First API Call

TypeScript:

typescript
// Get your partner profile
const { data: profile } = await client.partner.getProfile();
console.log(\`Partner: \${profile.name} (\${profile.uuid})\`);

// List wallets
const { data: wallets } = await client.wallets.list({ page: 1, per_page: 10 });
console.log(\`Found \${wallets.meta.total_count} wallets\`);

// List cards
const { data: cards } = await client.cards.list();
cards.cards.forEach(card => {
  console.log(\`Card \${card.last4} — \${card.status}\`);
});

Python:

python
# Get your partner profile
profile = client.partner.get_profile()
print(f"Partner: {profile.data['name']} ({profile.data['uuid']})")

# List wallets
wallets = client.wallets.list(page=1, per_page=10)
print(f"Found {wallets.data['meta']['total_count']} wallets")

# List cards
cards = client.cards.list()
for card in cards.data["cards"]:
    print(f"Card {card['last4']} — {card['status']}")

Step 4: Handle Errors

Both SDKs return structured responses with status codes and error messages.

TypeScript:

typescript
const result = await client.wallets.get('nonexistent-uuid');

if (result.error) {
  console.error(\`Error \${result.status}: \${result.error}\`);
} else {
  console.log(result.data);
}

Python:

python
result = client.wallets.get("nonexistent-uuid")

if not result.ok:
    print(f"Error {result.status}: {result.error}")
else:
    print(result.data)

Step 5: Explore the Sandbox

Use the sandbox environment to test without affecting production data.

TypeScript:

typescript
// Create a sandbox OAuth app
const { data: app } = await client.oauth.createApplication(
  'My Sandbox App',
  'partner:read wallets:read cards:read sandbox:write',
  true // sandbox mode
);

// Exchange for a sandbox token
const { data: token } = await client.oauth.createToken(
  app.client_id,
  app.client_secret,
);
client.setBearerToken(token.access_token);

// Simulate a transaction
const { data: txn } = await client.sandbox.authorize({
  amount: 42.50,
  currency: 'USD',
  merchant_name: 'Coffee Shop',
});
console.log(\`Transaction \${txn.transaction_id}: \${txn.status}\`);

Next Steps