الرئيسية إرسال تحويل عملات سحب إيداع البطاقات أسعار الصرف سجل المعاملات تثبيت التطبيق

Kazawallet API

Accept payments, manage wallets, run payouts and issue virtual cards. One reference for every Kazawallet endpoint.

BASE URL

https://outdoor.kasroad.com/wallet

Introduction

The Kazawallet API lets merchants accept payments, manage wallets, run payouts, and issue virtual cards programmatically.

Overview

All requests are made over HTTPS to the base URL below. Requests and responses use JSON. Authenticate every request with your API key and secret, which you can request from the support team.

Base URL

bash

https://outdoor.kasroad.com/wallet

Keep your credentials secret

Never expose your API key or secret in client-side code. Treat them like passwords and only use them from your backend.

Authentication

Authentication is handled through request headers. Most merchant endpoints require all three headers below; the payment-link endpoint only needs the API key.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Payment Methods

Some endpoints require a payment method id. The most common method ids per environment are listed below.

Development

USDT-TRC20

15

USDT-BEP20

13

Production

USDT-TRC20

118

USDT-ERC20

116

USDT-SOL

117

USDT-BEP20

115

Payment Links

Create hosted payment links and verify the webhooks they send back to you.

Create Payment Link

POST

/createPaymentLink

Create a payment link to initiate a payment for a specified amount and currency. Share the returned link with your customer to collect the payment.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`Content-Type` required	string	application/json

Request Body

json

{
  "amount": "YOUR_AMOUNT_HERE",
  "currency": "USD",
  "email": "MERCHANT EMAIL",
  "ref": "YOUR_UNIQUE_REFERENCE",
  "redirectUrl": "https://yourwebsite.com?kazawallet=success"
}

cURL Example

bash

curl -X POST 'https://outdoor.kasroad.com/wallet/createPaymentLink' \
-H 'x-api-key: XXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{
  "amount": "YOUR_AMOUNT_HERE",
  "currency": "USD",
  "email": "MERCHANT EMAIL",
  "redirectUrl": "https://yourwebsite.com?kazawallet=success"
}'

Payment Link Webhook

To be notified when a customer completes a payment, set a webhook URL in your profile. Once the payment is made, a POST request with the payment details is sent to your webhook URL ONLY ONE TIME.

Webhook Payload

Field	Type	Description
`order_id`	string	The id of the payment link.
`secret`	string	A secret code for verification.
`amount`	string	The amount paid.
`ref`	string	Sent back with the payload — for example, use it to reference the user id in your system.
`status`	string	Either "fulfilled" or "timed_out", indicating whether the link was paid.
`currency`	string	The code of the currency used.

Webhook Signature Verification

To verify the authenticity of a webhook request, calculate a verification code and compare it with the secret received from the API.

PHP Example

php

<?php

$amount = 'your_amount'; // Replace with the actual amount
$order_id = 'your_order_id'; // Replace with the actual payment link ID
$kazawalletApiKey = 'your_kazawallet_api_key'; // Replace with the actual kazawallet API key
$kazawalletApiSecret = 'your_kazawallet_api_secret'; // Replace with the actual kazawallet API secret

// Create the secret string by concatenating the amount, order_id, and kazawalletApiKey
$secretString = $amount . ':::' . $order_id . ':::' . $kazawalletApiKey;

// Generate a SHA-256 hash of the secret string
$hashDigest = hash('sha256', $secretString, true);

// Generate an HMAC-SHA512 hash of the SHA-256 hash using the kazawalletApiSecret
$hmacDigest = hash_hmac('sha512', $hashDigest, $kazawalletApiSecret, true);

// Encode the HMAC-SHA512 hash in Base64
$hmacDigestBase64 = base64_encode($hmacDigest);

// Output the Base64-encoded HMAC-SHA512 signature
echo $hmacDigestBase64;

?>

1. Receive the webhook POST request with the order_id, secret, status and amount. 2. Use the example above to calculate the HMAC-SHA512 signature from the received order_id, status and amount, plus your API key and secret. 3. Compare the calculated signature with the secret received from the webhook. 4. If they match, the request is authentic and you can process the payment confirmation.

Withdrawals

Create withdrawal requests from a user wallet to a supported payment method.

Create Withdrawal Request

POST

/createWithdrawalRequest

Create a withdrawal request from a user wallet. The request includes the user email, currency, amount, a note, the payment method, and any custom fields required by that method.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret (request it from the support team).
`Content-Type` required	string	application/json

Request Body

Field	Type	Description
`email` required	string	The email address of the merchant.
`currency` required	string	The currency code (e.g. USD).
`amount` required	string	The amount to withdraw.
`note`	string	A note for the withdrawal request.
`paymentMethod` required	string	The id of the payment method.
`fields`	object	A set of custom fields based on the payment method.

Example Request Body

json

{
  "email": "dummy.email@example.com",
  "currency": "USD",
  "amount": "10",
  "note": "This is a note",
  "paymentMethod": "xx",
  "fields": {
    "field1": "xxx",
    "field2": "yyy"
  }
}

Example Pending Response

json

{
  "success": true,
  "createdPayment": {
    "id": "wi-xxxxxx",
    "status": "pending",
    "message": "",
    "note": "note",
    "amount": "amount",
    "currency": "currency code",
    "paymentMethod": "Payment Method title",
    "actualAmount": "actual amount"
  }
}

Example Success Response

json

{
  "success": true,
  "createdPayment": {
    "id": "wi-xxxxxx",
    "status": "approved",
    "message": "message",
    "note": "note",
    "amount": "amount",
    "currency": "currency code",
    "paymentMethod": "Payment Method title",
    "actualAmount": "actual amount"
  }
}

Example Error Response

json

{
  "success": false,
  "error": "Error miss some critical information to create the request"
}

Withdrawal Webhook Content

json

{
  "userEmail": "xxx@xxx.com",
  "type": "withdraw",
  "username": "user name",
  "transactionId": "wi-xxxxxxx",
  "actualAmount": "510000",
  "createdAt": "2026-02-17",
  "currencyName": "currency name",
  "currencySymbol": "currency symbol",
  "paymentMethodTitle": "payment method",
  "status": "payment status (pending | processing | approved | rejected)",
  "adminMessage": "msg"
}

cURL Example

bash

curl --location 'https://outdoor.kasroad.com/wallet/createWithdrawalRequest' \
--header 'x-api-key: xxxxxxxxxxx' \
--header 'x-api-secret: xxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "dummy.email@example.com",
  "currency": "USD",
  "amount": "10",
  "note": "This is a note",
  "paymentMethod": "xx",
  "fields": {
    "field1": "xxxx",
    "field2": "yyyy"
  }
}'

PHP Example

php

<?php

$curl = curl_init();

$data = [
    "email" => "dummy.email@example.com",
    "currency" => "USD",
    "amount" => "10",
    "note" => "This is a note",
    "paymentMethod" => "xx",
    "fields" => [
        "field1" => "xxxx",
        "field2" => "yyyy"
    ]
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://outdoor.kasroad.com/wallet/createWithdrawalRequest',
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'x-api-key: xxxxxxxxxxx',
        'x-api-secret: xxxxxxxxxxx',
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;
?>

Notes

Ensure the x-api-key and x-api-secret headers are set with your API credentials. The fields object should contain the custom fields required by the selected payment method.

Merchant Wallet

Read rates and balances, inspect payment method fields, and move funds.

Get Rates

GET

/get-rate

Get the current exchange rates.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Response Success

json

{
  "success": true,
  "rate": {}
}

Response Error

json

{
  "data": null,
  "error": {}
}

Usage Example

javascript

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

Get Balance

GET

/get-merchant-wallets

Get the merchant wallet balances.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Response Success

json

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

Response Error

json

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

Usage Example

javascript

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

Get Payment Method Fields

GET

/get-payment-method-fields?id={payment method Id}&field={slug name}

Get deposit and withdraw fields for a specific payment method.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Response Success

json

{
  "withdraw": [],
  "deposit": []
}

Response Error

json

{
  "data": null,
  "error": {
    "status": 400,
    "name": "ERROR_NAME",
    "message": "error msg",
    "details": {}
  }
}

Usage Example

javascript

const result = await axios.get(
  'https://outdoor.kasroad.com/wallet/get-payment-method-fields?id=64&field=alamya_target',
  {
    headers: {
      'x-api-key': 'XXXXX',
      'x-api-secret': 'XXXXX',
      'merchant-email': 'merchant@example.com'
    }
  }
);

Create Deposit

POST

/createDepositRequest

Create a deposit request for a user.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.

Request Payload

json

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

json

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

Response Error

json

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

Webhook Request Content

json

{
  "userEmail": "xxx@xxx.com",
  "type": "deposit",
  "username": "user name",
  "transactionId": "de-xxxxxxx",
  "actualAmount": "484950",
  "createdAt": "2026-02-17",
  "currencyName": "currency name",
  "currencySymbol": "currency symbol",
  "paymentMethodTitle": "payment method",
  "resultType": "deposit",
  "status": "pending"
}

Usage Example

javascript

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"
    }
  },
  {
    headers: {
      'x-api-key': 'XXXXX',
      'x-api-secret': 'XXXXX'
    }
  }
);

Create Transfer

POST

/transfer-from-merchant-to-user

Create a transfer from the merchant to a user.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.

Request Payload

json

{
  "merchantEmail": "Merchant Email",
  "userEmail": "User Email",
  "currency": "currency_code",
  "amount": "amount",
  "notes": "Merchant Note"
}

Response Success

json

{
  "success": true,
  "details": {
    "transfer": "tr-XXXXXX"
  }
}

Response Error

json

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

Usage Example

javascript

const result = await axios.post(
  'https://outdoor.kasroad.com/wallet/transfer-from-merchant-to-user',
  {
    "merchantEmail": "mhd1@user.com",
    "email": "mhd2@user.com",
    "currency": "SYP",
    "amount": "500000",
    "note": "note"
  },
  {
    headers: {
      'x-api-key': 'XXXXX',
      'x-api-secret': 'XXXXX'
    }
  }
);

Cards

Issue and manage Kazawallet virtual cards for your users.

Issue Card

POST

/wallet-cards/create-then-topup

Create a card for a user. Use cardType to choose the tier — basic (default) or plus. The issue fee and top-up fees may differ per tier and per merchant plan.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Payload

javascript

{
  currency: "currency_code",
  amount: "Top up amount",
  cardType: "basic" | "plus", // optional, default "basic"
  remark: "user remark" // optional
}

Response Success

json

{
  "created": true,
  "topuped": true,
  "cardId": "kc-xxxxxxx",
  "create": {
    "id": "kc-xxxxxx",
    "amount": "issue fee"
  },
  "topup": {
    "id": "topup Id",
    "amount": "topup amount with fees"
  }
}

Response Error

json

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

Usage Example

javascript

const result = await axios.post(
  'https://outdoor.kasroad.com/wallet/wallet-cards/create-then-topup',
  {
    "currency": "currency_code",
    "amount": "100",
    "cardType": "plus"
  },
  {
    headers: {
      'x-api-key': 'XXXXX',
      'x-api-secret': 'XXXXX',
      'merchant-email': 'merchant@example.com'
    }
  }
);

Top up Card

PUT

/wallet-cards/topup

Top up a card for a user.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Payload

javascript

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

Response Success

json

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

Response Error

json

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

Usage Example

javascript

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

Cancel Card

PUT

/wallet-cards/cancel

Cancel a card for a user.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Payload

javascript

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

Response Success

json

{
  "Success": true
}

Response Error

json

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

Usage Example

javascript

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

Lock Card

PUT

/wallet-cards/lock

Lock a card for a user.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Payload

javascript

{
  cardId: "kc-xxxxxxx"
}

Response Success

json

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

Response Error

json

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

Usage Example

javascript

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

Unlock Card

PUT

/wallet-cards/unlock

Unlock a card for a user.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Payload

javascript

{
  cardId: "kc-xxxxxxx"
}

Response Success

json

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

Response Error

json

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

Usage Example

javascript

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

Get Cards List

GET

/get-merchant-wallets-cards

Get the list of wallet cards.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Response Success

json

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

json

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

Usage Example

javascript

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

Get Card Details

GET

/wallet-cards/get-card-details

Get the details of a card.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Query

javascript

{
  cardId: "kc-xxxxxxx"
}

Response Success

json

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

json

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

Usage Example

javascript

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

Get Card Transactions

GET

/wallet-cards/get-transactions

Get the transactions of a card.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Query

javascript

{
  cardId: "kc-xxxxxxx",
  page: 1,
  pageSize: 15
}

Response Success

json

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

json

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

Transaction State

SUCCESSFUL

1

FAILED

2

IN_PROCESS

3

POSTED

4

NOT_POSTED

5

PAYMENT_FAILED

6

CANCELLED

7

Usage Example

javascript

const result = await axios.get(
  'https://outdoor.kasroad.com/wallet/wallet-cards/get-transactions?cardId=kc-xxxxxxxx&page=1&pageSize=15',
  {
    headers: {
      'x-api-key': 'XXXXX',
      'x-api-secret': 'XXXXX',
      'merchant-email': 'merchant@example.com'
    }
  }
);

Validate Code

POST

/wallet-cards/validate-code

Validate a 3DS confirmation code for a card payment.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Payload

javascript

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

Response Success

json

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

Response Error

json

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

Usage Example

javascript

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

Create Card (without top-up)

Deprecated

POST

/wallet-cards/create

Create a card request for a user without an initial top-up. This endpoint is deprecated — use Issue Card (POST /wallet-cards/create-then-topup) for new integrations.

Deprecated

This endpoint should not be used for new integrations. Use POST /wallet-cards/create-then-topup instead.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Payload

javascript

{
  currency: "currency_code",
  cardType: "basic" | "plus", // optional, default "basic"
  remark: "user remark" // optional
}

Response Success

json

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

Response Error

json

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

Usage Example

javascript

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

Gift Cards

Issue gift cards for a set amount and currency, then redeem them into a user account.

Create Gift Card

POST

/gift-card/create

Create a gift card for a specified amount and currency. The expiry date is fixed at 1 year from the creation date and cannot be set by the merchant.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Body

Field	Type	Description
`giftCardCurrency` required	string	The currency code (e.g. usd).
`amount` required	string	The gift card amount.

The gift card expiry date is set automatically to 1 year from the creation date. It cannot be provided in the request; any expiry sent in the body is ignored.

Request Body

json

{
  "giftCardCurrency": "currency code",
  "amount": "1000"
}

Response Success

json

{
  "success": true,
  "details": {
    "uid": "GI-xxxxxxxxx",
    "code": "xxxxxxxxxxx",
    "amount": "1000",
    "currency": "USD",
    "expiryDate": "2027-01-02T00:00:00.000Z"
  }
}

Response Error

json

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

Usage Example

javascript

const result = await axios.post(
  'https://outdoor.kasroad.com/wallet/gift-card/create',
  {
    "giftCardCurrency": "USD",
    "amount": "1000"
  },
  {
    headers: {
      'x-api-key': 'XXXXX',
      'x-api-secret': 'XXXXX',
      'merchant-email': 'merchant@example.com'
    }
  }
);

Redeem Gift Card

POST

/gift-card/redeem

Redeem a gift card into a user account using its code.

Headers

Field	Type	Description
`x-api-key` required	string	Your API key.
`x-api-secret` required	string	Your API secret key.
`merchant-email` required	string	The merchant account email.

Request Body

Field	Type	Description
`giftCardCode` required	string	The gift card code to redeem.
`userEmail` required	string	The email of the user redeeming the gift card.

Request Body

json

{
  "giftCardCode": "xxxxxxx",
  "userEmail": "user email"
}

Response Success

json

{
  "success": true,
  "details": {
    "giftCardId": "GI-xxxxxxx",
    "redeem": true
  }
}

Response Error

json

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

Usage Example

javascript

const result = await axios.post(
  'https://outdoor.kasroad.com/wallet/gift-card/redeem',
  {
    "giftCardCode": "xxxxxxx",
    "userEmail": "user@example.com"
  },
  {
    headers: {
      'x-api-key': 'XXXXX',
      'x-api-secret': 'XXXXX',
      'merchant-email': 'merchant@example.com'
    }
  }
);

Card Webhooks

Events Kazawallet sends to your webhook URL for card activity.

Overview

When a merchant sets a webhookUrl in their profile, Kazawallet sends a POST request to that URL for the following card events. These webhooks are sent after Kazawallet receives the event from the card issuer.

Events

CC_CONSUME

Card consumption

CC_REFUND

Card refund

CC_RECHARGE

Card recharge

3DS_CONFIRM

3DS confirmation

Webhook Body (always)

json

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

Card Transaction Events

Common shape for CC_CONSUME, CC_REFUND and CC_RECHARGE events.

Example (CC_CONSUME)

json

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

Field	Type	Description
`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).

Status (details.status)

Successful

Failed

In Process

Posted

Not Posted

Payment Failed

Cancelled

Type (details.type)

Recharge / Mortgage

Consumption

Refund

Cash Withdrawal

Redemption

Management Fee

Other

Replacement

Deactivate

Refund Reversal

Direction (details.direction)

Income

Expense

3DS Confirmation Event

Sent as the 3DS_CONFIRM event when a card payment requires 3DS confirmation.

Example (3DS_CONFIRM)

json

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

Field Notes

Field	Type	Description
`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.