Rmp.Payments.RtrSdk 1.0.8

RtrSdk

A .NET SDK for integrating with the RTR (Real-Time Rail) Payment API, FIF (Financial Institution File) API, and CCIN (Canadian Company Identification Number) API in Canada. This SDK provides simple, easy-to-use clients for sending payments, status enquiries, retrieving reports, and looking up branch and company information.

Features

RTR Payment API

• ✅ Send Payments - Send real-time payments through the RTR network
• ✅ Status Enquiries - Check payment status using UETR or other identifiers
• ✅ Interest Reports - Retrieve interest rate information
• ✅ Balance Reports - Get payment capacity balance information

FIF (Financial Institution File) API

• ✅ Branch Lookup - Get branch details by DPRN (Direct Payment Routing Number)
• ✅ Master Extract - Retrieve complete branch master data
• ✅ Updated Extract - Get branch updates for a date range

CCIN (Canadian Company Identification Number) API

• ✅ CCIN Lookup - Get company details by CCIN
• ✅ Master Extract - Retrieve complete CCIN master data
• ✅ Updated Extract - Get CCIN updates for a date range

Common Features

• ✅ Automatic Token Management - OAuth tokens are automatically cached and refreshed
• ✅ Comprehensive Logging - Built-in support for Microsoft.Extensions.Logging
• ✅ Async/Await Support - Fully asynchronous API with cancellation token support
• ✅ Type-Safe Models - Strongly-typed request and response models
• ✅ Dependency Injection - Easy registration with extension methods
• ✅ Thread-Safe - Safe for concurrent use and singleton registration
• ✅ Separate Credentials - Each API client can use different consumer keys/secrets

Installation

NuGet Package Manager

Install-Package Rmp.Payments.RtrSdk

.NET CLI

dotnet add package Rmp.Payments.RtrSdk

Dependency Injection

The SDK provides extension methods for easy registration in dependency injection containers.

Option 1: Direct Configuration

using Rmp.Payments.RtrSdk;
using Microsoft.Extensions.DependencyInjection;

services.AddRtrPaymentClient(options =>
{
    options.BaseUrl = "https://api.payments.ca/rtr-sandbox";
    options.TokenUrl = "https://api.payments.ca/accesstoken";
    options.ConsumerKey = "your-consumer-key";
    options.ConsumerSecret = "your-consumer-secret";
});

Option 2: Configuration Binding

Register from appsettings.json:

{
  "RtrApi": {
    "BaseUrl": "https://api.payments.ca/rtr-sandbox",
    "TokenUrl": "https://api.payments.ca/accesstoken",
    "ConsumerKey": "your-rtr-consumer-key",
    "ConsumerSecret": "your-rtr-consumer-secret"
  },
  "FifBranchApi": {
    "BaseUrl": "https://api.payments.ca/fif-branch-sandbox",
    "TokenUrl": "https://api.payments.ca/accesstoken",
    "ConsumerKey": "your-fif-branch-consumer-key",
    "ConsumerSecret": "your-fif-branch-consumer-secret"
  },
  "FifExtractsApi": {
    "BaseUrl": "https://api.payments.ca/fif-extracts-sandbox",
    "TokenUrl": "https://api.payments.ca/accesstoken",
    "ConsumerKey": "your-fif-extracts-consumer-key",
    "ConsumerSecret": "your-fif-extracts-consumer-secret"
  },
  "CcinLookupApi": {
    "BaseUrl": "https://api.payments.ca/ccin-lookup-sandbox",
    "TokenUrl": "https://api.payments.ca/accesstoken",
    "ConsumerKey": "your-ccin-lookup-consumer-key",
    "ConsumerSecret": "your-ccin-lookup-consumer-secret"
  },
  "CcinExtractsApi": {
    "BaseUrl": "https://api.payments.ca/ccin-extracts-sandbox",
    "TokenUrl": "https://api.payments.ca/accesstoken",
    "ConsumerKey": "your-ccin-extracts-consumer-key",
    "ConsumerSecret": "your-ccin-extracts-consumer-secret"
  }
}

using Rmp.Payments.RtrSdk;
using Microsoft.Extensions.DependencyInjection;

// Register all clients
services.AddRtrPaymentClient();
services.AddFifBranchClient();
services.AddFifExtractsClient();
services.AddCcinLookupClient();
services.AddCcinExtractsClient();

// Or specify custom section names
services.AddRtrPaymentClient("CustomRtrApi");
services.AddFifBranchClient("CustomFifBranchApi");

Using the Client

Once registered, inject IRtrPaymentClient (or RtrPaymentClient) into your services:

public class PaymentService
{
    private readonly IRtrPaymentClient _client;

    public PaymentService(IRtrPaymentClient client)
    {
        _client = client;
    }

    public async Task ProcessPaymentAsync(SendPaymentRequest request)
    {
        var response = await _client.SendPaymentAsync(request);
        // Handle response...
    }
}

Note:

• All clients are registered as singletons and are thread-safe, making them safe to use across multiple threads and throughout your application lifetime.
• It's recommended to inject the interface (e.g., IRtrPaymentClient, IFifBranchClient) for better testability and mocking support.
• Each client requires its own consumer key and secret, as they authenticate independently.

API Reference

IRtrPaymentClient / RtrPaymentClient

The main client interface and implementation for interacting with the RTR Payment API. The IRtrPaymentClient interface is recommended for dependency injection to enable better testability and mocking.

Methods

SendPaymentAsync

Sends a payment through the RTR network.

Task<PaymentResponse?> SendPaymentAsync(
    SendPaymentRequest paymentRequest,
    CancellationToken cancellationToken = default)

Parameters:

• paymentRequest - The payment request containing all payment details
• cancellationToken - Optional cancellation token

Returns: PaymentResponse containing the payment status and details

SendStatusEnquiryAsync

Sends a status enquiry for an existing payment.

Task<PaymentResponse?> SendStatusEnquiryAsync(
    SendStatusEnquiryRequest statusRequest,
    CancellationToken cancellationToken = default)

Parameters:

• statusRequest - The status enquiry request (can use UETR or other identifiers)
• cancellationToken - Optional cancellation token

Returns: PaymentResponse containing the current payment status

GetInterestReportAsync

Retrieves an interest report.

Task<ReportResponse?> GetInterestReportAsync(
    InterestReportRequest interestRequest,
    CancellationToken cancellationToken = default)

Parameters:

• interestRequest - The interest report request
• cancellationToken - Optional cancellation token

Returns: ReportResponse containing interest rate information

GetBalanceReportAsync

Retrieves a payment capacity balance report.

Task<ReportResponse?> GetBalanceReportAsync(
    BalanceReportRequest balanceRequest,
    CancellationToken cancellationToken = default)

Parameters:

• balanceRequest - The balance report request
• cancellationToken - Optional cancellation token

Returns: ReportResponse containing balance information

RtrPaymentClientOptions

Configuration options for the RTR Payment client.

Properties

• BaseUrl (required) - Base URL for the RTR API (e.g., "https://api.payments.ca/rtr-sandbox")
• TokenUrl (required) - URL for OAuth token endpoint (e.g., "https://api.payments.ca/accesstoken")
• ConsumerKey (required) - OAuth consumer key
• ConsumerSecret (required) - OAuth consumer secret
• LoggerFactory (optional) - ILoggerFactory instance for logging. If not provided, no logging will occur.
• HttpClient (optional) - Custom HttpClient instance. If not provided, a new HttpClient will be created and disposed with the client.

FIF (Financial Institution File) API

IFifBranchClient / FifBranchClient

Client for FIF Branch API operations.

Methods

GetBranchAsync

Gets branch details by DPRN (Direct Payment Routing Number).

Task<FifBranchRecord?> GetBranchAsync(
    string dprn,
    DateTime? asAtDate = null,
    CancellationToken cancellationToken = default)

Parameters:

• dprn - The Direct Payment Routing Number (9 digits, required)
• asAtDate - Optional date to retrieve the branch record as at this date (yyyy-MM-dd). If not provided, latest completed cycle is used.
• cancellationToken - Optional cancellation token

Returns: FifBranchRecord containing branch details

Registration:

services.AddFifBranchClient(options =>
{
    options.BaseUrl = "https://api.payments.ca/fif-branch-sandbox";
    options.TokenUrl = "https://api.payments.ca/accesstoken";
    options.ConsumerKey = "your-fif-branch-consumer-key";
    options.ConsumerSecret = "your-fif-branch-consumer-secret";
});

IFifExtractsClient / FifExtractsClient

Client for FIF Extracts API operations.

Methods

GetMasterExtractAsync

Gets the master extract. Defaults to last completed cycle unless specific date is provided.

Task<List<FifMasterRecord>> GetMasterExtractAsync(
    DateTime? asAtDate = null,
    int? limit = null,
    CancellationToken cancellationToken = default)

Parameters:

• asAtDate - Optional date to retrieve the extract record(s) in effective as at this date (yyyy-MM-dd)
• limit - Optional limit on number of records to retrieve
• cancellationToken - Optional cancellation token

Returns: List of FifMasterRecord containing branch master data

GetUpdatedExtractAsync

Gets the updated branches from the extracts for a given date range.

Task<List<FifUpdatedRecord>> GetUpdatedExtractAsync(
    DateTime? startDate = null,
    DateTime? endDate = null,
    CancellationToken cancellationToken = default)

Parameters:

• startDate - Start of effective date range (yyyy-MM-dd). If not provided, latest completed cycle is used.
• endDate - End of effective date range (yyyy-MM-dd). If not provided, latest completed cycle is used.
• cancellationToken - Optional cancellation token

Returns: List of FifUpdatedRecord containing branch updates with change tracking

Registration:

services.AddFifExtractsClient(options =>
{
    options.BaseUrl = "https://api.payments.ca/fif-extracts-sandbox";
    options.TokenUrl = "https://api.payments.ca/accesstoken";
    options.ConsumerKey = "your-fif-extracts-consumer-key";
    options.ConsumerSecret = "your-fif-extracts-consumer-secret";
});

CCIN (Canadian Company Identification Number) API

ICcinLookupClient / CcinLookupClient

Client for CCIN Lookup API operations.

Methods

GetCcinAsync

Returns a single extract record by CCIN.

Task<CcinRecord?> GetCcinAsync(
    string ccin,
    DateTime? asAtDate = null,
    CancellationToken cancellationToken = default)

Parameters:

• ccin - The CCIN (Canadian Company Identification Number, required)
• asAtDate - Optional date to retrieve the most recent extract prior to the date sent in (yyyy-MM-dd)
• cancellationToken - Optional cancellation token

Returns: CcinRecord containing company details

Registration:

services.AddCcinLookupClient(options =>
{
    options.BaseUrl = "https://api.payments.ca/ccin-lookup-sandbox";
    options.TokenUrl = "https://api.payments.ca/accesstoken";
    options.ConsumerKey = "your-ccin-lookup-consumer-key";
    options.ConsumerSecret = "your-ccin-lookup-consumer-secret";
});

ICcinExtractsClient / CcinExtractsClient

Client for CCIN Extracts API operations.

Methods

GetMasterExtractAsync

Retrieves the master extract.

Task<List<CcinMasterRecord>> GetMasterExtractAsync(
    CcinExtractOptions? options = null,
    CancellationToken cancellationToken = default)

Parameters:

• options - Optional extract query options:
  • AsAtDate - Date to retrieve the most recent extract prior to this date
  • Limit - How many records to retrieve
  • Page - Start page to get the data for the dataset
  • SortField - The field to sort on
  • SortOrder - The direction to sort on (true for ascending)
  • Filter - Filter criteria
  • AllRecords - Whether to retrieve all records
• cancellationToken - Optional cancellation token

Returns: List of CcinMasterRecord containing CCIN master data

GetUpdatedExtractAsync

Gets the Update Extract for the most recent cycle or a date range.

Task<List<CcinUpdatedRecord>> GetUpdatedExtractAsync(
    CcinExtractOptions? options = null,
    CancellationToken cancellationToken = default)

Parameters:

• options - Optional extract query options:
  • StartDate - Start date to retrieve data for (yyyy-MM-dd)
  • EndDate - End date to retrieve data for (yyyy-MM-dd)
  • Limit - How many records to retrieve
  • Page - Start page to get the data for the dataset
  • SortField - The field to sort on
  • SortOrder - The direction to sort on (true for ascending)
  • AllRecords - Whether to retrieve all records
• cancellationToken - Optional cancellation token

Returns: List of CcinUpdatedRecord containing CCIN updates with change tracking

Registration:

services.AddCcinExtractsClient(options =>
{
    options.BaseUrl = "https://api.payments.ca/ccin-extracts-sandbox";
    options.TokenUrl = "https://api.payments.ca/accesstoken";
    options.ConsumerKey = "your-ccin-extracts-consumer-key";
    options.ConsumerSecret = "your-ccin-extracts-consumer-secret";
});

Error Handling

The SDK throws standard .NET exceptions:

• ArgumentNullException - When required parameters are null
• ArgumentException - When required options are missing or invalid
• HttpRequestException - When API requests fail
• InvalidOperationException - When token retrieval fails

Always wrap API calls in try-catch blocks to handle errors appropriately.

Token Management

The SDK automatically manages OAuth tokens:

• Tokens are automatically retrieved when needed
• Tokens are cached and reused until they expire
• Tokens are automatically refreshed when expired (with a 1-minute buffer)
• No manual token management is required

Thread Safety

All clients (RtrPaymentClient, FifBranchClient, FifExtractsClient, CcinLookupClient, CcinExtractsClient) are thread-safe and can be safely shared across multiple threads. Each client uses thread-safe token caching to prevent race conditions when refreshing OAuth tokens.

You can safely:

• Register clients as singletons in dependency injection containers
• Share a single instance across multiple threads
• Use the clients concurrently from different tasks/threads
• Each client maintains its own independent token cache

Disposal

The client implements IDisposable and should be disposed when no longer needed. Use using statements for automatic disposal, or call Dispose() manually.

Requirements

• .NET 8.0 or later
• Valid API credentials (ConsumerKey and ConsumerSecret) for each API you want to use:
  • RTR Payment API credentials for RtrPaymentClient
  • FIF Branch API credentials for FifBranchClient
  • FIF Extracts API credentials for FifExtractsClient
  • CCIN Lookup API credentials for CcinLookupClient
  • CCIN Extracts API credentials for CcinExtractsClient

Note: Each API requires separate credentials. You can register only the clients you need.