Customer Reserved Account

Provide customers with dedicated virtual bank accounts for seamless payment collection. Customer Reserved Accounts are virtual bank accounts assigned to specific customers, allowing them to make payments directly via bank transfer to their unique account number.

🏦 Virtual Accounts

Unique account numbers for each customer

⚡ Instant Recognition

Automatic payment attribution and processing

How It Works

🔄 Account Creation Flow

Create Customer

Generate Account

System creates a unique virtual account number for the customer

Share Details

Provide customer with their dedicated account information

Receive Payments

Customer transfers funds to their virtual account

Auto-Processing

Payments are automatically credited to customer’s balance

💰 Benefits for Businesses

🎯 Payment Attribution

Automatic identification of payment source

📊 Better Tracking

Detailed payment history per customer

⚡ Faster Processing

Reduced manual reconciliation effort

API Implementation

🚀 Create Customer Reserved Account

curl https://api.payvessel.com/api/v1/customers \
  -H "api-key: PVKEY-3ZO1QOSQH83C5Q3PBCVUT1" \
  -H "api-secret: Bearer PVSECRET-OZJD0SZ2F2WOTXAF" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "address": {
      "line1": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "create_reserved_account": true,
    "account_type": "individual",
    "metadata": {
      "customer_id": "internal_12345",
      "tier": "premium"
    }
  }'

📝 Request Parameters

Required Customer Information

name (string) - Full name of the customer email (string) - Valid email address phone (string) - Phone number with country code create_reserved_account (boolean) - Set to true to create virtual account

Address Information

address.line1 (string) - Street address address.city (string) - City name address.state (string) - State or province address.postal_code (string) - ZIP or postal code address.country (string) - Two-letter country code

Optional Parameters

account_type (string) - “individual” or “business” metadata (object) - Custom key-value pairs preferred_bank (string) - Preferred bank for virtual account

✅ Successful Response

{
  "id": "cust_1234567890abcdef",
  "object": "customer",
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "+1234567890",
  "created": 1634567890,
  "reserved_account": {
    "id": "acc_1234567890abcdef",
    "account_number": "1234567890",
    "account_name": "John Doe",
    "bank_name": "Payvessel Bank",
    "bank_code": "044",
    "routing_number": "123456789",
    "status": "active",
    "balance": 0,
    "currency": "USD"
  },
  "address": {
    "line1": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "metadata": {
    "customer_id": "internal_12345",
    "tier": "premium"
  }
}

Implementation Examples

🟨 Node.js Implementation

const payvessel = require('payvessel')('PVKEY-3ZO1QOSQH83C5Q3PBCVUT1');

async function createCustomerReservedAccount(customerData) {
  try {
    const customer = await payvessel.customers.create({
      name: customerData.name,
      email: customerData.email,
      phone: customerData.phone,
      address: customerData.address,
      create_reserved_account: true,
      account_type: customerData.account_type || 'individual',
      metadata: customerData.metadata || {}
    });

    if (customer.reserved_account) {
      console.log('Reserved account created:', customer.reserved_account.account_number);
      
      // Send account details to customer
      await sendAccountDetailsToCustomer(customer);
      
      return customer;
    } else {
      throw new Error('Failed to create reserved account');
    }
  } catch (error) {
    console.error('Account creation error:', error.message);
    throw error;
  }
}

async function sendAccountDetailsToCustomer(customer) {
  const accountDetails = {
    accountNumber: customer.reserved_account.account_number,
    accountName: customer.reserved_account.account_name,
    bankName: customer.reserved_account.bank_name,
    routingNumber: customer.reserved_account.routing_number
  };
  
  // Send via email, SMS, or your preferred communication method
  await emailService.sendAccountDetails(customer.email, accountDetails);
}

// Usage example
const customer = await createCustomerReservedAccount({
  name: 'John Doe',
  email: '[email protected]',
  phone: '+1234567890',
  address: {
    line1: '123 Main Street',
    city: 'New York',
    state: 'NY',
    postal_code: '10001',
    country: 'US'
  },
  account_type: 'individual',
  metadata: {
    customer_id: 'internal_12345'
  }
});

🐍 Python Implementation

import payvessel

payvessel.api_key = "PVKEY-3ZO1QOSQH83C5Q3PBCVUT1"

def create_customer_reserved_account(customer_data):
    try:
        customer = payvessel.Customer.create(
            name=customer_data['name'],
            email=customer_data['email'],
            phone=customer_data['phone'],
            address=customer_data['address'],
            create_reserved_account=True,
            account_type=customer_data.get('account_type', 'individual'),
            metadata=customer_data.get('metadata', {})
        )

        if customer.reserved_account:
            print(f'Reserved account created: {customer.reserved_account.account_number}')
            
            # Send account details to customer
            send_account_details_to_customer(customer)
            
            return customer
        else:
            raise Exception('Failed to create reserved account')
    
    except payvessel.error.PayvesselError as e:
        print(f'Account creation error: {e.user_message}')
        raise

def send_account_details_to_customer(customer):
    account_details = {
        'account_number': customer.reserved_account.account_number,
        'account_name': customer.reserved_account.account_name,
        'bank_name': customer.reserved_account.bank_name,
        'routing_number': customer.reserved_account.routing_number
    }
    
    # Send via email service
    email_service.send_account_details(customer.email, account_details)

# Usage example
customer = create_customer_reserved_account({
    'name': 'John Doe',
    'email': '[email protected]',
    'phone': '+1234567890',
    'address': {
        'line1': '123 Main Street',
        'city': 'New York',
        'state': 'NY',
        'postal_code': '10001',
        'country': 'US'
    },
    'account_type': 'individual',
    'metadata': {
        'customer_id': 'internal_12345'
    }
})

🐘 PHP Implementation

<?php
require_once('vendor/autoload.php');

\Payvessel\Payvessel::setApiKey("PVKEY-3ZO1QOSQH83C5Q3PBCVUT1");

function createCustomerReservedAccount($customerData) {
    try {
        $customer = \Payvessel\Customer::create([
            'name' => $customerData['name'],
            'email' => $customerData['email'],
            'phone' => $customerData['phone'],
            'address' => $customerData['address'],
            'create_reserved_account' => true,
            'account_type' => $customerData['account_type'] ?? 'individual',
            'metadata' => $customerData['metadata'] ?? []
        ]);

        if ($customer->reserved_account) {
            echo "Reserved account created: " . $customer->reserved_account->account_number . "\n";
            
            // Send account details to customer
            sendAccountDetailsToCustomer($customer);
            
            return $customer;
        } else {
            throw new Exception('Failed to create reserved account');
        }
    } catch (\Payvessel\Exception\ApiErrorException $e) {
        echo "Account creation error: " . $e->getMessage() . "\n";
        throw $e;
    }
}

function sendAccountDetailsToCustomer($customer) {
    $accountDetails = [
        'account_number' => $customer->reserved_account->account_number,
        'account_name' => $customer->reserved_account->account_name,
        'bank_name' => $customer->reserved_account->bank_name,
        'routing_number' => $customer->reserved_account->routing_number
    ];
    
    // Send via email service
    EmailService::sendAccountDetails($customer->email, $accountDetails);
}

// Usage example
$customer = createCustomerReservedAccount([
    'name' => 'John Doe',
    'email' => '[email protected]',
    'phone' => '+1234567890',
    'address' => [
        'line1' => '123 Main Street',
        'city' => 'New York',
        'state' => 'NY',
        'postal_code' => '10001',
        'country' => 'US'
    ],
    'account_type' => 'individual',
    'metadata' => ['customer_id' => 'internal_12345']
]);
?>

Account Management

💰 Check Account Balance

curl https://api.payvessel.com/api/v1/customers/cust_1234567890abcdef/reserved_account \
  -H "api-key: PVKEY-3ZO1QOSQH83C5Q3PBCVUT1" \
  -H "api-secret: Bearer PVSECRET-OZJD0SZ2F2WOTXAF"

📊 Account Balance Response

{
  "id": "acc_1234567890abcdef",
  "account_number": "1234567890",
  "account_name": "John Doe",
  "bank_name": "Payvessel Bank",
  "status": "active",
  "balance": 15000,
  "currency": "USD",
  "last_transaction": {
    "id": "txn_1234567890abcdef",
    "amount": 5000,
    "type": "credit",
    "description": "Bank transfer deposit",
    "created": 1634567890
  }
}

📝 Transaction History

curl "https://api.payvessel.com/api/v1/customers/cust_1234567890abcdef/reserved_account/transactions" \
  -H "api-key: PVKEY-3ZO1QOSQH83C5Q3PBCVUT1" \
  -H "api-secret: Bearer PVSECRET-OZJD0SZ2F2WOTXAF"

Use Cases

🏢 Business Applications

Educational Institutions

Student Fee Collection:

Assign unique accounts to each student
Parents can transfer fees directly
Automatic fee reconciliation
Generate payment confirmations

Property Management

Rent Collection:

Individual accounts for each tenant
Automated rent payment tracking
Late payment identification
Maintenance fee collection

Marketplace Platforms

Seller Accounts:

Dedicated accounts for marketplace sellers
Customer payments directly to seller accounts
Automatic commission deduction
Real-time settlement

🎯 Benefits by Industry

🏥 Healthcare

Patient billing accounts
Insurance payment processing
Medical expense tracking
Automated reconciliation

🚚 Logistics

Customer shipping accounts
Prepaid balance management
COD alternative solution
Fleet payment tracking

🏪 Retail

Customer loyalty accounts
Layaway payment plans
Bulk order processing
Corporate account management

💼 Professional Services

Client retainer accounts
Project-based billing
Recurring service fees
Expense reimbursement

Webhook Integration

🔔 Account Events

Monitor reserved account activity with webhooks:

// Webhook handler for reserved account events
app.post('/webhook/reserved-account', (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case 'reserved_account.credit':
      handleAccountCredit(event.data);
      break;
    case 'reserved_account.debit':
      handleAccountDebit(event.data);
      break;
    case 'reserved_account.low_balance':
      notifyLowBalance(event.data);
      break;
  }
  
  res.status(200).send('OK');
});

function handleAccountCredit(accountData) {
  // Process incoming payment
  console.log(`Account ${accountData.account_number} credited with ${accountData.amount}`);
  
  // Update customer balance
  // Send confirmation to customer
  // Trigger any business logic
}

Security Considerations

🔒 Account Security

🔐 Access Control

Customer-specific account access
Encrypted account numbers
Secure API authentication
Audit trail maintenance

🛡️ Fraud Prevention

Transaction monitoring
Unusual activity detection
Account status management
Compliance reporting

📋 Compliance Requirements

KYC Verification - Customer identity verification required
AML Monitoring - Anti-money laundering compliance
Data Protection - GDPR/CCPA compliance for customer data
Financial Regulations - Local banking regulation compliance

Account Limits: Reserved accounts may have transaction limits based on customer verification level and regulatory requirements.

Ready to implement customer reserved accounts?

🚀 API Integration

Explore the complete API documentation

🔔 Webhook Setup

Configure webhooks for account events

Getting started

Use cases

API Basics

Accept Payment

Send Money & Payouts

Wallets

Verify Identities

Bill Payments

Cardholders

Card Issuance

Webhook

​Customer Reserved Account

🏦 Virtual Accounts

⚡ Instant Recognition

​How It Works

​🔄 Account Creation Flow

​💰 Benefits for Businesses

🎯 Payment Attribution

📊 Better Tracking

⚡ Faster Processing

​API Implementation

​🚀 Create Customer Reserved Account

​📝 Request Parameters

​✅ Successful Response

​Implementation Examples

​🟨 Node.js Implementation

​🐍 Python Implementation

​🐘 PHP Implementation

​Account Management

​💰 Check Account Balance

​📊 Account Balance Response

​📝 Transaction History

​Use Cases

​🏢 Business Applications

​🎯 Benefits by Industry

🏥 Healthcare

🚚 Logistics

🏪 Retail

💼 Professional Services

​Webhook Integration

​🔔 Account Events

​Security Considerations

​🔒 Account Security

🔐 Access Control

🛡️ Fraud Prevention

​📋 Compliance Requirements

🚀 API Integration

🔔 Webhook Setup

Customer Reserved Account

How It Works

🔄 Account Creation Flow

💰 Benefits for Businesses

API Implementation

🚀 Create Customer Reserved Account

📝 Request Parameters

✅ Successful Response

Implementation Examples

🟨 Node.js Implementation

🐍 Python Implementation

🐘 PHP Implementation

Account Management

💰 Check Account Balance

📊 Account Balance Response

📝 Transaction History

Use Cases

🏢 Business Applications

🎯 Benefits by Industry

Webhook Integration

🔔 Account Events

Security Considerations

🔒 Account Security

📋 Compliance Requirements