KsuFlickPay 1.0.0

PayStack API for .Net

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

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;
...

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

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.