How to integrate with CSM DD Services

This page explains how to integrate a client application with CSM DD services. It provides interfaces (CSMDDClientAdapter, CSMDDClientValidationResponseAdapter, and CSMDDAdapter) that clients must implement to handle various message types and API flows related to payment processing, settlement, and scheme rule validation within the CSM system.

CSMDDClientAdapter

The CSM Adapter is expecting clients to provide an implementation for CSMDDClientAdapter:

public interface CSMDDClientAdapter {
    default CompletionStage<Void> handleCollectAndSettleResponse(ReceivingContext receivingContext, CollectAndSettleResponse collectAndSettleResponse) {
        throw new IconRuntimeException("Please implement the CSMDDClientAdapter's handleCollectAndSettleResponse");
    }

    default CompletionStage<Void> handleCancellationResponse(ReceivingContext receivingContext, ExecuteDDCancellationResponse cancellationResponse) {
        throw new IconRuntimeException("Please implement the CSMDDClientAdapter's handleCancellationResponse");
    }

    default CompletionStage<Void> handleTechnicalResponse(ReceivingContext receivingContext, TechnicalResponse technicalResponse) {
        throw new IconRuntimeException("Please implement the CSMDDClientAdapter's handleTechnicalResponse");
    }
    default CompletionStage<Void> handleReversalResponse(ReceivingContext receivingContext, ExecuteDDReversalResponse executeDDReversalResponse) {
        throw new IconRuntimeException("Please implement the CSMDDClientAdapter's handleReversalResponse");
    }
}

By overriding the methods, the client is able to process distinct messages from the CSM Service, for further processing.

Method API Flows

handleCollectAndSettleResponse

Direct Debit API

Creditor DD

handleCancellationResponse

Direct Debit API

Creditor DD

handleTechnicalResponse

Direct Debit API

Creditor DD

handleReversalResponse

Direct Debit API

Creditor DD

CSMDDClientValidationResponseAdapter

The CSM Adapter is expecting clients to provide an implementation for CSMDDClientValidationResponseAdapter:

public interface CSMDDClientValidationResponseAdapter {
    default CompletionStage<Void> handleSchemeRulesResponse(ReceivingContext receivingContext, ValidateDirectDebitSchemeRulesResponse response) {
        ValidatedIsoType validatedIsoType = ValidatedIsoTypeExtractor.extract(response);
        return switch (validatedIsoType) {
            case PACS_003 -> handlePacs003ValidateDirectDebitSchemeRulesResponse(receivingContext, response);
            case PACS_007 -> handlePacs007ValidateDirectDebitSchemeRulesResponse(receivingContext, response);
            case CAMT_056 -> handleCamt056ValidateDirectDebitSchemeRulesResponse(receivingContext, response);
            case PACS_008, PACS_004, PACS_002, PACS_028, CAMT_029, UNKNOWN -> handleUnexpectedDirectDebitSchemeRulesResponse(receivingContext, response);
        };
    }

    default CompletionStage<Void> handleUnexpectedDirectDebitSchemeRulesResponse(ReceivingContext receivingContext, ValidateDirectDebitSchemeRulesResponse validateDirectDebitSchemeRulesResponse) {
        return CompletableFuture.failedStage(new IconRuntimeException("Please implement the CSMDDClientValidationResponseAdapter's handleUnexpectedDirectDebitSchemeRulesResponse"));
    }

    default CompletionStage<Void> handlePacs003ValidateDirectDebitSchemeRulesResponse(ReceivingContext receivingContext, ValidateDirectDebitSchemeRulesResponse validateDirectDebitSchemeRulesResponse) {
        return CompletableFuture.failedStage(new IconRuntimeException("Please implement the CSMDDClientValidationResponseAdapter's handlePacs003ValidationResponse"));
    }

    default CompletionStage<Void> handlePacs007ValidateDirectDebitSchemeRulesResponse(ReceivingContext receivingContext, ValidateDirectDebitSchemeRulesResponse validateDirectDebitSchemeRulesResponse) {
        return CompletableFuture.failedStage(new IconRuntimeException("Please implement the CSMDDClientValidationResponseAdapter's handlePacs007ValidationResponse"));
    }

    default CompletionStage<Void> handleCamt056ValidateDirectDebitSchemeRulesResponse(ReceivingContext receivingContext, ValidateDirectDebitSchemeRulesResponse validateDirectDebitSchemeRulesResponse) {
        return CompletableFuture.failedStage(new IconRuntimeException("Please implement the CSMDDClientValidationResponseAdapter's handleCamt056ValidationResponse"));
    }
}

By overriding the methods, the client is able to process distinct ValidateDirectDebitSchemeRuleResponse messages from the CSM Service. Clients can choose to implement the ISO type-specific handler methods or override default handleSchemeRulesResponse() method.

CSM Client Starter Project

The following maven dependency is a starter project and includes boilerplate code which will accelerate the integration of a client application with a CSM service. This is the preferred method and makes things easier. However, it is not technically required to be used.

<dependency>
    <groupId>com.iconsolutions.ipf.payments.csm</groupId>
    <artifactId>csm-client-starter-all</artifactId>
</dependency>

CSMDDAdapter

When the csm-client-starter-all dependency is added, an implementation of CSMDDAdapter is also available:

public interface CSMDDAdapter {
    CompletionStage<DeliveryReport> collectAndSettle(CollectAndSettleRequest collectAndSettleRequest);

    CompletionStage<DeliveryReport> cancellation(ExecuteDDCancellationRequest cancellationRequest);

    CompletionStage<DeliveryReport> executeReversalRequest(ExecuteDDReversalRequest executeDDReversalRequest);
}

This interface can be injected on the client side and by invoking these methods, distinct messages can be sent to the CSM Service, for further processing.

Method API Flows

collectAndSettle

Direct Debit API

Creditor DD

cancellation

Direct Debit API

Creditor DD

executeReversalRequest

Direct Debit API

Creditor DD