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

03-Virtual-Cards

Virtual Cards Guide#

This guide covers the complete flow for virtual (digital) card issuance and activation.

Prerequisites#

āœ… Complete Getting Started guide
āœ… Received USER_CREATE_RESULT webhook with status APPROVED
āœ… Have user_id and template_id from previous steps

Step 3a: Order a Virtual Card#

After receiving the USER_CREATE_RESULT webhook with status APPROVED, you can order a virtual card using the user ID from Step 2 and template ID from Step 1.

Endpoint#

Request Fields#

user_id - User ID (from Getting Started guide)
template_id - Template ID (from Getting Started guide)
deposit_amount - Initial deposit amount (required for templates with requires_initial_deposit = true)

Request Examples#

Standard Virtual Card#

{
  "user_id": 12345,
  "template_id": 123
}

Virtual Card with Initial Deposit (for templates with requires_initial_deposit = true)#

{
  "user_id": 12345,
  "template_id": 456,
  "deposit_amount": 500.0
}
Important for Deposit Cards:
deposit_amount must be within the template's recharge_min_limit and recharge_max_limit
The deposit will be automatically loaded onto the card after creation
Merchant balance will be charged: card fee + deposit amount + recharge fees

Response#

{
  "card_id": 67890,
  "card_number": "",
  "status": "TBA"
}

Card Status Processing#

After ordering, the card initially has status PENDING. Before performing any operations on the card, you must wait for the webhook confirmation.

Webhook Event: CARD_APPLY_RESULT#

You will receive a webhook notification with the card creation result:
{
  "card_id": 12345,
  "status": "SUCCESS",
  "occur_time": 1691249025085
}
Webhook Fields:
card_id - Card unique ID
status - Application status (SUCCESS or FAILED)
occur_time - Trigger time (milliseconds)

Card Status After Application#

After receiving CARD_APPLY_RESULT webhook with status SUCCESS, the card status changes based on the template's needs_activation setting:

For Templates with needs_activation = true#

Card status becomes TBA (To Be Activated)
Card requires activation before use (proceed to Step 4a)
Card details are not available until activation

For Templates with needs_activation = false#

Card status becomes ACTIVE
Card is ready for use immediately
Card details are available
No activation required (skip Step 4a, proceed to Card Operations for recharge)

Important Notes#

The issue fee specified in the card template will be deducted from your merchant account balance
Always wait for CARD_APPLY_RESULT webhook before checking card status
Card operations are only possible after successful application confirmation

Step 4a: Card Activation (For Virtual Cards with needs_activation = true)#

Note: This step is only required for virtual cards with needs_activation = true. If your card template has needs_activation = false, skip to Card Operations.
To activate the virtual card, you need to call the update status endpoint.

Endpoint#

Request Fields#

user_id - User ID
card_id - Card ID
alter - Set to "ACTIVATE"
Note: PIN is not used for virtual cards (PIN is only required for physical card activation)

Request Example#

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

Response#

{
  "message": "Operation requested"
}

Card Activation Confirmation#

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

Webhook Event: CARD_ACTIVATE_RESULT#

{
  "card_id": 12345,
  "card_number": "1234567890123456",
  "status": "SUCCESS",
  "occur_time": 1691249025085
}
Webhook Fields:
card_id - Card unique ID
card_number - Card number (now available)
status - Activation status (SUCCESS or FAILED)
occur_time - Trigger time (milliseconds)
Important: Only after receiving this webhook with status: "SUCCESS", the card becomes fully operational for transactions.

Card Status After Activation#

Event Type: CARD_ACTIVATE_RESULT
The card status will change to "ACTIVE"
Card details (number, CVV, expiry date) become available
Card is ready for transactions and recharge

Next Steps#

Card is Ready! šŸŽ‰#

Your virtual card is now active and ready to use. Continue to:
Card Operations - Recharge your card and perform operations
Get Card Details - Retrieve sensitive card information (number, CVV, expiry)
Monitor Transactions - Track card usage via webhooks

Common Operations#

1.
Recharge Card - Add funds to the card balance
2.
Get Balance - Check current card balance
3.
Get Card Info - Retrieve card details and status
4.
Get Transactions - View transaction history

Error Handling#

Common Issues#

Card Application Failed: Check merchant balance for issuance fees (including deposit amount if required)
Activation Failed: Verify card is in TBA status and template supports activation
Invalid Template: Ensure template is available for virtual cards

Troubleshooting#

1.
Always wait for webhook confirmations before proceeding to next steps
2.
Check card status via API if unsure about current state
3.
Verify sufficient merchant balance for fees (including deposit amount and deposit fees)
4.
For deposit-required cards, ensure deposit_amount is provided and within valid limits
5.
Check template properties (requires_initial_deposit) before including deposit in request
6.
Contact support with card_id for specific issues

Related Documentation#

Getting Started - Initial setup and user registration
Card Operations - Managing active cards
Event Types - Complete webhook reference
Reference - Card states and important considerations
Modified atĀ 2025-09-24 13:36:19
Previous
02-Getting-Started
Next
04-Physical-Cards
Built with