API Reference

Card status

Card type

Transaction status

List cards

List all cards owned by the authenticated user. Query params: none.

Response 200

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Netflix",
      "masked_number": "411111******1234",
      "card_plan": "standard",
      "balance": 2500,
      "status": "active",
      "type": "online",
      "total_deposited": 5000,
      "total_withdrawn": 2500
    }
  ]
}

List card plans

Returns the list of card plans. Query params: none.

Response 200

{
  "success": true,
  "data": [
    { "slug": "standard", "name": "Standard", "topup_limit": 10000, "creation_fee": 1 }
  ]
}

List card transactions

List card transactions for the authenticated user, newest first.

Query params

Response 200

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "uuid",
        "card_id": "uuid",
        "amount": 1000,
        "currency": "USD",
        "masked_number": "411111******1234",
        "description": "Top-up",
        "status": "complete",
        "created_at": "2026-04-19T10:00:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

Get a card

Get a single card by ID.

Path params

Response 200

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Netflix",
    "masked_number": "411111******1234",
    "card_plan": "standard",
    "balance": 2500,
    "status": "active",
    "type": "online",
    "billing_address": { "...": "..." },
    "total_deposited": 5000,
    "total_withdrawn": 2500,
    "minimum_topup": 5,
    "min_balance": 0
  }
}

Errors: 404 if the card does not exist or is not owned by the caller.

Get sensitive card details

Returns sensitive card details (PAN, CVV, expiry). Treat the response as short-lived and never log it.

Path params

Response 200

{
  "success": true,
  "data": {
    "id": "uuid",
    "number": "4111111111111234",
    "cvv": "123",
    "expiry_date": "12/29"
  }
}

Errors: 400 if id is missing; 404 if the card is not owned by the caller.

Issue a card

Issue a new card for the authenticated user.

Body

Request

{ "bin_id": "uuid", "plan_slug": "standard", "card_name": "Netflix" }

Response 201

{ "success": true, "data": { "cardId": "uuid" } }

Errors: 400 for invalid bin or plan.

Top up a card

Load funds from the user's wallet onto a card. A top-up fee applies.

Body

Request

{ "card_id": "uuid", "amount": 100 }

Response 200

{ "success": true, "data": { "success": true } }

Errors: 400 when the wallet has insufficient balance or the amount is invalid; 502 when the top-up is declined.

Withdraw from a card

Withdraw funds from a card back to the user's wallet.

Body

Request

{ "card_id": "uuid", "amount": 50 }

Response 200

{ "success": true, "data": { "success": true } }

Errors: 400 when amount exceeds the card balance; 502 when the withdrawal is declined.

Close a card

Permanently close a card. Remaining balance is returned to the wallet. This action is irreversible — the card's status becomes closed.

Body

Request

{ "card_id": "uuid" }

Response 200

{ "success": true, "data": { "success": true } }

Errors: 400 if the card is already closed.

Webhooks

UnCard sends HTTP POST requests to your configured endpoint whenever an event occurs on one of your cards (e.g. a transaction). This lets you react to card activity in real time instead of polling.

Configuration

Webhooks are configured per-user from your dashboard.

If no webhook_url is set, no events are delivered.

Delivery

Your endpoint should acknowledge receipt with a 2xx response as quickly as possible.

Request headers

Payload

Every delivery has the same envelope:

{
  "type": "transaction.created",
  "data": { ... }
}

Events

transaction.created — data object

Example

{
  "type": "transaction.created",
  "data": {
    "id": "a1b2c3d4-0000-4444-8888-abcdef012345",
    "card_id": "f0e1d2c3-1111-4444-8888-abcdef543210",
    "amount": 12.50,
    "currency": "USD",
    "masked_number": "411111******1111",
    "description": "COFFEE SHOP",
    "status": "complete",
    "created_at": "2026-07-29T12:34:56.000Z"
  }
}

Note: fee transactions (Transaction fee, Decline fee) are delivered as separate transaction.created events, each with its own id.

Verifying signatures

If you set a webhook_secret, verify the X-UnCard-Signature header before trusting a payload. The signature is sha256= followed by the hex HMAC-SHA256 of the raw request body using your secret.

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

Compute the HMAC over the exact bytes received — the relay forwards the body byte-for-byte so the signature stays valid.