PayPal Subscription API v1 - 구독 API

{
  "product_id": "PROD-XXCD1234QWER65782",
  "name": "비디오 스트리밍 서비스 플랜",
  "description": "비디오 스트리밍 서비스 기본 플랜",
  "status": "ACTIVE",
  "billing_cycles": [
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 1,
      "total_cycles": 2,
      "pricing_scheme": {
        "fixed_price": {
          "value": "3",
          "currency_code": "USD"
        }
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "REGULAR",
      "sequence": 2,
      "total_cycles": 12,
      "pricing_scheme": {
        "fixed_price": {
          "value": "10",
          "currency_code": "USD"
        }
      }
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "value": "10",
      "currency_code": "USD"
    },
    "setup_fee_failure_action": "CONTINUE",
    "payment_failure_threshold": 3
  },
  "taxes": {
    "percentage": "10",
    "inclusive": false
  }
}

{
  "id": "P-5ML4271244454362WXNWU5NQ",
  "product_id": "PROD-XXCD1234QWER65782",
  "name": "비디오 스트리밍 서비스 플랜",
  "description": "비디오 스트리밍 서비스 기본 플랜",
  "status": "ACTIVE",
  "billing_cycles": [
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 1,
      "total_cycles": 2,
      "pricing_scheme": {
        "fixed_price": {
          "value": "3",
          "currency_code": "USD"
        },
        "version": 1,
        "create_time": "2020-05-27T12:13:51Z",
        "update_time": "2020-05-27T12:13:51Z"
      }
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "value": "10",
      "currency_code": "USD"
    },
    "setup_fee_failure_action": "CONTINUE",
    "payment_failure_threshold": 3
  },
  "taxes": {
    "percentage": "10",
    "inclusive": false
  },
  "create_time": "2020-05-27T12:13:51Z",
  "update_time": "2020-05-27T12:13:51Z",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
      "rel": "self",
      "method": "GET"
    }
  ]
}

{
  "plans": [
    {
      "id": "P-9CT60829WM695623HL7QGYOI",
      "name": "넷플릭스 플랜 17012019",
      "status": "ACTIVE",
      "description": "넷플릭스 기본 플랜",
      "usage_type": "LICENSED",
      "create_time": "2020-12-23T07:08:40Z",
      "links": [
        {
          "href": "https://api-m.paypal.com/v1/billing/plans/P-9CT60829WM695623HL7QGYOI",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/billing/plans?page_size=10&page=1",
      "rel": "self",
      "method": "GET"
    }
  ]
}

{
  "id": "P-5ML4271244454362WXNWU5NQ",
  "product_id": "PROD-XXCD1234QWER65782",
  "name": "기본 플랜",
  "description": "기본 플랜",
  "status": "ACTIVE",
  "billing_cycles": [
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 1,
      "total_cycles": 2,
      "pricing_scheme": {
        "fixed_price": {
          "currency_code": "USD",
          "value": "3"
        },
        "version": 1,
        "create_time": "2020-05-27T12:13:51Z",
        "update_time": "2020-05-27T12:13:51Z"
      }
    }
  ],
  "taxes": {
    "percentage": "10",
    "inclusive": false
  },
  "create_time": "2020-05-27T12:13:51Z",
  "update_time": "2020-05-27T12:13:51Z",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
      "rel": "self",
      "method": "GET"
    }
  ]
}

[
  {
    "op": "replace",
    "path": "/payment_preferences/payment_failure_threshold",
    "value": 7
  },
  {
    "op": "replace",
    "path": "/name",
    "value": "업데이트된 비디오 스트리밍 서비스 플랜"
  }
]

{
  "plan_id": "P-5ML4271244454362WXNWU5NQ",
  "start_time": "2025-01-01T00:00:00Z",
  "quantity": "1",
  "shipping_amount": {
    "currency_code": "USD",
    "value": "10.00"
  },
  "subscriber": {
    "name": {
      "given_name": "홍",
      "surname": "길동"
    },
    "email_address": "subscriber@example.com"
  },
  "application_context": {
    "brand_name": "우리 회사",
    "locale": "ko-KR",
    "shipping_preference": "SET_PROVIDED_ADDRESS",
    "user_action": "SUBSCRIBE_NOW",
    "payment_method": {
      "payer_selected": "PAYPAL",
      "payee_preferred": "IMMEDIATE_PAYMENT_REQUIRED"
    },
    "return_url": "https://example.com/returnUrl",
    "cancel_url": "https://example.com/cancelUrl"
  }
}

{
  "reason": "구독자 요청에 의한 일시 정지"
}

{
  "reason": "구독자 요청에 의한 취소"
}

{
  "reason": "구독자 요청에 의한 활성화"
}

{
  "note": "정기 결제 수집",
  "capture_type": "OUTSTANDING_BALANCE",
  "amount": {
    "currency_code": "USD",
    "value": "10.00"
  }
}

Frontend (React/Vue/Angular)
    ↓
Backend API (Node.js/Python/Java)
    ↓
Database (PostgreSQL/MySQL)
    ↓
PayPal Subscription API
    ↓
Webhook Handler

-- 제품 테이블
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    paypal_product_id VARCHAR(50) UNIQUE NOT NULL,
    name VARCHAR(127) NOT NULL,
    description TEXT,
    category VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
 
-- 플랜 테이블
CREATE TABLE plans (
    id SERIAL PRIMARY KEY,
    paypal_plan_id VARCHAR(50) UNIQUE NOT NULL,
    product_id INTEGER REFERENCES products(id),
    name VARCHAR(127) NOT NULL,
    description TEXT,
    status VARCHAR(20) DEFAULT 'ACTIVE',
    billing_cycles JSONB,
    payment_preferences JSONB,
    taxes JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
 
-- 구독 테이블
CREATE TABLE subscriptions (
    id SERIAL PRIMARY KEY,
    paypal_subscription_id VARCHAR(50) UNIQUE NOT NULL,
    plan_id INTEGER REFERENCES plans(id),
    user_id INTEGER REFERENCES users(id),
    status VARCHAR(20) DEFAULT 'APPROVAL_PENDING',
    start_time TIMESTAMP,
    next_billing_time TIMESTAMP,
    quantity INTEGER DEFAULT 1,
    shipping_amount DECIMAL(10,2),
    subscriber_info JSONB,
    application_context JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
 
-- 구독 거래 테이블
CREATE TABLE subscription_transactions (
    id SERIAL PRIMARY KEY,
    subscription_id INTEGER REFERENCES subscriptions(id),
    paypal_transaction_id VARCHAR(50) UNIQUE NOT NULL,
    amount DECIMAL(10,2),
    currency_code VARCHAR(3),
    transaction_type VARCHAR(20), -- PAYMENT, REFUND, CANCELLATION
    status VARCHAR(20),
    transaction_time TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

const express = require('express');
const paypal = require('@paypal/checkout-server-sdk');
 
// PayPal 환경 설정
const environment = new paypal.core.SandboxEnvironment(
    process.env.PAYPAL_CLIENT_ID,
    process.env.PAYPAL_CLIENT_SECRET
);
const client = new paypal.core.PayPalHttpClient(environment);
 
// 플랜 생성
app.post('/api/plans', async (req, res) => {
    try {
        const request = new paypal.orders.OrdersCreateRequest();
        request.prefer("return=representation");
        request.requestBody({
            product_id: req.body.product_id,
            name: req.body.name,
            description: req.body.description,
            status: "ACTIVE",
            billing_cycles: req.body.billing_cycles,
            payment_preferences: req.body.payment_preferences,
            taxes: req.body.taxes
        });
 
        const response = await client.execute(request);
        
        // 데이터베이스에 플랜 정보 저장
        await savePlanToDatabase(response.result);
        
        res.json(response.result);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});
 
// 구독 생성
app.post('/api/subscriptions', async (req, res) => {
    try {
        const request = new paypal.orders.OrdersCreateRequest();
        request.prefer("return=representation");
        request.requestBody({
            plan_id: req.body.plan_id,
            start_time: req.body.start_time,
            quantity: req.body.quantity,
            subscriber: req.body.subscriber,
            application_context: req.body.application_context
        });
 
        const response = await client.execute(request);
        
        // 데이터베이스에 구독 정보 저장
        await saveSubscriptionToDatabase(response.result);
        
        res.json(response.result);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});
 
// 웹훅 처리
app.post('/api/webhooks/paypal', async (req, res) => {
    const event = req.body;
    
    switch (event.event_type) {
        case 'BILLING.SUBSCRIPTION.CREATED':
            await handleSubscriptionCreated(event);
            break;
        case 'BILLING.SUBSCRIPTION.ACTIVATED':
            await handleSubscriptionActivated(event);
            break;
        case 'BILLING.SUBSCRIPTION.SUSPENDED':
            await handleSubscriptionSuspended(event);
            break;
        case 'BILLING.SUBSCRIPTION.CANCELLED':
            await handleSubscriptionCancelled(event);
            break;
        case 'PAYMENT.SALE.COMPLETED':
            await handlePaymentCompleted(event);
            break;
        case 'PAYMENT.SALE.DENIED':
            await handlePaymentFailed(event);
            break;
        default:
            console.log('Unhandled webhook event:', event.event_type);
    }
    
    res.status(200).send('OK');
});

import React, { useState, useEffect } from 'react';
import { PayPalScriptProvider, PayPalButtons } from '@paypal/react-paypal-js';
 
const SubscriptionComponent = ({ planId }) => {
    const [subscriptionID, setSubscriptionID] = useState('');
    const [isLoading, setIsLoading] = useState(false);
 
    const createSubscription = (data, actions) => {
        return actions.subscription.create({
            plan_id: planId,
            application_context: {
                brand_name: "우리 회사",
                locale: "ko-KR",
                shipping_preference: "NO_SHIPPING",
                user_action: "SUBSCRIBE_NOW",
                return_url: "https://example.com/return",
                cancel_url: "https://example.com/cancel"
            }
        });
    };
 
    const onApprove = (data, actions) => {
        setSubscriptionID(data.subscriptionID);
        
        // 백엔드에 구독 정보 저장
        fetch('/api/subscriptions/activate', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                subscriptionID: data.subscriptionID
            })
        })
        .then(response => response.json())
        .then(data => {
            alert('구독이 성공적으로 생성되었습니다!');
        })
        .catch(error => {
            console.error('Error:', error);
            alert('구독 생성 중 오류가 발생했습니다.');
        });
    };
 
    const onError = (err) => {
        console.error('PayPal Error:', err);
        alert('구독 생성 중 오류가 발생했습니다.');
    };
 
    return (
        <PayPalScriptProvider options={{
            "client-id": process.env.REACT_APP_PAYPAL_CLIENT_ID,
            vault: true,
            intent: "subscription"
        }}>
            <div className="subscription-container">
                <h2>구독 플랜 선택</h2>
                <PayPalButtons
                    createSubscription={createSubscription}
                    onApprove={onApprove}
                    onError={onError}
                    style={{
                        layout: "vertical",
                        color: "blue",
                        shape: "rect",
                        label: "subscribe"
                    }}
                />
                {subscriptionID && (
                    <div className="subscription-success">
                        <p>구독 ID: {subscriptionID}</p>
                        <p>구독이 성공적으로 생성되었습니다!</p>
                    </div>
                )}
            </div>
        </PayPalScriptProvider>
    );
};
 
export default SubscriptionComponent;