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

02-Getting-Started

Getting Started with B2B Card Management#

This guide covers the initial setup steps required before issuing any type of card. These steps are common for both virtual and physical cards.

Prerequisites#

Active merchant account with B2B platform
Configured webhook URL in Admin Console or API
API credentials and encryption keys

Step 1: Get Available Card Templates#

Before registering a user or ordering a card, you need to get the list of available card templates to understand the requirements and choose the appropriate one.

Endpoint#

Response#

The response will contain a list of available card templates with their properties:
id - Template identifier (use this as template_id in registration)
description - Template name/description
type - Card type (e.g., "Virtual")
payment_system - Payment system (e.g., "Visa", "Mastercard")
apply_fee - Card issuance fee
recharge_fee - Fee charged for each recharge
refund_fee - Fee charged for refunds
activate_min_limit - Minimum amount for initial recharge
recharge_min_limit - Minimum amount per recharge
recharge_max_limit - Maximum amount per recharge
limit_per_tx - Maximum amount per transaction
limit_per_day - Daily spending limit
limit_per_month - Monthly spending limit
requires_kyc - Whether KYC verification is required for this template
requires_phone_only - Whether phone number is required for this template
needs_activation - Whether card needs activation before use
requires_initial_deposit - Whether card requires an initial deposit amount when ordering

Step 2: User Registration#

Register a new user in the system. The registration process depends on the card template's provider and requirements.

Endpoint#

Required Fields#

email - User's email address
template_id - ID of the card template (obtained from Step 1)

Additional Requirements Based on Template#

For Phone-Only Templates (requires_phone_only = true)#

phone_number - User's phone number
dial_code - International dial code

For KYC-Required Templates (requires_kyc = true)#

kyc_data - Complete KYC information object containing:
first_name, last_name
gender - User's gender (MALE, FEMALE, UNSPECIFIED)
date_of_birth - Date in ISO format (YYYY-MM-DD)
country_code - ISO 3166-1 alpha-3 country code (e.g., "USA", "GBR", "CAN")
identification_type - Type of identification document (PASSPORT, IDENTITY_CARD, DRIVER_LICENSE)
identification_number - Document number
front_img_base64 - Base64 encoded front image of ID
back_img_base64 - Base64 encoded back image of ID
handheld_img_base64 - Base64 encoded handheld image with ID
issue - Issuance date of the credential. Long type millisecond timestamp.
expiry - Expiration date of the credential. Long type millisecond timestamp.
region - ISO 3166-2 subdivision code (e.g., "US-CA" for California)
city, postcode, address_line - Address information

Request Examples#

Basic Registration (No KYC)#

{
  "email": "user@example.com",
  "template_id": 123
}

Phone-Only Registration#

{
  "email": "user@example.com",
  "template_id": 124,
  "phone_number": "5551234567",
  "dial_code": "+1"
}

Full KYC Registration (USA Example)#

{
  "email": "user@example.com",
  "template_id": 125,
  "phone_number": "5551234567",
  "dial_code": "+1",
  "kyc_data": {
    "first_name": "John",
    "last_name": "Doe",
    "gender": "MALE",
    "date_of_birth": "1990-01-01",
    "country_code": "USA",
    "identification_type": "DRIVER_LICENSE",
    "identification_number": "DL123456789",
    "front_img_base64": "...",
    "back_img_base64": "...",
    "handheld_img_base64": "...",
    "issue": 946684800000,
    "expiry": 2145916800000, 
    "region": "US-CA",
    "city": "Los Angeles",
    "postcode": "90210",
    "address_line": "123 Main Street"
  }
}

Response#

{
  "user_id": 12345
}
The response contains the user ID (user_id) which is required for all subsequent card operations.

User Status Processing#

After registration, the user initially has status PROCESSING. Before ordering cards, you must wait for the webhook confirmation.

Webhook Event: USER_CREATE_RESULT#

You will receive a webhook notification with the registration result:
{
  "user_id": 12345,
  "status": "APPROVED",
  "message": "Reason of rejection"
}
Webhook Fields:
user_id - User unique ID
status - User status (APPROVED or REJECTED)
message - Reason of rejection (optional, only for rejected users)

Data Format Requirements#

Important Data Format Guidelines:
1.
Country Codes: Must use ISO 3166-1 alpha-3 format (3 letters)
✅ Correct: "USA", "GBR", "CAN", "FRA", "DEU"
❌ Incorrect: "US", "UK", "CA", "FR", "DE"
2.
Region Codes: Must use ISO 3166-2 format (country-subdivision)
✅ Correct: "US-CA", "US-NY", "US-TX", "GB-ENG", "CA-ON"
❌ Incorrect: "California", "New York", "Texas", "England", "Ontario"
3.
Phone Numbers: Must be valid for the specified country
Use proper formatting without spaces or special characters
Example for USA: "5551234567" with dial_code "+1"
4.
Date Format: Always use ISO 8601 format (YYYY-MM-DD)
✅ Correct: "1990-01-01"
❌ Incorrect: "01/01/1990", "1990/01/01"

Next Steps#

Important: Only proceed to card ordering/assignment after receiving USER_CREATE_RESULT webhook with status APPROVED.

Choose Your Card Type#

Virtual Cards: Continue to Virtual Cards Guide
Physical Cards: Continue to Physical Cards Guide

Security#

All requests must be encrypted according to the API Security Implementation Guide
All webhook notifications are encrypted using the same security protocol
See Integration Guide for webhook integration details
Modified at 2025-09-29 09:44:06
Previous
01-README
Next
03-Virtual-Cards
Built with