Paystack.Net 1.0.1

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.