kazawallet-logo
HomeTransferExchangeWithdrawDepositCardsRatesHistoryInstall App

Kazawallet API Documentation

This document provides comprehensive information about all Kazawallet API endpoints used in the Kascards application.

Table of Contents

Configuration

Base URL

The API base URL is configurable via environment variables:

Base URL: https://outdoor.kasroad.com/wallet

API Headers

  • x-api-key: Your API key,
  • x-api-secret: Your API Secret key,

Payment Methods

Development

  • USDT-TRC20: 15
  • USDT-BEP20: 13

Production

  • USDT-TRC20: 118
  • USDT-ERC20: 116
  • USDT-SOL: 117
  • USDT-BEP20: 115

Endpoints

1. Get Balance

Endpoint: GET /get-merchant-wallets

Description: Get wallets.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Response Success:

{
    "success": true,
    "wallets": [
        {
            "currency": "currency-code",
            "amount": "amount"
        },
    ]
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.get( 'https://outdoor.kasroad.com/wallet/get-merchant-wallets,  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

2. Create Deposit

Endpoint: POST /createDepositRequest

Description: Creates a deposit request for a user.

Headers:

apiHeaders

Request Payload:

{
  merchantEmail: "Merchant Email",
  email: "User Email",
  currency: "currency_code",
  amount: "amount",
  note: "Merchant Note",
  paymentMethod: payment method number,
  fields:{
        "custom-field1": "test-1"
        "custom-field2": "test-2"
  }
}

Response Success:

  {
    "success": true,
    "error": null,
    "createdPayment": {
        "status": "pending",
        "message": null,
        "transaction_id": "de-xxxxx",
        "note": null,
        "extraPaymentInfo": null 
    }
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.post( 'https://outdoor.kasroad.com/wallet/createDepositRequest',{

  "merchantEmail": "mhd1@user.com",
  "email": "mhd2@user.com",
  "currency": "SYP",
  "amount": "500000",
  "note": "note",
  "paymentMethod": 17,
  "fields": {
    "bemo-dp-f1": "test-1"
  }
},  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
  },

);

3. Issue Kazawallet Cards

Endpoint: POST /wallet-cards/create

Description: Create cards request for a user.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Request Payload:

{
  currency: "currency_code",
  remark: "user remark" (optional)
}

Response Success:

{
    "created": true,
    "cardId": "kc-xxxxxxx",
    "createdTransfer": {
        "id": "kc-xxxxxxx",
        "amount": "creation fees"
    }
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.post( 'https://outdoor.kasroad.com/wallet/wallet-cards/create',{
  "currency": "currency_code"
},  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

4. Topup Card

Endpoint: PUT /wallet-cards/topup

Description: Topup cards request for a user.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Request Payload:

{
  amount: "amount",
  currency: "currency_code",
  cardId: "kc-xxxxxxx"
}

Response Success:

{
    "topup": true,
    "topupTransfer": {
        "id": "kc-xxxxxxx",
        "amount": "amount"
    }
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.post( 'https://outdoor.kasroad.com/wallet/wallet-cards/topup',{
  "amount": "amount",
  "currency": "currency_code",
  "cardId": "kc-xxxxxxx"
},  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

5. Cancel Card

Endpoint: PUT /wallet-cards/cancel

Description: Cancel cards request for a user.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Request Payload:

{
  currency: "currency_code",
  cardId: "kc-xxxxxxx"
}

Response Success:

{
    "Success": true,
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.post( 'https://outdoor.kasroad.com/wallet/wallet-cards/cancel',{
  "currency": "currency_code",
  "cardId": "kc-xxxxxxx"
},  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

6. Lock Card

Endpoint: PUT /wallet-cards/lock

Description: Lock cards request for a user.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Request Payload:

{
  cardId: "kc-xxxxxxx"
}

Response Success:

{
    "success": true,
    "message": "Card locked successfully",
    "details": {
        "success": true,
        "ts": xxxxxxxxx,
        "data": true,
        "code": 0,
        "msg": "Success"
    }
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.put( 'https://outdoor.kasroad.com/wallet/wallet-cards/lock',{
  "cardId": "kc-xxxxxxx"
},  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

7. Unlock Card

Endpoint: PUT /wallet-cards/unlock

Description: Unock cards request for a user.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Request Payload:

{
  cardId: "kc-xxxxxxx"
}

Response Success:

{
    "success": true,
    "message": "Card unlocked successfully",
    "details": {
        "success": true,
        "ts": xxxxxxxx,
        "data": true,
        "code": 0,
        "msg": "Success"
    }
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.put( 'https://outdoor.kasroad.com/wallet/wallet-cards/unlock',{
  "cardId": "kc-xxxxxxx"
},  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

8. Get Cards List

Endpoint: GET /get-merchant-wallets-cards

Description: Get wallet cards.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Response Success:

{
    "success": true,
    "cards": [
      {
            "mode": 1,
            "type": "card type",
            "last4": "xxxx",
            "remark": "",
            "status": "NORMAL",
            "cardName": "Platinum Virtual Card",
            "provider": "Provider name",
            "created_at": 1765270430545,
            "openCardTime": "1757937352000",
            "organization": "VISA",
            "cardIdInWallet": "kc-xxxxxx",
            "openCardOrderNo": "2025091501967557978384818176"
        },
    ]
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.get( 'https://outdoor.kasroad.com/wallet/get-merchant-wallets-cards,  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

9. Get Card Details

Endpoint: GET /wallet-cards/get-card-details

Description: Get card details.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Request Query:

{
  cardId="kc-xxxxxxx"
}

Response Success:

{
    "success": true,
    "message": "Card details retrieved successfully",
    "details": {
        "success": true,
        "ts": 1764680938,
        "data": {
            "cardCurrency": "USD",
            "cardName": "Platinum Virtual Card",
            "cardNumber": "**** **** **** ****",
            "cvv": "581",
            "expiryDate": "09/30"
        },
        "code": 0,
        "msg": "Success"
    }
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.get( 'https://outdoor.kasroad.com/wallet/wallet-cards/get-card-details?cardId=kc-xxxxxxxx',  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

10. Get Card Transactions

Endpoint: GET /wallet-cards/get-transactions

Description: Get card transactions.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Request Query:

{
  cardId="kc-xxxxxxx"
}

Response Success:

{
    "data": [
        {
            "amount": "amount",
            "businessOrderNo": "businessOrderNo",
            "cardNumber": "card number",
            "currency": "currency_code",
            "direction": "number",
            "merchantName": "merchantName",
            "orderNo": "order",
            "originalAmount": null,
            "originalCurrency": null,
            "reason": null,
            "state": 4,
            "transactionAt": 1764488059337,
            "transactionId": "transaction id",
            "type": 1
        }
    ],
    "cardDetails": {
        "cardNumber": "**** **** **** ****",
        "availableBalance": "card balance",
        "status": 1,
        "type": 1
    },
    "meta": {
        "pagination": {
            "page": 1,
            "pageSize": 15,
            "pageCount": 3,
            "total": 36
        }
    }
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.get( 'https://outdoor.kasroad.com/wallet/wallet-cards/get-transactions?cardId=kc-xxxxxxxx',  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

Transaction State

  • SUCCESSFUL: 1
  • FAILED: 2
  • IN_PROCESS: 3
  • POSTED: 4
  • NOT_POSTED: 5
  • PAYMENT_FAILED: 6
  • CANCELLED: 7

11. Validate code

Endpoint: POST /wallet-cards/validate-code

Description: Validate code.

Headers:

apiHeaders,
'merchant-email': 'merchant@example.com'

Request Payload:

{
  cardId:"kc-xxxxxxx"
  validateCode: "XXXXXXX"
}

Response Success:

{
    "success": true,
    "message": "Code validated successfully",
    "details": {
        "code": 0,
        "msg": "Success",
        "success": boolean,
        "ts": number,
        "data": boolean
    }
}

Response Error:

{
  success: false,
  error: "Error Msg",
}

Usage Example:

const result = await axios.post( 'https://outdoor.kasroad.com/wallet/wallet-cards/validate-code',{
  'cardId': 'kc-xxxxxxx',
  'validateCode': 'XXXX'
},  { 
    'x-api-key': 'XXXXX', 
    'x-api-secret': 'XXXXX', 
    "merchant-email": 'merchant@example.com'
  },

);

Webhook Events (Kazawallet Cards)

When a merchant sets a webhookUrl in their profile, Kazawallet will send a POST request to that URL for the following Kazawallet card events:

  • CC_CONSUME
  • CC_REFUND
  • CC_RECHARGE
  • 3DS_CONFIRM

These webhooks are sent by kazawallet after it receives the event from the card issuer. The webhook body is always:

{
  "event": "EVENT_NAME",
  "details": {
    "key": "value"
  }
}

Common fields for card transaction events (CC_CONSUME, CC_REFUND, CC_RECHARGE)

{
  "event": "CC_CONSUME",
  "details": {
    "reason": "R7",
    "amount": "19.030000",
    "transactionAt": 1768084354000,
    "type": 2,
    "originalAmount": 19.03,
    "originalCurrency": "USD",
    "currency": "USD",
    "status": 2,
    "direction": 1,
    "cardNumber": "**** 3904",
    "cardId": "xxxx",
    "orderNo": "xxxx",
    "merchantName": "Google Earthquake Net"
  }
}

Field notes

  • reason: Provider reason code (example: R7).
  • amount: Transaction amount as string.
  • transactionAt: Unix time in milliseconds.
  • type: Transaction type code (see mapping below).
  • originalAmount: Original amount before FX conversion (if applicable).
  • originalCurrency: Original currency before FX conversion (if applicable).
  • currency: Settlement currency.
  • status: Transaction status code (see mapping below). Webhooks are not sent when status = 4 (POSTED).
  • direction: Transaction direction code (see mapping below).
  • cardNumber: Masked card number (last 4 digits).
  • merchantName: Merchant name (if available).

Transaction status mapping (details.status)

  • 1: Successful
  • 2: Failed
  • 3: In Process
  • 4: Posted
  • 5: Not Posted
  • 6: Payment Failed
  • 7: Cancelled

Transaction type mapping (details.type)

  • 1: Recharge / Mortgage
  • 2: Consumption
  • 3: Refund
  • 4: Cash Withdrawal
  • 5: Redemption
  • 6: Management Fee
  • 7: Other
  • 8: Replacement
  • 9: Deactivate
  • 10: Refund Reversal

Transaction direction mapping (details.direction)

  • 1: Income
  • 2: Expense

3DS confirmation event (3DS_CONFIRM)

{
  "event": "3DS_CONFIRM",
  "details": {
    "amount": "1",
    "type": "code",
    "cardNumber": "**** 7777",
    "cardId": "xxxx",
    "merchants": "Google ",
    "transactionCurrency": "USD",
    "transactionDate": 1767962820000,
    "validateCode": "X435zgUYJK3P"
  }
}

Field notes

  • amount: Transaction amount.
  • type: 3DS confirmation type from provider (commonly code).
  • cardNumber: Masked card number (last 4 digits).
  • merchants: Merchant name provided by the processor.
  • transactionCurrency: Transaction currency.
  • transactionDate: Unix time in milliseconds.
  • validateCode: Code used with POST /wallet-cards/validate-code to confirm the payment.
kazawallet-logo
Home
Wallets
Transfer
Exchange
Withdraw
Deposit
Cards
Mass Payout
Rates
History
Help Center
Blog