Paystack OpenAPI Specification

The OpenAPI specification for the Paystack API.

Getting Started

The OpenAPI specification provides another alternative to test the Paystack API. You can download the specification and make use of it on:

• SwaggerHub
• OpenAPI (Swagger) Editor

Set up locally

• Clone repo

  git clone git@github.com:PaystackOSS/openapi.git

• Navigate to the cloned project and install dependencies

  cd openapi
  pnpm install

• Start the server to view the spec in your browser

  pnpm dev

  [!NOTE] At the moment, the paystack.yaml file is the only spec that is automatically opened in your browser. If the spec doesn't open automatically in your browser, you can manually open http://localhost:7070 in your browser.

Components

There are two top-level folders of interest in this repo:

• src: This contains the assets, scripts and basic .html for working and viewing the OpenAPI Specification (OAS) file.
  • assets: This contains the Paystack OAS files:
    • base: Default single OAS file that was used to rebuild codebase (to be removed)
    • openapi: This contains the individual, manageable parts of the OAS
    • sdk: This is a single file specification being used for client library generation. It contains just enough parameters for our client libraries (might be removed later).
    • use_cases: This is a collection of specifications containing APIs for common use cases of the Paystack API. For example, the wallet.yaml contains the APIs needed to build a wallet feature into your application. The specifications in this directory are used to create the collections in our Postman Workspace.
• dist: Not all OpenAPI readers can read from different file sources, so we built a single file from all the components in the main directory.

SDKs

This repo also contains TypeScript SDKs generated from the OpenAPI spec in src/assets/sdk/paystack.yaml.

Node (server)

• Package: @alexasomba/paystack-node

import { createPaystack } from "@alexasomba/paystack-node";

const paystack = createPaystack({
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
});

const { data, error } = await paystack.transaction_initialize({
  body: { email: "customer@example.com", amount: 5000 },
});

if (error) throw error;

Axios (server)

• Package: @alexasomba/paystack-axios

import { createPaystack } from "@alexasomba/paystack-axios";

const paystack = createPaystack({
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
});

const { data, error } = await paystack.transaction_initialize({
  body: { email: "customer@example.com", amount: 5000 },
});

if (error) throw error;

Browser

• Package: @alexasomba/paystack-browser

import { createPaystackClient } from "@alexasomba/paystack-browser";

const paystack = createPaystackClient({
  apiKey: "YOUR_API_KEY",
});

const { data, error } = await paystack.POST("/transaction/initialize", {
  body: { email: "customer@example.com", amount: 5000 },
});

if (error) throw error;

Build locally

pnpm sdk:build

Other languages (generated)

The following SDKs are generated via OpenAPI Generator and live in the sdks/ directory:

• Python: sdks/python (includes pyproject.toml / setup.py)
• PHP: sdks/php (includes composer.json)
• Go: sdks/go (includes go.mod)

Regenerate them with:

pnpm sdk:others:generate

Each folder contains its own README with language-specific usage and install instructions.

Packagist (PHP)

Packagist (public) expects a VCS repository where the package's composer.json is at the repository root. Since this repo is a monorepo and the PHP SDK lives in sdks/php, publishing to Packagist is handled by splitting sdks/php into its own repository.

• Create a dedicated repo for the PHP SDK (alexasomba/paystack-php) and add it on Packagist.
• This repo includes a GitHub Action which, on tags like v1.1.1, subtree-splits sdks/php and pushes it to the dedicated repo (including the same tag).
• Configure these GitHub repo secrets:
  • PHP_SPLIT_REPO: alexasomba/paystack-php
  • PHP_SPLIT_PUSH_TOKEN: a GitHub Personal Access Token (PAT) with repo scope (used to push the split branch and tags to the target repo)
  • PACKAGIST_TOKEN: a Packagist API token (or username:token) used by the register-packagist workflow to create or update the package on Packagist

If you see Permission to ... denied to github-actions[bot] in the split workflow, check that PHP_SPLIT_PUSH_TOKEN is set and has the required permissions.

Contributing

Here are some of the ways to contribute to this repository:

• Create a use case
• Raise an issue
• Suggest an improvement

Issues

You can open an issue if you discover any bug or have problems using this repo.

License

This repository is made available under the MIT license. Kindly read the LICENSE file for more information.