Paystack.Net 1.1.0

dotnet add package Paystack.Net --version 1.1.0
NuGet\Install-Package Paystack.Net -Version 1.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Paystack.Net" Version="1.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Paystack.Net --version 1.1.0
#r "nuget: Paystack.Net, 1.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Paystack.Net as a Cake Addin
#addin nuget:?package=Paystack.Net&version=1.1.0

// Install Paystack.Net as a Cake Tool
#tool nuget:?package=Paystack.Net&version=1.1.0

PayStack API for .Net

This library makes it easy to consume the Payment API from .Net projects.

What's new in 1.0.x !

100% API coverage, simply!

With this update, all Paystack APIs are now available via the Type-less API, exposed directly on PayStackApi. This makes it possible to call new or existing endpoints previously not suppported via this library's Typed API.

See Usage > Type-less API below for details.

How to Install

From Nuget

Install-Package PayStack.Net

Usage

The most important type in this library is the PayStackApi class. This can be created as follows:

var testOrLiveSecret = ConfigurationManager.AppSettings["PayStackSecret"];
var api = new PayStackApi(testOrLiveSecret);

To enhance discovery, all types are exposed under the PayStack.Net namespace. So, remember to include:

...
using PayStack.Net;
...

As implemented from version 1.0.0 and later, this library exposes Paystack APIs in two major ways:

  1. Typed: Intellisense and support for most commonly used APIs; and
  2. Type-less: No intellisense (by default), but with 100% API coverage.

Typed API


Please see usage examples (and instructions) below:

Transactions API

To consume the Transactions API, use methods from the ITransactionsApi interface (available via the Transactions property of PayStackApi, viz:


// Initializing a transaction
var response = api.Transactions.Initialize("user@somewhere.net", 5000000);
if (response.Status)
  // use response.Data
else
  // show response.Message
  
// Verifying a transaction
var verifyResponse = api.Transactions.Verify("transaction-reference"); // auto or supplied when initializing;
if (verifyResponse.Status)
  /* 
      You can save the details from the json object returned above so that the authorization code 
      can be used for charging subsequent transactions
      
      // var authCode = verifyResponse.Data.Authorization.AuthorizationCode
      // Save 'authCode' for future charges!
  */

The ITransactionsApi is defined as follows:

public interface ITransactionsApi
{
    TransactionInitializeResponse Initialize(string email, int amount);
    TransactionInitializeResponse Initialize(TransactionInitializeRequest request);
    TransactionVerifyResponse Verify(string reference);
    TransactionListResponse List(TransactionListRequest request = null);
    TransactionFetchResponse Fetch(string transactionId);
    TransactionTimelineResponse Timeline(string transactionIdOrReference);
    TransactionTotalsResponse Totals(DateTime? from = null, DateTime? to = null);

    TransactionExportResponse Export(DateTime? from = null, DateTime? to = null,
        bool settled = false, string paymentPage = null);
}

Other APIs


Other APIs are implemented in like manner and exposed via the PayStackApi type as given below:

// Customer APIs

var request = new CustomerCreateRequest { ... };
var response = api.Customers.Create(request);

var listRequest = new CustomerListRequest { ... };
var listResponse = api.Customers.List(listRequest);  // api.Customers is of type ICustomersApi 

// Sub Accounts APIs

var saRequest = new SubAccountCreateRequest { ... };
var response = api.SubAccounts.Create(saRequest); // api.SubAccounts is of type ISubAccountsApi
// response.Status, response.Message, response.Data are available

// etc

The only exception to this is the API for resolving a card's identity given its Bank Identification Number (BIN), ResolveCardBin("..."), which is defined directly on the PayStackApi class, as follows:

ResolveCardBinResponse response = api.ResolveCardBin("123456");
// Use response as necessary

Type-less API (available since v1.0.0)


The Get, Post, and Put methods on PayStackApi allow for Type-less access to the entire PayStack API (100% coverage! Albeit without intellisense, by default).

For example, the InitializePayment endpoint can be called via the Type-less API, viz:

var _api = new PayStackApi(...);

var result = _api
  .Post<ApiResponse<dynamic>, dynamic>(
    "/transaction/initialize", 
    new {
      amount = 5000000, // N50,000.00,
      email = "someone@somewhere.net",
      currency = "NGN",
      reference = "",
    }
  );

if (result.Status) { 
  // use result.Data.authorization_url
  // Note: result.Data properties appear as presented in API docs.
} 
else { 
  // display result.Message 
}

Intellisense can be enabled for the Type-less API by creating a custom Response class that matches the .data schema of the API being called.

For example, the following snippet will enable intellisense for the InitializePayment Type-less API:

// defined a .data schema compatible class
public class DtoInitializePayment {
    public string authorization_url { get; set; }
    public string reference { get; set; }
    public string access_code { get; set; }
}

or with .Net naming convention

// define a result.data schema compatible class
public class DtoInitializePayment {
    [JsonProperty("authorization_url")]
    public string AuthorizationUrl { get; set; }

    public string Reference { get; set; }

    [JsonProperty("access_code")]
    public string AccessCode { get; set; }
}

The DTO class can then be used when calling Type-less API, viz:

var _api = new PayStackApi(...);

var result = _api
  .Post<ApiResponse<DtoInitializePayment>, dynamic>(
    "/transaction/initialize", 
    new {
      amount = 5000000, // N50,000.00,
      email = "someone@somewhere.net",
      currency = "NGN",
      reference = "",
    }
  );

if (result.Status) { 
  // Use result as follows (with properties available via intellisense!):
  // result.Data.authorization_url; or
  // result.Data.AuthorizationUrl 
  // ...depending on the Dto class used.

} 
else { 
  // display result.Message 
}

Working with Metadata

Some PayStack API allow sending additional information about your request via an optional metadata property. PayStack.Net Request Types that support this feature (e.g. TransactionInitializeRequest, SubAccountCreateRequest, ChargeAuthorizationRequest, among others) inherit from the RequestMetadataExtender class. RequestMetadataExtender class has two properties, CustomFields (a List of CustomField) and MetadataObject (a string-keyed dictionary of object), and can be used thus:

// Prepare request object and set necessary payload on request
var request = new TransactionInitializeRequest { ... };

// Add a custom-field to metadata
request.CustomFields.Add(
  CustomField.From("Field Name", "field_variable_name", "Field Value")
);

//  Send request
var response = api.Transactions.Initialize(request);

// Use response as needed
...

Arbitary non custom-field metadata can be set, viz:

// Prepare request object and set necessary payload on request
var request = new SubAccountCreateRequest { ... };

// Add arbitary information to metadata
request.MetadataObject["Technical-Tip"] = "Microservices are awesome with Docker & Kubernetes!";
request.MetadataObject["ProductionUrl"] = "http://amazon.co.uk/product-url-slugified";

// Send request
var response = api.SubAccounts.Create(request);

// Use response as needed
...

One more thing about ~Response Types (since v0.7.2)!

For situations where some properties (data.[property1][property2][...n]) are not directly exposed via the Typed Interface implemented by this library, all PayStack.Net ~Response types expose the .RawJson property that contains the raw JSON content returned from the PayStack Server, as a String.

As a String, this value can be parsed using any .Net compatible JSON parser, for use.

However, to make it easier to work this raw JSON (especially to remove the need for extra parsing before use), all ~Response types has an extension method, .AsJObject(), which returns a JObject instance. With this object, any property of the returned JSON can be retrieved as described on this page.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on Paystack.Net:

Package Downloads
Xown.Travels.Core

The core library for travel operations

madeinOffice

Package Description

247Travels.Core

The Core Library for 247 Travels

Dw.Core

The core library for Domestic Workers platform

Xown.Hotels.Core

The core library for hotel operations

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.0 26,476 10/3/2022
1.0.1 3,419 8/20/2022
0.7.7 18,170 9/12/2019
0.7.6 1,463 9/7/2019
0.7.4 2,589 4/2/2019
0.7.3 1,083 3/25/2019
0.7.2 1,397 12/6/2018
0.7.1 2,450 10/28/2017
0.7.0 1,486 10/1/2017
0.6.6 46,480 1/20/2017
0.6.5 1,499 12/28/2016
0.6.4 1,403 12/27/2016

-- v1.1.0 --
   * [Breaking] Update transaction ID from Int32 (int) to Int64 (long). (Thanks @teghoz!)

   -- v1.0.1 --
   * Fix: Clean-up URL for Type-less API calls.

   -- v1.0.0 --
   * Feat: 100% API coverage (via the Type-less API)
   * Bug fix: Closes #21 (Thanks @thrizy, sorry it took so long!)
   * Feat: Adds PartialDebit (Typed API).

   -- v0.7.7 --
   * Bug fix: Correct the BVN endpoint. #17
   
   
   -- v0.7.6 --
   * Bug fix: Ensure response.data exists before parsing metadata, especially when response.status is 'false'. #16
   
   
   -- v0.7.5 --
   * Bug fix: #15 Incorrect attempt to parse 'metadata' from JArray responses.
   * Enable multi-currency for transaction initializer (Inspired by @django101, #14)
   
   -- v0.7.4 --
   * Bug fix. Adds ChargeApi missing request DTOs properties: Reference and DeviceId - (#12)
   * Minor bug fixes.

   -- v0.7.3 --
   * Bug fix. Transaction's ChargeAuthorization method included (big thanks to Aghogho Bernard - @teghoz)
   * Transaction's CheckAuthorization and RequestReauthorization methods now included.
   * Expose more query params to the Transaction's Export method.

   -- v0.7.2 --
   * Bug fix. Charge.Data field Url
   * All response types now implements IHasRawResponse interface. This introduces 'RawJson' property which contains the raw server's JSON response.
   
   -- v0.7.1 --
   * "Charge" API (Bank, Card, Authorization Code) now available [Complete].
   
   -- v0.7.0 --
* .Net Core support (implements .Net Standard 2.0).
* "Miscellaneous" API now available [Complete].
* "Funds Transfer" API  (Bulk, Control, Initiate, List, & Fetch) now available [Complete].

-- up to v0.6.6 --
Implements PayStack Standard Flow along with APIs for Transactions, Customers, SubAccounts, among others.