dbis_core/docs/nostro-vostro/rtgs-mapping.md

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:

// 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:

-- 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.):

// Consume from RTGS queue
consumer.on('message', (rtgsMessage) => {
  const transfer = mapRtgstoDbis(rtgsMessage);
  await nostroVostroService.createTransfer(transfer);
});

Generic RTGS Adapter Template

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:

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

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