PayPal TypeScript Types

TypeScript type definitions automatically generated from PayPal's official OpenAPI specifications.

Features

• Type-safe: Fully typed interfaces for all PayPal REST APIs
• Up-to-date: Generated directly from official PayPal OpenAPI specs
• Comprehensive: Covers 13 PayPal APIs including Orders, Payments, Subscriptions, and more
• Tree-shakeable: Import only the types you need

Installation

npm install @better-giving/paypal
# or
pnpm add @better-giving/paypal

Available Modules

This package provides TypeScript types for the following PayPal APIs:

Module	Import Path	API
Orders	@better-giving/paypal/generated (orders)	Checkout Orders API v2
Payments	@better-giving/paypal/generated (payments)	Payments API v2
Payments v1	@better-giving/paypal/generated (payments_v1)	Payments API v1 (Legacy)
Subscriptions	@better-giving/paypal/generated (subscriptions)	Billing Subscriptions API v1
Invoices	@better-giving/paypal/generated (invoices)	Invoicing API v2
Payouts	@better-giving/paypal/generated (payouts)	Payouts Batch API v1
Payment Tokens	@better-giving/paypal/generated (payment_tokens)	Vault Payment Tokens API v3
Disputes	@better-giving/paypal/generated (disputes)	Customer Disputes API v1
Partner Referrals	@better-giving/paypal/generated (partner_referrals)	Partner Referrals API v2
Catalog Products	@better-giving/paypal/generated (catalog_products)	Catalog Products API v1
Shipment Tracking	@better-giving/paypal/generated (shipment_tracking)	Shipment Tracking API v1
Web Experience Profiles	@better-giving/paypal/generated (web_experience_profiles)	Payment Experience API v1
Transaction Search	@better-giving/paypal/generated (transaction_search)	Transaction Search API v1
Webhooks	@better-giving/paypal/generated (webhooks)	Webhooks Management API v1
SDK	@better-giving/paypal	PayPal SDK Helper

Usage

Import types and helper functions from the package:

// Import helper types and utilities from the main package
import type {
  CreateOrderRequest,
  CreateOrderResponse,
  Order,
  PurchaseUnitsRequest
} from '@better-giving/paypal';

// Or import raw generated types from specific API modules
import { orders, payments, subscriptions } from '@better-giving/paypal/generated';

// Use the generated types directly
type OrderDetail = typeof orders.components.schemas.order;
type PaymentCapture = typeof payments.components.schemas['capture-2'];

Using the PayPal SDK Helper

This package includes a simple SDK helper for making API calls:

import { PayPalSDK, type ISdkConfig } from '@better-giving/paypal';

const sdk = new PayPalSDK({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  api_url: 'https://api-m.sandbox.paypal.com', // or https://api-m.paypal.com for production
});

// Create an order
const order = await sdk.create_order({
  intent: 'CAPTURE',
  purchase_units: [
    {
      amount: {
        currency_code: 'USD',
        value: '100.00',
      },
    },
  ],
});

console.log('Order ID:', order.id);

Example with Fetch

import type { CreateOrderRequest, CreateOrderResponse } from '@better-giving/paypal';

async function create_order(order_data: CreateOrderRequest, access_token: string): Promise<CreateOrderResponse> {
  const response = await fetch('https://api.paypal.com/v2/checkout/orders', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    body: JSON.stringify(order_data)
  });

  if (!response.ok) {
    throw new Error('Failed to create order');
  }

  return response.json();
}

Development

Prerequisites

• Node.js 20+
• pnpm (via corepack)

Building from Source

# Clone the repository
git clone <your-repo-url>
cd paypal-typescript-types

# Enable corepack
corepack enable

# Install dependencies
pnpm install

# Download PayPal OpenAPI specs and generate types
pnpm build

Scripts

• pnpm build - Full build process (download specs + generate types + compile)
• pnpm clean - Remove generated files and build artifacts
• pnpm format - Format code with Biome

This project uses the TypeScript compiler (tsc) for compiling source code and generating type declarations.

Publishing

To publish a new version:

# Login to npm registry (first time only)
npm login

# Update version in package.json
npm version patch  # or minor, or major

# Publish to npm registry
npm publish --access public

Updating Types

To update the types when PayPal releases new API specifications:

pnpm build
npm version patch
npm publish

Type Structure

Each API module exports types following the OpenAPI structure:

{
  paths: {
    '/api/path': {
      get: { parameters, responses, ... },
      post: { requestBody, responses, ... },
      ...
    }
  },
  components: {
    schemas: { ... },
    parameters: { ... },
    responses: { ... }
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Disclaimer

This is an unofficial package. For official PayPal SDKs and documentation, visit PayPal Developer.

Related Links

• PayPal REST API Specifications
• PayPal Developer Documentation
• openapi-typescript