C# Sample

A comprehensive .NET 10 client library for integrating with the PIPA PayCenter API. This library handles OAuth2 authentication, credential management, and provides a simple interface for making API calls.

Features

Simple API: Developers only need to pass JSON payloads; the client handles authentication and HTTP operations
OAuth2 Authentication: Automatic token management with refresh logic
Cross-Platform: Works on Windows, Linux, and macOS
Flexible Credential Storage: Support for appsettings, environment variables, or vault providers
Extensible Credential Provider: Easy integration with Azure Key Vault, AWS Secrets Manager, or other secret stores
Dependency Injection: Full support for Microsoft.Extensions.DependencyInjection
Comprehensive Coverage: Supports all PIPA PayCenter API workflows

Project Structure

PIPAPayCenter.Client: The main client library containing the API client and credential management
PIPAPayCenter.Sample: Example console application demonstrating usage

Quick Start

1. Installation

Add the PIPAPayCenter.Client project to your solution:

dotnet add reference path/to/PIPAPayCenter.Client/PIPAPayCenter.Client.csproj

2. Configuration

Add the following configuration to your appsettings.json:

{
  "PIPAPayCenter": {
    "BaseUrl": "https://ipa01.eagle.jhapaycenter.com",
    "InstitutionId": "707060783",
    "Environment": "sandbox",
    "Product": "pipa",
    "TimeoutSeconds": 30,
    "Authentication": {
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret"
    }
  }
}

⚠️ Security Note: For production, use environment variables or a vault provider instead of storing credentials in appsettings.json.

3. Choose Your Credential Management Approach

Option A: Environment Variables (Recommended for Production)

Set these environment variables:

Linux/macOS - Add to ~/.bashrc or ~/.zshrc:

export PIPA_CLIENT_ID="your-client-id"
export PIPA_CLIENT_SECRET="your-client-secret"

Windows PowerShell:

[System.Environment]::SetEnvironmentVariable('PIPA_CLIENT_ID', 'your-client-id', 'User')
[System.Environment]::SetEnvironmentVariable('PIPA_CLIENT_SECRET', 'your-client-secret', 'User')

Windows Command Prompt:

setx PIPA_CLIENT_ID "your-client-id"
setx PIPA_CLIENT_SECRET "your-client-secret"

Then register with environment variable provider:

services.AddPIPAPayCenterClient(configuration, sp => new EnvironmentVariableCredentialProvider());

Option B: AppSettings (Development Only)

Store credentials directly in appsettings.json (shown above). This is convenient for development but not recommended for production.

// Uses credentials from appsettings.json
services.AddPIPAPayCenterClient(configuration);

Option C: Vault Provider (Best for Production)

Use Azure Key Vault, AWS Secrets Manager, or similar (see examples below).

4. Register the Client with Dependency Injection

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using PIPAPayCenter.Client;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var services = new ServiceCollection();

// Use default encrypted credentials from appsettings.json
services.AddPIPAPayCenterClient(configuration);

var serviceProvider = services.BuildServiceProvider();
var client = serviceProvider.GetRequiredService<PIPAPayCenterClient>();

5. Make API Calls

// Example: Create a Credit Transfer
var institutionId = "707060783";
var endpoint = $"/v2/paycenter/institutions/{institutionId}/environments/sandbox/products/pipa/credit-transfers";

var headers = new Dictionary<string, string>
{
    { "X-Request-ID", Guid.NewGuid().ToString() }
};

var jsonPayload = @"{
    ""CreditTransfer"": {
        ""Debtor"": {
            ""Name"": ""PC-Tester"",
            ""AccountNumber"": ""556677"",
            ""AccountType"": ""Checking""
        },
        ""Creditor"": {
            ""Name"": ""PC-Test"",
            ""AccountNumber"": ""201990001"",
            ""RoutingNumber"": ""711060274""
        },
        ""CreditTransferDescription"": {
            ""Amount"": 1.01,
            ""OriginatorType"": ""BUSINESS"",
            ""UserName"": ""TestUser"",
            ""Notes"": ""Sample Transfer""
        }
    }
}";

var response = await client.PostAsync(endpoint, jsonPayload, headers);

if (response.IsSuccess)
{
    Console.WriteLine($"Success! Response: {response.Content}");
}
else
{
    Console.WriteLine($"Error: {response.ErrorMessage}");
}

Using a Custom Credential Provider

If you want to use Azure Key Vault, AWS Secrets Manager, or another secret store:

1. Implement ICredentialProvider

using PIPAPayCenter.Client.Configuration;

public class AzureKeyVaultCredentialProvider : ICredentialProvider
{
    private readonly SecretClient _secretClient;

    public AzureKeyVaultCredentialProvider(SecretClient secretClient)
    {
        _secretClient = secretClient;
    }

    public async Task<string> GetClientIdAsync()
    {
        var secret = await _secretClient.GetSecretAsync("pipa-client-id");
        return secret.Value.Value;
    }

    public async Task<string> GetClientSecretAsync()
    {
        var secret = await _secretClient.GetSecretAsync("pipa-client-secret");
        return secret.Value.Value;
    }
}

2. Register with Dependency Injection

services.AddPIPAPayCenterClient(configuration, sp => 
{
    var secretClient = sp.GetRequiredService<SecretClient>();
    return new AzureKeyVaultCredentialProvider(secretClient);
});

API Methods

PostAsync

Send a POST request with JSON payload.

Task<ApiResponse> PostAsync(string endpoint, string jsonPayload, Dictionary<string, string>? customHeaders = null)

GetAsync

Send a GET request with optional query parameters.

Task<ApiResponse> GetAsync(string endpoint, Dictionary<string, string>? queryParameters = null, Dictionary<string, string>? customHeaders = null)

PatchAsync

Send a PATCH request with JSON payload.

Task<ApiResponse> PatchAsync(string endpoint, string jsonPayload, Dictionary<string, string>? customHeaders = null)

Supported Workflows

The client library supports all PIPA PayCenter API workflows:

Token Authentication - Automatic OAuth2 token management
Credit Transfer - Create and send payment transfers
Get Credit Transfer by X-Request-ID - Check transfer status
Get Credit Transfer by TrackID - Retrieve transfer details
Routing Number Eligibility - Verify institution eligibility
Payment Request - Create Request for Payment (RfP)
Payment Request Response - Accept/Reject payment requests
Get Payment Request by X-Request-ID - Check request status
Get Payment Request by TrackID - Retrieve request details
Pay a Payment Request - Execute payment for received RfP

Security Considerations

Development vs Production: Use plain appsettings for dev, environment variables or vaults for production
Cross-Platform: Works on Windows, Linux, and macOS without platform-specific dependencies
Vault Integration: For production, integrate with Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault
Token Management: Access tokens are cached and automatically refreshed
Thread-Safe: Token refresh logic is protected by semaphore locks
No Secrets in Code: Never hardcode credentials; use configuration or environment variables

Building and Running

# Build the solution
dotnet build

# Run the sample application
cd CSharpSample/PIPAPayCenter.Sample
dotnet run

# Run tests (if tests are added)
dotnet test

Requirements

.NET 10.0 SDK
Windows, Linux, or macOS

Error Handling

The ApiResponse object contains:

IsSuccess: Boolean indicating if the request succeeded
StatusCode: HTTP status code
Content: Response body as string
ErrorMessage: Error description if request failed
Headers: Response headers dictionary

var response = await client.PostAsync(endpoint, jsonPayload);

if (!response.IsSuccess)
{
    Console.WriteLine($"Request failed: {response.ErrorMessage}");
    Console.WriteLine($"Status Code: {response.StatusCode}");
    Console.WriteLine($"Response: {response.Content}");
}

📥 Downloads

Download the complete C# client library and sample application:

Download C# Sample (ZIP) - Complete .NET 10 solution with client library and sample console application

What's included:

PIPAPayCenter.Client - Main client library with OAuth2 authentication
PIPAPayCenter.Sample - Example console application
PIPAPayCenter.CredentialEncryptor - Utility for encrypting credentials
Sample payloads and configuration files
Complete project documentation

After downloading:

Extract the ZIP file
Open PIPAPayCenter.slnx in Visual Studio or your preferred IDE
Configure your credentials in appsettings.json or environment variables
Build and run the sample application

Contributing

When contributing, ensure:

Code follows C# naming conventions
All public methods have XML documentation comments
Error handling is comprehensive
Examples are updated with new features

Features​

Project Structure​

Quick Start​

1. Installation​

2. Configuration​

3. Choose Your Credential Management Approach​

Option A: Environment Variables (Recommended for Production)​

Option B: AppSettings (Development Only)​

Option C: Vault Provider (Best for Production)​

4. Register the Client with Dependency Injection​

5. Make API Calls​

Using a Custom Credential Provider​

1. Implement ICredentialProvider​

2. Register with Dependency Injection​

API Methods​

PostAsync​

GetAsync​

PatchAsync​

Supported Workflows​

Security Considerations​

Building and Running​

Requirements​

Error Handling​

📥 Downloads​

Contributing​