193 lines
4.6 KiB
Markdown
193 lines
4.6 KiB
Markdown
# RTGS System to DBIS Nostro/Vostro API Mapping
|
|
|
|
## Overview
|
|
|
|
This document provides patterns for mapping local RTGS (Real-Time Gross Settlement) systems to the DBIS Nostro/Vostro API.
|
|
|
|
## Common RTGS Patterns
|
|
|
|
### Pattern 1: REST API Integration
|
|
|
|
Many modern RTGS systems expose REST APIs:
|
|
|
|
```typescript
|
|
// RTGS API call
|
|
const rtgsTransfer = {
|
|
fromAccount: "ACC123",
|
|
toAccount: "ACC456",
|
|
amount: 1000.00,
|
|
currency: "USD",
|
|
valueDate: "2024-01-15",
|
|
reference: "REF123"
|
|
};
|
|
|
|
// Map to DBIS API
|
|
const dbisTransfer = {
|
|
fromAccountId: rtgsTransfer.fromAccount,
|
|
toAccountId: rtgsTransfer.toAccount,
|
|
amount: rtgsTransfer.amount.toString(),
|
|
currency: rtgsTransfer.currency,
|
|
valueDate: rtgsTransfer.valueDate,
|
|
reference: rtgsTransfer.reference
|
|
};
|
|
```
|
|
|
|
### Pattern 2: Database Integration
|
|
|
|
For RTGS systems with direct database access:
|
|
|
|
```sql
|
|
-- RTGS Database Query
|
|
SELECT
|
|
transaction_id,
|
|
debit_account,
|
|
credit_account,
|
|
amount,
|
|
currency,
|
|
value_date,
|
|
reference
|
|
FROM rtgs_transactions
|
|
WHERE status = 'PENDING';
|
|
|
|
-- Map to DBIS API request
|
|
```
|
|
|
|
### Pattern 3: Message Queue Integration
|
|
|
|
For RTGS systems using message queues (Kafka, RabbitMQ, etc.):
|
|
|
|
```typescript
|
|
// Consume from RTGS queue
|
|
consumer.on('message', (rtgsMessage) => {
|
|
const transfer = mapRtgstoDbis(rtgsMessage);
|
|
await nostroVostroService.createTransfer(transfer);
|
|
});
|
|
```
|
|
|
|
## Generic RTGS Adapter Template
|
|
|
|
```typescript
|
|
import { BasePluginAdapter } from './generic-adapter';
|
|
|
|
export class GenericRtgAdapter extends BasePluginAdapter {
|
|
constructor(config: Record<string, unknown> = {}) {
|
|
super('GenericRTGS', '1.0.0', config);
|
|
}
|
|
|
|
mapTransfer(internalData: unknown): TransferCreateRequest {
|
|
const rtgsTx = internalData as {
|
|
fromAccount: string;
|
|
toAccount: string;
|
|
amount: number;
|
|
currency: string;
|
|
valueDate: string;
|
|
reference?: string;
|
|
};
|
|
|
|
return {
|
|
fromAccountId: rtgsTx.fromAccount,
|
|
toAccountId: rtgsTx.toAccount,
|
|
amount: rtgsTx.amount.toString(),
|
|
currency: rtgsTx.currency,
|
|
valueDate: rtgsTx.valueDate,
|
|
reference: rtgsTx.reference,
|
|
metadata: {
|
|
source: 'RTGS',
|
|
rtgsSystem: this.config.rtgsSystemName,
|
|
},
|
|
};
|
|
}
|
|
|
|
// Implement other methods based on RTGS system capabilities
|
|
}
|
|
```
|
|
|
|
## Account Mapping
|
|
|
|
RTGS accounts typically map directly:
|
|
|
|
```typescript
|
|
mapAccount(internalData: unknown): AccountCreateRequest {
|
|
const rtgsAccount = internalData as {
|
|
accountNumber: string;
|
|
customerId: string;
|
|
correspondentId: string;
|
|
currency: string;
|
|
accountType: 'NOSTRO' | 'VOSTRO';
|
|
};
|
|
|
|
return {
|
|
ownerParticipantId: rtgsAccount.customerId,
|
|
counterpartyParticipantId: rtgsAccount.correspondentId,
|
|
ibanOrLocalAccount: rtgsAccount.accountNumber,
|
|
currency: rtgsAccount.currency,
|
|
accountType: rtgsAccount.accountType,
|
|
};
|
|
}
|
|
```
|
|
|
|
## Reconciliation
|
|
|
|
RTGS reconciliation typically involves:
|
|
|
|
1. **Statement Comparison**: Compare RTGS statements with DBIS transactions
|
|
2. **Balance Matching**: Match opening/closing balances
|
|
3. **Transaction Matching**: Match individual transactions by reference
|
|
|
|
```typescript
|
|
async reconcile(accountId: string, asOfDate: Date): Promise<{matched: number; breaks: unknown[]}> {
|
|
// Get RTGS statement
|
|
const rtgsStatement = await this.getRtgStatement(accountId, asOfDate);
|
|
|
|
// Get DBIS transactions
|
|
const dbisTransactions = await nostroVostroService.listTransfers({
|
|
fromAccountId: accountId,
|
|
valueDate: asOfDate,
|
|
});
|
|
|
|
// Match transactions
|
|
const matched = this.matchTransactions(rtgsStatement, dbisTransactions);
|
|
const breaks = this.findBreaks(rtgsStatement, dbisTransactions);
|
|
|
|
return { matched, breaks };
|
|
}
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Idempotency**: Use RTGS transaction IDs as idempotency keys
|
|
2. **Error Handling**: Map RTGS error codes to DBIS error codes
|
|
3. **Retry Logic**: Implement retry for transient RTGS failures
|
|
4. **Monitoring**: Monitor RTGS integration health
|
|
5. **Audit Trail**: Log all RTGS interactions
|
|
|
|
## Common RTGS Systems
|
|
|
|
### Fedwire (US)
|
|
- Format: Proprietary
|
|
- Integration: SWIFT or direct API
|
|
|
|
### TARGET2 (EU)
|
|
- Format: ISO 20022
|
|
- Integration: See ISO 20022 mapping guide
|
|
|
|
### CHAPS (UK)
|
|
- Format: SWIFT MT
|
|
- Integration: See SWIFT mapping guide
|
|
|
|
### CHIPS (US)
|
|
- Format: Proprietary
|
|
- Integration: Direct API or database
|
|
|
|
## Implementation Checklist
|
|
|
|
- [ ] Understand RTGS system architecture
|
|
- [ ] Identify integration method (API, DB, MQ)
|
|
- [ ] Map RTGS data structures to DBIS
|
|
- [ ] Implement adapter class
|
|
- [ ] Test with sandbox RTGS environment
|
|
- [ ] Implement error handling
|
|
- [ ] Set up monitoring
|
|
- [ ] Document RTGS-specific mappings
|
|
|