463 lines
11 KiB
Markdown
463 lines
11 KiB
Markdown
# DBIS Nostro/Vostro Network — Central Bank Implementation Guide
|
|
|
|
## Overview
|
|
|
|
This guide provides step-by-step instructions for Central Banks (SCBs) to implement and deploy the DBIS Nostro/Vostro Network API for their regulated Financial Institutions (FIs).
|
|
|
|
## Table of Contents
|
|
|
|
1. [Prerequisites](#prerequisites)
|
|
2. [Phased Rollout Strategy](#phased-rollout-strategy)
|
|
3. [Infrastructure Setup](#infrastructure-setup)
|
|
4. [API Configuration](#api-configuration)
|
|
5. [FI Onboarding](#fi-onboarding)
|
|
6. [Testing & Validation](#testing--validation)
|
|
7. [Production Deployment](#production-deployment)
|
|
8. [Best Practices](#best-practices)
|
|
9. [Troubleshooting](#troubleshooting)
|
|
|
|
## Prerequisites
|
|
|
|
### Technical Requirements
|
|
|
|
- **API Gateway**: RESTful API gateway supporting OpenAPI 3.0.3
|
|
- **Authentication**: OAuth2 server with Mutual TLS (mTLS) support
|
|
- **Database**: PostgreSQL 12+ or compatible database
|
|
- **Network**: Secure network connectivity to DBIS infrastructure
|
|
- **HSM**: Hardware Security Module for key management (recommended)
|
|
|
|
### Regulatory Requirements
|
|
|
|
- Central Bank authorization to operate Nostro/Vostro services
|
|
- Compliance with local banking regulations
|
|
- Data protection and privacy compliance (GDPR, local regulations)
|
|
- Audit trail capabilities
|
|
|
|
### Organizational Requirements
|
|
|
|
- Designated API administrator
|
|
- Technical support team
|
|
- Compliance officer
|
|
- Relationship manager for FI onboarding
|
|
|
|
## Phased Rollout Strategy
|
|
|
|
### Phase 1: Pilot / Sandbox (Months 1-3)
|
|
|
|
**Objective**: Validate API functionality with limited participants
|
|
|
|
**Activities**:
|
|
1. Deploy sandbox environment
|
|
2. Onboard 1-3 Tier-1 FIs
|
|
3. Test core endpoints:
|
|
- Participant registration
|
|
- Account creation
|
|
- Transfer initiation
|
|
- Balance queries
|
|
4. Collect feedback and iterate
|
|
|
|
**Success Criteria**:
|
|
- All core endpoints functional
|
|
- No critical bugs
|
|
- Positive FI feedback
|
|
- Performance meets SLA requirements
|
|
|
|
### Phase 2: Expansion (Months 4-6)
|
|
|
|
**Objective**: Broaden FI participation and add advanced features
|
|
|
|
**Activities**:
|
|
1. Onboard additional Tier-1 and Tier-2 FIs
|
|
2. Enable webhook integration
|
|
3. Implement reconciliation automation
|
|
4. Add GRU/FX endpoints
|
|
5. Performance optimization
|
|
|
|
**Success Criteria**:
|
|
- 10+ FIs onboarded
|
|
- Webhook delivery success rate > 99%
|
|
- Reconciliation accuracy > 99.9%
|
|
- API response time < 200ms (p95)
|
|
|
|
### Phase 3: Full Production (Months 7+)
|
|
|
|
**Objective**: Full-scale deployment with all features
|
|
|
|
**Activities**:
|
|
1. Onboard all eligible FIs
|
|
2. Integration with GRU/FX and GAS
|
|
3. Ω-Layer-aligned settlement
|
|
4. Advanced monitoring and alerting
|
|
5. Continuous improvement
|
|
|
|
**Success Criteria**:
|
|
- All eligible FIs onboarded
|
|
- 24/7 availability (99.9% uptime)
|
|
- Full GRU/FX integration
|
|
- Complete audit trail
|
|
|
|
## Infrastructure Setup
|
|
|
|
### 1. API Gateway Configuration
|
|
|
|
#### Server Configuration
|
|
|
|
```yaml
|
|
# Example configuration
|
|
servers:
|
|
- url: https://api.yourcb.gov/api/v1/nostro-vostro
|
|
description: Production
|
|
- url: https://sandbox.yourcb.gov/api/v1/nostro-vostro
|
|
description: Sandbox
|
|
```
|
|
|
|
#### Security Configuration
|
|
|
|
1. **OAuth2 Setup**:
|
|
- Configure OAuth2 authorization server
|
|
- Set up client credentials flow
|
|
- Configure scopes: `nv.read`, `nv.write`, `nv.reconcile`, `gru.read`, `gru.convert`
|
|
|
|
2. **Mutual TLS (mTLS)**:
|
|
- Generate server certificates
|
|
- Configure client certificate validation
|
|
- Set up certificate revocation list (CRL) checking
|
|
|
|
3. **Rate Limiting**:
|
|
- Configure per-FI rate limits
|
|
- Set up burst allowances
|
|
- Monitor and alert on rate limit violations
|
|
|
|
### 2. Database Setup
|
|
|
|
#### Schema Migration
|
|
|
|
```bash
|
|
# Run Prisma migrations
|
|
npx prisma migrate deploy
|
|
|
|
# Verify schema
|
|
npx prisma studio
|
|
```
|
|
|
|
#### Indexes
|
|
|
|
Ensure the following indexes are created for optimal performance:
|
|
- `participantId` on `nostro_vostro_participants`
|
|
- `accountId` on `nostro_vostro_accounts`
|
|
- `transferId` and `idempotencyKey` on `nostro_vostro_transfers`
|
|
- `reportId` on `nostro_vostro_reconciliations`
|
|
|
|
### 3. Integration Points
|
|
|
|
#### DBIS Core Integration
|
|
|
|
- Connect to DBIS GAS (Global Atomic Settlement) network
|
|
- Configure Ω-Layer finality integration
|
|
- Set up GRU/FX rate feeds
|
|
- Configure webhook delivery infrastructure
|
|
|
|
#### Internal Systems Integration
|
|
|
|
- RTGS system integration
|
|
- Core banking system integration
|
|
- Compliance system integration
|
|
- Reporting system integration
|
|
|
|
## API Configuration
|
|
|
|
### 1. Environment Variables
|
|
|
|
```bash
|
|
# API Configuration
|
|
API_BASE_URL=https://api.yourcb.gov/api/v1/nostro-vostro
|
|
API_VERSION=1.0.0
|
|
|
|
# Database
|
|
DATABASE_URL=postgresql://user:pass@localhost:5432/nostro_vostro
|
|
|
|
# Authentication
|
|
OAUTH2_TOKEN_URL=https://auth.yourcb.gov/oauth/token
|
|
OAUTH2_CLIENT_ID=your_client_id
|
|
OAUTH2_CLIENT_SECRET=your_client_secret
|
|
|
|
# Security
|
|
MTLS_ENABLED=true
|
|
MTLS_CA_CERT_PATH=/path/to/ca.crt
|
|
|
|
# Webhooks
|
|
WEBHOOK_RETRY_ATTEMPTS=5
|
|
WEBHOOK_TIMEOUT_MS=30000
|
|
|
|
# GRU/FX
|
|
GRU_FX_ENABLED=true
|
|
GRU_FX_RATE_SOURCE=DBIS_GRU
|
|
```
|
|
|
|
### 2. API Documentation
|
|
|
|
- Host OpenAPI spec at `/api-docs` endpoint
|
|
- Provide interactive Swagger UI
|
|
- Generate client SDKs (Java, .NET, Python, Node.js)
|
|
- Publish API reference documentation
|
|
|
|
### 3. Monitoring & Logging
|
|
|
|
- Set up application performance monitoring (APM)
|
|
- Configure structured logging
|
|
- Set up alerting for:
|
|
- API errors (> 1% error rate)
|
|
- High latency (> 500ms p95)
|
|
- Failed webhook deliveries
|
|
- Reconciliation breaks
|
|
|
|
## FI Onboarding
|
|
|
|
### 1. Pre-Onboarding Checklist
|
|
|
|
**For Central Bank**:
|
|
- [ ] API documentation published
|
|
- [ ] Sandbox environment available
|
|
- [ ] Test credentials generated
|
|
- [ ] Support channels established
|
|
- [ ] Onboarding process documented
|
|
|
|
**For Financial Institution**:
|
|
- [ ] Technical team assigned
|
|
- [ ] Development environment ready
|
|
- [ ] Network connectivity established
|
|
- [ ] Security certificates obtained
|
|
- [ ] Compliance approval received
|
|
|
|
### 2. Onboarding Process
|
|
|
|
#### Step 1: Registration
|
|
|
|
1. FI submits participant registration request
|
|
2. CB reviews and approves
|
|
3. CB creates participant record via API
|
|
4. CB provides participant ID and credentials
|
|
|
|
#### Step 2: Account Setup
|
|
|
|
1. FI requests Nostro/Vostro account creation
|
|
2. CB creates account via API
|
|
3. CB provides account ID and details
|
|
4. FI verifies account in their system
|
|
|
|
#### Step 3: Integration Testing
|
|
|
|
1. FI implements API client
|
|
2. FI tests in sandbox environment
|
|
3. CB validates test transactions
|
|
4. Both parties sign off on testing
|
|
|
|
#### Step 4: Production Access
|
|
|
|
1. CB grants production credentials
|
|
2. FI switches to production endpoint
|
|
3. CB monitors initial transactions
|
|
4. Both parties confirm successful go-live
|
|
|
|
### 3. Onboarding Timeline
|
|
|
|
- **Registration**: 1-2 business days
|
|
- **Account Setup**: 1 business day
|
|
- **Integration Testing**: 2-4 weeks
|
|
- **Production Access**: 1 business day
|
|
|
|
**Total**: 3-5 weeks
|
|
|
|
## Testing & Validation
|
|
|
|
### 1. Test Scenarios
|
|
|
|
#### Core Functionality Tests
|
|
|
|
- Participant creation and retrieval
|
|
- Account creation and balance queries
|
|
- Transfer initiation and status tracking
|
|
- Reconciliation report generation
|
|
- Webhook subscription and delivery
|
|
|
|
#### Error Handling Tests
|
|
|
|
- Invalid authentication
|
|
- Insufficient balance
|
|
- Duplicate idempotency keys
|
|
- Invalid account references
|
|
- Network timeouts
|
|
|
|
#### Performance Tests
|
|
|
|
- Concurrent request handling
|
|
- Large batch transfers
|
|
- High-frequency balance queries
|
|
- Webhook delivery under load
|
|
|
|
### 2. Test Playbook
|
|
|
|
See [Test Playbook](./test-playbook.md) for detailed test cases.
|
|
|
|
### 3. Validation Checklist
|
|
|
|
- [ ] All endpoints functional
|
|
- [ ] Error responses correct
|
|
- [ ] Idempotency working
|
|
- [ ] Webhooks delivering
|
|
- [ ] Reconciliation accurate
|
|
- [ ] Performance meets SLA
|
|
- [ ] Security validated
|
|
- [ ] Audit trail complete
|
|
|
|
## Production Deployment
|
|
|
|
### 1. Pre-Deployment Checklist
|
|
|
|
- [ ] Infrastructure provisioned
|
|
- [ ] Database migrated
|
|
- [ ] API deployed
|
|
- [ ] Monitoring configured
|
|
- [ ] Alerting configured
|
|
- [ ] Backup strategy in place
|
|
- [ ] Disaster recovery tested
|
|
- [ ] Security audit completed
|
|
- [ ] Documentation published
|
|
- [ ] Support team trained
|
|
|
|
### 2. Deployment Steps
|
|
|
|
1. **Deploy to Staging**:
|
|
- Deploy latest code
|
|
- Run database migrations
|
|
- Verify all services healthy
|
|
- Run smoke tests
|
|
|
|
2. **Deploy to Production**:
|
|
- Schedule maintenance window
|
|
- Deploy code (blue-green deployment)
|
|
- Run database migrations
|
|
- Verify services healthy
|
|
- Monitor for issues
|
|
|
|
3. **Post-Deployment**:
|
|
- Verify API endpoints
|
|
- Check monitoring dashboards
|
|
- Validate webhook delivery
|
|
- Confirm reconciliation working
|
|
- Notify FIs of deployment
|
|
|
|
### 3. Rollback Plan
|
|
|
|
- Keep previous version available
|
|
- Database migrations reversible
|
|
- Feature flags for gradual rollout
|
|
- Automated rollback triggers
|
|
|
|
## Best Practices
|
|
|
|
### 1. Security
|
|
|
|
- **Always use mTLS** for production
|
|
- **Rotate credentials** regularly
|
|
- **Monitor for anomalies** in API usage
|
|
- **Implement rate limiting** per FI
|
|
- **Log all API calls** for audit
|
|
|
|
### 2. Performance
|
|
|
|
- **Cache frequently accessed data** (participants, accounts)
|
|
- **Use connection pooling** for database
|
|
- **Implement pagination** for large result sets
|
|
- **Optimize database queries** with proper indexes
|
|
- **Monitor and tune** based on metrics
|
|
|
|
### 3. Reliability
|
|
|
|
- **Implement retry logic** for transient failures
|
|
- **Use idempotency keys** for all transfers
|
|
- **Set up health checks** and monitoring
|
|
- **Plan for disaster recovery**
|
|
- **Test failover procedures** regularly
|
|
|
|
### 4. Compliance
|
|
|
|
- **Maintain complete audit trail**
|
|
- **Implement data retention policies**
|
|
- **Ensure GDPR/privacy compliance**
|
|
- **Regular compliance audits**
|
|
- **Document all procedures**
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### 1. Authentication Failures
|
|
|
|
**Symptoms**: 401 Unauthorized errors
|
|
|
|
**Solutions**:
|
|
- Verify OAuth2 token is valid
|
|
- Check mTLS certificate is valid
|
|
- Ensure correct scopes are requested
|
|
- Verify token hasn't expired
|
|
|
|
#### 2. Transfer Failures
|
|
|
|
**Symptoms**: Transfers stuck in PENDING status
|
|
|
|
**Solutions**:
|
|
- Check account balances
|
|
- Verify account status (ACTIVE)
|
|
- Check for holds on accounts
|
|
- Review rejection reasons
|
|
|
|
#### 3. Webhook Delivery Failures
|
|
|
|
**Symptoms**: Webhooks not received by FI
|
|
|
|
**Solutions**:
|
|
- Verify webhook URL is accessible
|
|
- Check webhook signature validation
|
|
- Review delivery logs
|
|
- Test webhook endpoint manually
|
|
|
|
#### 4. Reconciliation Breaks
|
|
|
|
**Symptoms**: Reconciliation reports show breaks
|
|
|
|
**Solutions**:
|
|
- Review transaction history
|
|
- Check for pending transfers
|
|
- Verify account balances
|
|
- Compare with internal records
|
|
|
|
### Support Contacts
|
|
|
|
- **Technical Support**: api-support@yourcb.gov
|
|
- **Emergency Hotline**: +1-XXX-XXX-XXXX
|
|
- **Documentation**: https://docs.yourcb.gov/nostro-vostro
|
|
|
|
## Next Steps
|
|
|
|
1. Review this guide with your technical team
|
|
2. Set up sandbox environment
|
|
3. Begin FI onboarding process
|
|
4. Schedule production deployment
|
|
5. Monitor and iterate
|
|
|
|
## Additional Resources
|
|
|
|
- [API Reference](./api-reference.md)
|
|
- [Plugin Development Guide](./plugin-development-guide.md)
|
|
- [ISO 20022 Mapping Guide](./iso20022-mapping.md)
|
|
- [SWIFT Mapping Guide](./swift-mapping.md)
|
|
- [RTGS Mapping Guide](./rtgs-mapping.md)
|
|
|
|
---
|
|
|
|
**Version**: 1.0.0
|
|
**Last Updated**: 2024-01-15
|
|
**Contact**: cb-support@dbis.org
|
|
|