.NET client library for the AffiniPay Payment Gateway (aka ChargeIO)
Use our official C# library to access the AffiniPay Payment Gateway API from your .NET project.
This library requires a secret_key to authenticate with the AffiniPay Payment Gateway API. Don't inadvertently expose your secret_key in public web pages or source control repositories. Refer to the Configuration section for more information.
This library requires the .NET Core SDK. Make sure it's installed before proceeding.
Install the library from NuGet:
PM> Install-Package chargeio-net -Version 1.1.0
Access to the AffiniPay Payment Gateway requires a test or live-mode secret_key for authentication and authorization. You can supply your secret_key to this library by using either of these two methods:
- Pass your secret_key directly to the service constructors in your code. Here's an example of creating a payment method service object by supplying a secret_key:
PaymentMethodService pm = new PaymentMethodService("your-secret-key");
- Create an appsettings.json file that contains your secret_key and place it in the same directory as your project .dll. This can be accomplished in Visual Studio by adding your appsettings.json file to your project and setting the Copy to output directory property of the file to Always copy. This method would work if only a single client secret is needed in your application.
Here's an example of an appsettings.json file:
{
"ChargeIOSecretKey": "z6keqpRzRAiNNjvlJ3sL5wU46t1VGewnBu7Xzsed03W5b359KhDyapZWGnTiAFXM",
"ChargeIOApiUrl": "https://api.chargeio.com/v1",
"ChargeIOHTTPTimeout": "20000"
}
You must tokenize all sensitive payment information before you submit it to AffiniPay. On your payment form, use AffiniPay’s hosted fields to secure payment data and call window.AffiniPay.HostedFields.getPaymentToken to create a one-time payment token. See "Creating payment forms using hosted fields". POST the token ID received to your C# application, and then perform the charge:
try {
// Invoke the TransactionService to run a charge.
TransactionService ts = new TransactionService();
// Run a charge using the one-time token.
Charge charge = ts.Charge(new ChargeOptions(){
AmountInCents = 1000,
Method = new TokenReferenceOptions() {
TokenId = token.Id
}
});
await context.Response.WriteAsync(JObject.FromObject(charge).ToString());
}
// Handle exceptions and print details to the screen.
catch(ChargeIoException e) {
await context.Response.WriteAsync(e.Message);
}
The latest AffiniPay Payment Gateway API documentation is available at https://developers.affinipay.com/reference/api.html#PaymentGatewayAPI.
To successfully run tests, you must have an AffiniPay merchant account that matches the following configuration:
- At least one test-mode eCheck account (for eCheck payments)
- At least one test-mode credit account (for credit card payments)
- No daily/monthly transaction limit set on your test-mode accounts
- CVV policy set to "Optional"
- AVS policy set to "Address or Postal Code Match - Lenient"
- No additional Required Payment Fields checked other than those set by default after selecting a CVV/AVS policy
Contact support if you need an AffiniPay merchant account or to remove transaction limits from your test account(s).
This library contains the following services:
MerchantServicePaymentMethodServiceRecurringChargeServiceTransactionService
Use this service to manage merchant account information, such as retrieving and updating merchant and ach_account information.
This service includes the following methods:
GetMerchantUpdateMerchantUpdateACHAccount
Refer to Merchant Management for more information.
You can exchange a payment token for a saved card/bank, which is designed to support "remembered" payments for customers with no limits on future use. You can use these saved payment methods with any endpoint that accepts card or bank details in lieu of the card or bank JSON entity.
This service includes the following methods:
CreateCardDeleteCardListCardsCreateBankDeleteBankListBanksGetToken
Refer to Payment Methods for more information.
The AffiniPay Payment Gateway's recurring charge support makes it easy to collect payments from customers on an ongoing, scheduled basis--from simple donations to more complicated installment plans.
This service includes the following methods:
RecurringChargeRecurringChargesGetRecurringChargeUpdateRecurringChargeCancelRecurringChargeDeleteRecurringChargeGetOccurrencePayOccurrenceIgnoreOccurrenceOccurrences
Refer to Recurring Charges for more information.
Simplifies the process of submitting payments and applying refunds to those payments. The gateway automatically performs funds capture daily and initiates settlement. Refunds can be performed at any time after a charge, in any number, up to the amount of the charge.
The API also includes methods for retrieving individual transactions by ID or source ID, as well as a search operation that returns paginated results based on criteria specified by the caller.
This service includes the following methods:
ChargeAuthorizeVoidCaptureRefundCreditGetTransactionTransactionsHoldsSignGetSignature
Refer to Transactions for more information.
To handle and view errors emitted from the library catch on "ChargeIoException". ChargeIoException contains three parameters: an HTTP status code, a List of type "ChargeIoError", and a messages string. ChargeIoErrors will give you the bulk of debug information. A "ChargeIoError" contains five parameters: a message, code, level, context, and sub_code.
// Handle exceptions and print details to the screen. catch(ChargeIoException e) { await context.Response.WriteAsync(e.Message); }
Contributions in the form of GitHub pull requests are welcome. Please adhere to the following guidelines:
- Before embarking on a significant change, please create an issue to discuss the proposed change and ensure that it is likely to be merged.
- Follow the coding conventions used throughout the project, including 2-space indentation.
- All contributions must be licensed under the MIT license.
ISC © AffiniPay LLC