Skip to content

CHANNEL_AGGREGATOR_SETUP.md

Latest commit

 

History

History
242 lines (193 loc) · 6.76 KB

CHANNEL_AGGREGATOR_SETUP.md

File metadata and controls

242 lines (193 loc) · 6.76 KB
Raw

🔗 Channel Aggregator Integration Setup

📋 Overview

CPay has been successfully integrated with your channel aggregator service, providing unified access to all payment channels through a single API key. This integration allows CPay to process payments through InstaPay, GCash, Maya, PesoNet, Korean Banks, and other channels using your unified API.

🔑 Test Credentials

The following test credentials have been configured:

Merchant Name: CPAY
Merchant No.: 300000064613
SHA256 Key: uck6lo8sdjaarqf3sohdoovdvvn0kdnk

🛠️ Implementation Details

Channel Aggregator Gateway

  • File: functions/src/integrations/channel-aggregator.ts
  • Features:
    • SHA256 signature generation for security
    • Unified API for all payment channels
    • Transaction status checking
    • Available channels listing
    • Comprehensive error handling

Updated Payment Gateways

  • File: functions/src/integrations/payment-gateways.ts
  • Changes:
    • All individual gateways now use the channel aggregator
    • Legacy gateway classes maintained for backward compatibility
    • Unified gateway for new partner integrations

New Firebase Functions

  • processChannelAggregatorTransfer - Direct channel aggregator transfers
  • checkChannelAggregatorStatus - Check transaction status
  • getChannelAggregatorChannels - Get available channels

🔧 Environment Configuration

Add the following environment variables to your Firebase Functions:

# Channel Aggregator Configuration
CHANNEL_AGGREGATOR_MERCHANT_NAME=CPAY
CHANNEL_AGGREGATOR_MERCHANT_NO=300000064613
CHANNEL_AGGREGATOR_SHA256_KEY=uck6lo8sdjaarqf3sohdoovdvvn0kdnk
CHANNEL_AGGREGATOR_ENDPOINT=https://api.channelaggregator.com

📊 Available Channels

The system supports the following channels:

Channel Type Description
instapay Bank Transfer InstaPay bank transfers
gcash Mobile Wallet GCash mobile payments
maya Digital Bank Maya digital banking
pesonet Bank Transfer PesoNet bank transfers
korean-bank Bank Transfer Korean bank transfers
other Generic Other payment channels

🚀 Usage Examples

Direct Channel Aggregator Transfer

// Frontend call
const result = await callDispatcher('processChannelAggregatorTransfer', {
  amount: 1000,
  currency: 'PHP',
  referenceId: 'TXN123456',
  description: 'Payment for services',
  channel: 'instapay',
  recipientInfo: {
    accountNumber: '1234567890',
    accountName: 'John Doe',
    bankCode: 'BDO'
  }
});

Check Transaction Status

const status = await callDispatcher('checkChannelAggregatorStatus', {
  transactionId: 'TXN123456'
});

Get Available Channels

const channels = await callDispatcher('getChannelAggregatorChannels', {});

Legacy Gateway Calls (Still Supported)

// These now use the channel aggregator internally
const instapayResult = await callDispatcher('processInstaPayTransfer', {
  amount: 1000,
  currency: 'PHP',
  referenceId: 'TXN123456',
  description: 'InstaPay transfer',
  recipientInfo: {
    accountNumber: '1234567890',
    accountName: 'John Doe',
    bankCode: 'BDO'
  }
});

🔒 Security Features

Signature Generation

  • SHA256 HMAC signatures for all API calls
  • Timestamp validation
  • Request payload integrity verification

Authentication

  • Firebase Auth integration
  • Role-based access control
  • Rate limiting on all endpoints

Audit Logging

  • All transactions logged
  • Webhook signature verification
  • Comprehensive error tracking

📈 Monitoring & Logging

Transaction Monitoring

  • Real-time transaction status tracking
  • Success/failure rate monitoring
  • Performance metrics collection

Error Handling

  • Graceful error responses
  • Detailed error logging
  • Automatic retry mechanisms

Audit Trail

  • Complete transaction history
  • User action logging
  • System event tracking

🔄 Webhook Integration

The system is ready to receive webhooks from your channel aggregator service:

Webhook Endpoints

  • /handleInstaPayWebhook - InstaPay callbacks
  • /handleGCashWebhook - GCash callbacks
  • /handleMayaWebhook - Maya callbacks
  • /handleKoreanBankWebhook - Korean bank callbacks

Webhook Security

  • Signature verification for all webhooks
  • Timestamp validation
  • Duplicate request prevention

🚀 Deployment

1. Set Environment Variables

firebase functions:config:set channel_aggregator.merchant_name="CPAY"
firebase functions:config:set channel_aggregator.merchant_no="300000064613"
firebase functions:config:set channel_aggregator.sha256_key="uck6lo8sdjaarqf3sohdoovdvvn0kdnk"
firebase functions:config:set channel_aggregator.endpoint="https://api.channelaggregator.com"

2. Deploy Functions

firebase deploy --only functions

3. Test Integration

# Test channel aggregator transfer
curl -X POST https://your-region-your-project.cloudfunctions.net/cpayDispatcher \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
  -d '{
    "action": "processChannelAggregatorTransfer",
    "payload": {
      "amount": 100,
      "currency": "PHP",
      "referenceId": "TEST123",
      "description": "Test transfer",
      "channel": "instapay",
      "recipientInfo": {
        "accountNumber": "1234567890",
        "accountName": "Test User",
        "bankCode": "BDO"
      }
    }
  }'

📊 Benefits

Unified Integration

  • Single API key for all channels
  • Consistent interface across all payment methods
  • Simplified maintenance and updates

Enhanced Security

  • SHA256 signature verification
  • Comprehensive audit logging
  • Role-based access control

Scalability

  • Easy addition of new channels
  • High-performance transaction processing
  • Robust error handling

Monitoring

  • Real-time transaction tracking
  • Comprehensive logging
  • Performance metrics

🎯 Next Steps

  1. Deploy to Production: Use the provided test credentials
  2. Test All Channels: Verify each payment channel works correctly
  3. Monitor Performance: Watch logs and metrics
  4. Configure Webhooks: Set up webhook endpoints for real-time updates
  5. Go Live: Switch to production credentials when ready

📞 Support

For any issues or questions regarding the channel aggregator integration:

  1. Check the Firebase Functions logs
  2. Review the audit trail for transaction details
  3. Verify environment variable configuration
  4. Test with the provided test credentials

🎉 Channel Aggregator Integration Complete!

The CPay system is now fully integrated with your channel aggregator service and ready to process payments through all available channels using your unified API.