paystack-setup

Paystack のセットアップ

TypeScript／JavaScript のサーバーサイドアプリケーション向けに、Paystack API クライアントの基盤と環境設定をセットアップします。

API の基本事項

プロパティ	値
ベース URL	https://api.paystack.co
認証ヘッダー	Authorization: Bearer SECRET_KEY
コンテンツタイプ	application/json
レスポンス形式	{ status: boolean, message: string, data: object }
金額の単位	通貨の補助単位（表示金額に 100 を掛けます）
トランザクション ID	符号なし 64 ビット整数 — TypeScript では string を使用します

対応通貨と補助単位

通貨	コード	補助単位	乗数
ナイジェリア・ナイラ	NGN	コボ	×100
米ドル	USD	セント	×100
ガーナ・セディ	GHS	ペセワ	×100
南アフリカ・ランド	ZAR	セント	×100
ケニア・シリング	KES	セント	×100
西アフリカ CFA フラン	XOF	—	×100
エジプト・ポンド	EGP	ピアストル	×100
ルワンダ・フラン	RWF	—	×100

環境変数

.env ファイル（または Next.js の場合は .env.local）を作成します。

PAYSTACK_SECRET_KEY=sk_test_xxxxx        # Server-side only, NEVER expose to client
NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY=pk_test_xxxxx  # Safe for client-side (Popup/InlineJS)

シークレットキー（sk_*）をクライアントサイドのコード、ブラウザーのバンドル、公開リポジトリに絶対に含めないでください。公開キー（pk_*）は、Paystack Popup／InlineJS でフロントエンドから使用する場合に限り安全です。

テストキーは sk_test_／pk_test_ で始まります。本番キーは sk_live_／pk_live_ で始まります。Paystack Dashboard の「Settings」→「API Keys & Webhooks」から取得してください。

依存関係のインストール

# For client-side Popup/InlineJS checkout
npm install @paystack/inline-js

# Or with pnpm / yarn
pnpm add @paystack/inline-js
yarn add @paystack/inline-js

サーバーサイド SDK は不要です。以下のヘルパーと組み込みの fetch API を使用してください。

TypeScript API クライアントヘルパー

再利用可能で型安全な Paystack クライアントを作成します。ほかのすべての Paystack スキルは、このパターンを使用します。

// lib/paystack.ts
const PAYSTACK_SECRET_KEY = process.env.PAYSTACK_SECRET_KEY;

if (!PAYSTACK_SECRET_KEY) {
  throw new Error("PAYSTACK_SECRET_KEY is not set in environment variables");
}

export interface PaystackResponse<T = unknown> {
  status: boolean;
  message: string;
  data: T;
}

export interface PaystackListResponse<T = unknown> {
  status: boolean;
  message: string;
  data: T[];
  meta: {
    total: number;
    skipped: number;
    perPage: number;
    page: number;
    pageCount: number;
  };
}

export class PaystackError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public response?: unknown
  ) {
    super(message);
    this.name = "PaystackError";
  }
}

export async function paystackRequest<T>(
  endpoint: string,
  options: RequestInit = {}
): Promise<PaystackResponse<T>> {
  const url = `https://api.paystack.co${endpoint}`;

  const response = await fetch(url, {
    ...options,
    headers: {
      Authorization: `Bearer ${PAYSTACK_SECRET_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!response.ok) {
    throw new PaystackError(
      data.message || `Paystack API error: ${response.status}`,
      response.status,
      data
    );
  }

  return data as PaystackResponse<T>;
}

ページネーション

すべてのリストエンドポイントは、クエリパラメーターとして perPage（既定値：50、最大値：100）と page（既定値：1）を受け付けます。レスポンスには meta オブジェクトが含まれます。

{
  "meta": {
    "total": 243,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 5
  }
}

次のようにページネーション付きのクエリを作成します。

const params = new URLSearchParams({
  perPage: "20",
  page: "2",
  from: "2024-01-01T00:00:00.000Z",
  to: "2024-12-31T23:59:59.000Z",
});
const result = await paystackRequest<Transaction[]>(`/transaction?${params}`);

金額の変換

Paystack に送信する前に表示金額を必ず補助単位に変換し、表示する際には元に戻してください。

// Display → Paystack (multiply by 100)
const amountInKobo = Math.round(amountInNaira * 100);

// Paystack → Display (divide by 100)
const amountInNaira = amountInKobo / 100;

Math.round() を使用して、19.99 * 100 = 1998.9999999999998 のような浮動小数点の問題を回避してください。

HTTP メソッド

メソッド	用途
POST	リソースの作成、アクションの開始
GET	リソースの取得、一覧表示、検証
PUT	リソースの更新
DELETE	リソースの無効化または削除

エラー処理

Paystack の呼び出しを try/catch で囲み、PaystackError クラスを処理してください。

import { paystackRequest, PaystackError } from "@/lib/paystack";

try {
  const result = await paystackRequest<Transaction>("/transaction/verify/ref_123");
} catch (error) {
  if (error instanceof PaystackError) {
    console.error(`Paystack error ${error.statusCode}: ${error.message}`);
    // Handle specific status codes
    if (error.statusCode === 400) { /* bad request / validation error */ }
    if (error.statusCode === 401) { /* invalid secret key */ }
    if (error.statusCode === 404) { /* resource not found */ }
  }
  throw error;
}

セキュリティチェックリスト

• PAYSTACK_SECRET_KEY は環境変数にのみ保存し、コードには記述しないでください
• .env と .env.local を .gitignore に追加してください
• Paystack API の呼び出しはすべてサーバーサイド（API ルート、サーバーアクション、バックエンド）で実行してください
• すべてのコールバック URL と Webhook URL に HTTPS を使用してください
• トランザクションを初期化する前に、サーバーサイドで金額を検証してください
• 支払い後は必ずサーバーサイドでトランザクションのステータスを検証し、クライアントサイドのコールバックだけを信用しないでください