COGWare.CyberSourceRefunds 1.0.0

CyberSource Credit Card Refunds

Process refunds for transactions submitted via the CyberSource payment platform

Getting Started

Install the standard Nuget package into your .NET Core application.

Package Manager:
Install-Package COGWare.CyberSourceRefunds -Version <version>

CLI:
dotnet add package --version <version> COGWare.CyberSourceRefunds

Add Config

Add the CyberSourceRefunds.IsProduction key to your settings file, eg:
<add key="CyberSourceRefunds.IsProduction" value="false" />

Usage

With logging:

    // Create your logger from the logging framework's extensions package (in this case, NLog)
    var logger = LoggerFactory.Create(builder => builder.AddNLog()).CreateLogger<Program>();

    logger.LogInformation("starting");

    try {
        RefundResult? refundResult = await CyberSourceRefunds.RefundHelper.ProcessRefund(
            // An instance of the RefundConfig object containing details of the
            // CyberSource entity that the original transaction was processed against.
            // These details are available in the CyberSource Merchant Console. 
            new RefundConfig() {                        
                // The merchant identifier.
                MID = "your_mid_here",
                // Your merchant API key.
                MerchantKey = "you_merchant_key_here",
                // Your merchant API secret.
                MerchantSecret = "your_merchant_secret_here"
            },
            // An instance of a Refund object representing the refund to be processed.
            new Refund() {
                // The amount to be refunded.
                Amount = 1,
                // Your refund identifier (must be unique).
                Id = "your_unique_identifier_here",
                // This will appear as the reference for the refund
                Comments = "your_comment_here",
                // The original (CyberSource) RequestId of the authorization
                RequestId = "CyberSource_requestId_here"
            },
            logger);

        // Checks the status of the refund against the API response codes to 
        // determine if the refund can be considered successful.
        if(refundResult!.IsSuccessful) {
            // Update the status of the refund in your refund system.
            Console.WriteLine("Refund processed successfully! " +
                "Your refund identifier: '" + refundResult.Id + "', " +
                "CyberSource refund reference: '" + refundResult.RefundId + "'");
        } else {
            // Update the status of the refund in your refund system, optionally including the
            // errors for analysis and manual resolution (if necessary).
            Console.WriteLine("Refund ('" + refundResult.Id + "') failed: " +
                refundResult?.Reason + " - " + 
                refundResult?.Message);
        }
    } catch(Exception ex) {
        Console.WriteLine("ERROR: " + ex.GetBaseException().Message);
    }

    logger.LogInformation("complete");

Without logging:

    try {
        RefundResult? refundResult = await CyberSourceRefunds.RefundHelper.ProcessRefund(
            // An instance of the RefundConfig object containing details of the
            // CyberSource entity that the original transaction was processed against.
            // These details are available in the CyberSource Merchant Console. 
            new RefundConfig() {                        
                // The merchant identifier.
                MID = "your_mid_here",
                // Your merchant API key.
                MerchantKey = "you_merchant_key_here",
                // Your merchant API secret.
                MerchantSecret = "your_merchant_secret_here"
            },
            // An instance of a Refund object representing the refund to be processed.
            new Refund() {
                // The amount to be refunded.
                Amount = 1,
                // Your refund identifier (must be unique).
                Id = "your_unique_identifier_here",
                // This will appear as the reference for the refund
                Comments = "your_comment_here",
                // The original (CyberSource) RequestId of the authorization
                RequestId = "CyberSource_requestId_here"
            });

        // Checks the status of the refund against the API response codes to 
        // determine if the refund can be considered successful.
        if(refundResult!.IsSuccessful) {
            // Update the status of the refund in your refund system.
            Console.WriteLine("Refund processed successfully! " +
                "Your refund identifier: '" + refundResult.Id + "', " +
                "CyberSource refund reference: '" + refundResult.RefundId + "'");
        } else {
            // Update the status of the refund in your refund system, optionally including the
            // errors for analysis and manual resolution (if necessary).
            Console.WriteLine("Refund ('" + refundResult.Id + "') failed: " +
                refundResult?.Reason + " - " + 
                refundResult?.Message);
        }
    } catch(Exception ex) {
        Console.WriteLine("ERROR: " + ex.GetBaseException().Message);
    }

Response object:

RefundResult

An object representing the response from the CyberSource API.

• Id:(String) - Your refund identifier.
• RefundId: (String) - The CyberSource transaction identifier for this specific refund.
• ClientReferenceInformation (Object) - Information you can use to reference this refund request.
  • Code (String) - A code associated with this refund request.
  • TransactionId (String) - Your unique refund transaction identifier.
  • Comments (String) - The comment submitted along with this refund request.
• ErrorInformation (Object) - May be populated with error details - depending on severity of error.
  • Reason (String) - Reason for the error.
  • Message (String) - Detail of the error.
• ProcessorInformation (Object) - Upstream processing information.
  • ApprovalCode (String) - ?
  • NetworkTransactionId (String) - ?
  • RetrievalReferenceNumber (String) - ?
  • ResponseCode (String) - Not sure, but it seems '00' is good.
• ReconciliationId: (String) - This seems to match the original RequestId.
• Status: (String) - Usually "PENDING" since the refund is not immediately processed.
• Reason: (String) - Usually provides the reason for the refund being rejected.
• Message: (String) - A longer description for the associated reason.
• Details: (List) - If there are specific fields that are invalid, this collection can contain details of those offending items.
  • Field (String) - The invalid/offencding field.
  • Reason (String) - The reason why CyberSource has taken offence to this field/value.
• IsSuccessful (Boolean) - A flag indicating if the refund was successfully processed.

Logging:

Implements Microsoft.Extensions.Logging, so log away with any compatible logging framework,eg: NLog This package logs at DEBUG level.

Additional documentation

The CyberSource documentation can be a bit overwhelming to wade through. Warning: here be dragons!

• Create a CyberSource sandbox account
• Create a CyberSource REST API key
• CyberSource response error codes
• CyberSource refunds
• CyberSource refund API documentation

Feedback

I welcome comments, suggestions, feature requests and even honest criticism 😃
Heck, just let me know if you found this useful at all.

• Github Repo
• Email: lance@cogware.co.za

Want to show your appreciation?

That's mighty generous - thank you!
Buy me a coffee