BananaTech
  1. Guides
BananaTech
  • API Security Implementation Guide
  • Guides
    • 01-README
    • 02-Getting-Started
    • 03-Virtual-Cards
    • 04-Physical-Cards
    • 05-Card-Operations
  • Webhook
    • Integration Guide
    • Event Types
  • Merchant related APIs
    • Get Account Balance
      POST
    • Get Card Templates
      POST
    • Set Webhook URL
      POST
    • Get Webhook Records
      POST
  • User related APIs
    • Register
      POST
    • Get Users
      POST
  • Card related APIs
    • Apply
      POST
    • Recharge
      POST
    • Update Status
      POST
    • Get Balance
      POST
    • Get Information
      POST
    • Get Transactions
      POST
    • Assign (for Physical cards only)
      POST
    • Set PIN (for Physical cards only)
      POST
    • 3DS Confirm
      POST
  • Schemas
    • Sample Schemas
      • Pet
      • Category
      • Tag
  1. Guides

05-Card-Operations

Card Operations Guide#

This guide covers common operations available for both virtual and physical cards after they have been successfully activated.

Prerequisites#

Choose your card type for activation requirements:

For Virtual Cards#

✅ Complete Virtual Cards Guide
✅ Card status is ACTIVE (either immediately after application or after activation)

For Physical Cards#

✅ Complete Physical Cards Guide
✅ Card was successfully assigned (received CARD_ASSIGN_RESULT webhook with status SUCCESS)
✅ Card was activated with PIN (received CARD_ACTIVATE_RESULT webhook)
Once your card meets the above requirements, you can perform all operations described in this guide.

Card Recharge#

Add funds to your card balance. This operation works identically for both virtual and physical cards after activation.

Endpoint#

Request Fields#

user_id - User ID
card_id - Card ID
amount - Recharge amount

Request Example#

{
  "user_id": 12345,
  "card_id": 67890,
  "amount": 100.0
}

Response#

{
  "message": "Card recharge request sent successfully"
}

Recharge Confirmation#

After the recharge is processed by the banking provider, you will receive a webhook notification.

Webhook Event: CARD_RECHARGE_RESULT#

{
  "card_id": 12345,
  "transaction_id": 67890,
  "receive_amount": 100.0,
  "status": "SUCCESS",
  "currency": "USD",
  "occur_time": 1691249025085
}
Webhook Fields:
card_id - Card unique ID
transaction_id - Transaction unique ID
receive_amount - Amount received on the card
status - Recharge status (SUCCESS or FAILED)
currency - Currency of the recharge
occur_time - Trigger time (milliseconds)

Important Notes#

The recharge amount must be greater than or equal to recharge_min_limit specified in the card template
The total amount deducted from your merchant account will be: recharge amount + recharge fee
The recharge process is asynchronous
Card balance will reflect the recharged amount after processing
Works identically for both virtual and physical cards

Get Card Balance#

Retrieve current card balance information.

Endpoint#

Request Fields#

user_id - User ID
card_id - Card ID

Request Example#

{
  "user_id": 12345,
  "card_id": 67890
}

Response#

{
  "balance": 150.5,
  "refund_amount": 0.0,
  "currency": "USD"
}
Response Fields:
balance - Current available balance
refund_amount - Amount available for refund (if applicable)
currency - Currency code

Get Card Information#

Retrieve detailed card information and status.

Endpoint#

Request Fields#

user_id - User ID
card_id - Card ID

Request Example#

{
  "user_id": 12345,
  "card_id": 67890
}

Response#

{
  "number": "1234567890123456",
  "cvv": "123",
  "expiry_date": "12/25",
  "status": "ACTIVE",
  "template_id": 1
}
Response Fields:
number - Card number (masked or full depending on permissions)
cvv - Card verification value
expiry_date - Card expiration date (MM/YY format)
status - Current card status
template_id - Card template identifier

Get Transaction History#

Retrieve card transaction history with filtering options.

Endpoint#

Request Fields#

user_id - User ID (optional for admin access)
card_id - Card ID (optional, for filtering by specific card)
skip - Number of records to skip (pagination)
limit - Maximum number of records to return
search - Search term (optional)
status - Filter by transaction status (optional)
type - Filter by transaction type (optional)
start_date - Filter from date (optional)
end_date - Filter to date (optional)

Request Example#

{
  "card_id": 67890,
  "skip": 0,
  "limit": 10,
  "status": "SUCCESS"
}

Response#

{
  "data": [
    {
      "id": 12345,
      "card_id": 67890,
      "amount": 100.0,
      "currency": "USD",
      "type": "RECHARGE",
      "status": "SUCCESS",
      "created_at": "2024-01-15T10:30:00Z",
      "merchant_name": "RECHARGE"
    }
  ],
  "total": 1
}

Card Status Management#

Update card status for lock/unlock operations.

Endpoint#

Available Status Changes#

Lock Card#

{
  "user_id": 12345,
  "card_id": 67890,
  "alter": "LOCK"
}

Unlock Card#

{
  "user_id": 12345,
  "card_id": 67890,
  "alter": "UNLOCK"
}

Close Card#

{
  "user_id": 12345,
  "card_id": 67890,
  "alter": "CLOSE"
}

Response#

{
  "message": "Operation requested"
}

Status Change Confirmation#

For lock/unlock operations, you will receive a webhook notification:

Webhook Event: CARD_STATUS_CHANGE#

{
  "card_id": 12345,
  "status": "SUCCESS",
  "card_status": "LOCKED",
  "occur_time": 1691249025085
}
For card closure, you will receive:

Webhook Event: CARD_CLOSE_RESULT#

{
  "card_id": 12345,
  "transaction_id": 67890,
  "refund_amount": 100.0,
  "status": "SUCCESS",
  "occur_time": 1691550780785
}

Physical Card Specific Operations#

Change PIN (Physical Cards Only)#

Update the PIN code for physical cards.

Endpoint#

Request Fields#

user_id - User ID
card_id - Card ID
pin - New PIN code (4-6 digits)

Request Example#

{
  "user_id": 12345,
  "card_id": 67890,
  "pin": "6789"
}

Response#

{
  "message": "PIN set successfully"
}

Error Handling#

Common Issues#

Insufficient Balance#

Issue: Recharge amount below minimum limit
Solution: Check card template recharge_min_limit

Invalid Card State#

Issue: Operation not allowed in current card status
Solution: Verify card is ACTIVE before operations

Merchant Balance#

Issue: Insufficient merchant account balance
Solution: Add funds to merchant account

Invalid Request Data#

Issue: Missing or invalid request parameters
Solution: Verify all required fields are provided

Troubleshooting Steps#

1.
Verify Card Status: Ensure card is ACTIVE before operations
2.
Check Webhooks: Wait for confirmation webhooks before proceeding
3.
Validate Amounts: Ensure amounts meet template requirements
4.
Monitor Balance: Check merchant account balance for fees
5.
Review Logs: Check API response codes and error messages

Related Documentation#

Getting Started - Initial setup and user registration
Virtual Cards - Virtual card specific flow
Physical Cards - Physical card specific flow
Event Types - Complete webhook reference
Modified at 2025-08-04 15:20:16
Previous
04-Physical-Cards
Next
Integration Guide
Built with