# Cards

The Cards API allows you to create and manage virtual cards, allocate balances, retrieve card details, and access transaction history.

Each card is linked to a specific user and operates with an independent balance.

***

### Base Path All card-related endpoints are prefixed with:

```
/users/{userId}/cards
```

Base URL:

```
https://aurex.cash/api/dashboard
```

***

### Card Entity

A card object includes:

* cardId Unique identifier
* cardName Custom name assigned during creation
* cardNumber Full card number
* expiryDate Expiration date
* cvv Card security code
* balance Current card balance
* status Card status

Example:

```json
{
  "cardId": "card_abc123",
  "cardName": "Marketing Card",
  "cardNumber": "4111 1111 1111 1234",
  "expiryDate": "12/28",
  "cvv": "123",
  "balance": 100,
  "status": "active"
}
```

***

### Create Card

Creates a new virtual card for a user.

#### Endpoint

```
POST /users/{userId}/cards
```

#### Request Body

```json
{
  "cardName": "My Card",
  "initialBalance": 100
}
```

#### Fee Rules

* Issue fee Fixed card issuance fee
* Service fee Percentage applied to allocated amount
* Minimum balance 25 USD
* Maximum balance 100000 USD

Total deducted from wallet:

Initial balance + service fee + issue fee

#### Success Response

```json
{
  "success": true,
  "data": {
    "cardId": "card_abc123",
    "cardName": "My Card",
    "balance": 100,
    "cardNumber": "4111 1111 1111 1234",
    "expiryDate": "12/28",
    "cvv": "123",
    "status": "active",
    "fees": {
      "depositAmount": 124,
      "ourFee": 5,
      "ourFeeRate": 0.05,
      "cardIssueFee": 19,
      "totalFees": 24,
      "cardBalance": 100
    }
  }
}
```

> Card creation deducts funds from the user wallet, including all applicable fees.

***

### List User Cards

Returns all cards associated with a user.

#### Endpoint

```
GET /users/{userId}/cards
```

#### Success Response

```json
{
  "success": true,
  "data": [
    {
      "cardId": "card_abc123",
      "cardName": "My Card",
      "balance": 100,
      "status": "active"
    }
  ]
}
```

***

### Get Card Details

Returns full card details by card ID.

#### Endpoint

```
GET /users/{userId}/cards/{cardId}
```

#### Success Response

```json
{
  "success": true,
  "data": {
    "cardId": "card_abc123",
    "cardName": "My Card",
    "cardNumber": "4111 1111 1111 1234",
    "expiryDate": "12/28",
    "cvv": "123",
    "balance": 100,
    "status": "active"
  }
}
```

> Card details must be handled securely and never exposed in client-side environments.

***

### Top Up Card

Transfers funds from wallet to card balance.

#### Endpoint

```
POST /users/{userId}/cards/{cardId}/topup
```

#### Request Body

```json
{
  "amount": 100
}
```

#### Rules

* Minimum top-up amount 10 USD
* Maximum top-up amount 10000 USD
* Service fee 3 percent

Total deducted from wallet:

Amount + service fee

#### Success Response

```json
{
  "success": true,
  "message": "Card recharged successfully",
  "data": {
    "cardId": "card_abc123",
    "newBalance": 200,
    "rechargeAmount": 100,
    "fees": 3
  }
}
```

***

### Card Transactions

Returns transaction history for a specific card.

#### Endpoint

```
GET /users/{userId}/cards/{cardId}/transactions
```

#### Success Response

```json
{
  "success": true,
  "data": [
    {
      "transactionId": "txn_123",
      "amount": 25.50,
      "currency": "USD",
      "status": "completed",
      "createdAt": "2026-01-31T12:00:00Z"
    }
  ]
}
```

#### Transaction Status Values

* pending
* completed
* declined
* failed

***

### Get OTP Code

Returns a one-time password for card authentication.

#### Endpoint

```
GET /users/{userId}/otp?cardId={cardId}
```

#### Success Response

```json
{
  "success": true,
  "data": {
    "otp": "123456",
    "expiresIn": 300,
    "cardId": "card_abc123"
  }
}
```

{% hint style="info" %}
OTP codes are time-limited and must be used immediately.
{% endhint %}

***

### Card Status Values

A card may have one of the following statuses:

* active
* frozen
* blocked
* expired

***

### Error Responses

All endpoints return errors in the following format:

```json
{
  "success": false,
  "error": "Error description"
}
```

Common HTTP status codes:

* 400 Invalid request parameters
* 401 Invalid or missing API key
* 404 Resource not found
* 409 Insufficient balance
* 429 Rate limit exceeded