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:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

OTP codes are time-limited and must be used immediately.

---

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:

{
  "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