gru_emoney_token-factory/docs/adapters/SEPAAdapter.md

SEPA Adapter Specification

Overview

The SEPA adapter connects ChainID 138 eMoney Token Factory to the Single Euro Payments Area (SEPA) network for EUR-denominated transfers. Supports both SCT (SEPA Credit Transfer) and SCT Inst (SEPA Instant Credit Transfer).

Architecture

ChainID 138 Events → SEPA Adapter → SEPA Network → Settlement Confirmation → ChainID 138

Responsibilities

1. Event Watching: Monitor TriggerCreated events for SEPA rail type
2. SEPA Message Construction: Build ISO-20022 messages compliant with SEPA rulebook
3. SEPA Submission: Submit via SEPA clearing system (via bank or payment service provider)
4. Attestation: Submit confirmations to SettlementOrchestrator

Event Monitoring

Watched Events

• RailTriggerRegistry.TriggerCreated (filter: rail == SEPA)
• RailTriggerRegistry.TriggerStateUpdated (filter: rail == SEPA)

SEPA Variants

SCT (Standard Credit Transfer)

• Settlement: T+1 (next business day)
• Message: pain.001 (initiation), pacs.008 (interbank)
• Cut-off times apply

SCT Inst (Instant Credit Transfer)

• Settlement: Real-time (within seconds)
• Message: pain.001 with instant indicator
• Higher fees, 24/7 availability

ISO-20022 Message Construction

Outbound (pain.001 for SEPA)

<Document>
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>instructionId</MsgId>
      <CreDtTm>timestamp</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>paymentInfoId</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <BtchBookg>false</BtchBookg>
      <ReqdExctnDt>executionDate</ReqdExctnDt>
      <Dbtr>
        <Nm>debtorName</Nm>
      </Dbtr>
      <DbtrAcct>
        <Id>
          <IBAN>debtorIBAN</IBAN>
        </Id>
      </DbtrAcct>
      <DbtrAgt>
        <FinInstnId>
          <BIC>debtorBIC</BIC>
        </FinInstnId>
      </DbtrAgt>
      <CdtTrfTxInf>
        <PmtId>
          <EndToEndId>endToEndId</EndToEndId>
        </PmtId>
        <Amt>
          <InstdAmt Ccy="EUR">amount</InstdAmt>
        </Amt>
        <CdtrAgt>
          <FinInstnId>
            <BIC>creditorBIC</BIC>
          </FinInstnId>
        </CdtrAgt>
        <Cdtr>
          <Nm>creditorName</Nm>
        </Cdtr>
        <CdtrAcct>
          <Id>
            <IBAN>creditorIBAN</IBAN>
          </Id>
        </CdtrAcct>
        <RmtInf>
          <Ustrd>remittanceInfo</Ustrd>
        </RmtInf>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>

SCT Inst Indicator

For instant transfers, add:

<PmtTpInf>
  <SvcLvl>
    <Cd>SEPA</Cd>
  </SvcLvl>
  <CtgyPurp>
    <Cd>INST</Cd>
  </CtgyPurp>
</PmtTpInf>

On-Chain Attestation Flow

1. Submit to Rail:

   • Call SettlementOrchestrator.markSubmitted(triggerId, railTxRef)
   • railTxRef = SEPA transaction reference

2. Confirm Settlement:

   • SCT: On receipt of camt.054 (next day)
   • SCT Inst: On receipt of camt.054 (within seconds)
   • Call SettlementOrchestrator.confirmSettled(triggerId, railTxRef)

3. Handle Returns:

   • On pacs.004 (Payment Return):
     • Call SettlementOrchestrator.confirmRejected(triggerId, reason)

Account Resolution

• accountRefId → SEPA account details (IBAN, BIC)
• Validate IBAN format before submission
• Support both IBAN and BIC resolution

SEPA Rulebook Compliance

• Amount Limits: SCT Inst max €15,000 per transaction
• Currency: EUR only
• IBAN Validation: Must validate IBAN checksum
• Cut-off Times: Respect SEPA cut-off times for SCT

Error Handling

• Invalid IBAN: Validate and reject before submission
• Amount Limits: Check SCT Inst limits
• Cut-off Time: Queue for next business day if past cut-off

Security Considerations

• SEPA-compliant authentication (e.g., PSD2 Strong Customer Authentication)
• Secure storage of IBANs and credentials
• Implement SEPA security guidelines

Testing

• Unit tests for IBAN validation
• Integration tests with SEPA test environment
• SCT vs SCT Inst flow tests