PayPal MCP Server

공식

PayPal Model Context Protocol 서버를 사용하면 함수 호출을 통해 PayPal API와 통합할 수 있습니다. 이 프로토콜은 다양한 PayPal 서비스와 상호작용할 수 있는 여러 도구를 지원합니다.

GitHub
187

문서

PayPal 에이전트 툴킷

PayPal 에이전트 툴킷은 OpenAI의 Agent SDK, LangChain, Vercel의 AI SDK, Model Context Protocol(MCP) 등 주요 에이전트 프레임워크가 함수 호출을 통해 PayPal API와 통합될 수 있도록 지원합니다. TypeScript를 지원하며 PayPal API와 PayPal SDK를 기반으로 구축되었습니다.

사용 가능한 도구

PayPal 에이전트 툴킷은 다음 도구를 제공합니다:

인보이스

  • create_invoice: PayPal 시스템에 새 인보이스 생성
  • list_invoices: 페이지네이션 및 필터링 옵션으로 인보이스 목록 조회
  • get_invoice: 특정 인보이스의 세부 정보 조회
  • send_invoice: 수신자에게 인보이스 발송
  • send_invoice_reminder: 기존 인보이스에 대한 리마인더 발송
  • cancel_sent_invoice: 발송된 인보이스 취소
  • generate_invoice_qr_code: 인보이스용 QR 코드 생성

결제

  • create_order: 제공된 세부 정보를 기반으로 PayPal 시스템에 주문 생성
  • get_order: 주문 세부 정보 조회
  • pay_order: 승인된 주문에 대한 결제 처리
  • create_refund: 캡처된 결제에 대한 환불 처리
  • get_refund: 특정 환불에 대한 세부 정보 조회

분쟁 관리

  • list_disputes: 모든 진행 중인 분쟁 요약 조회
  • get_dispute: 특정 분쟁의 상세 정보 조회
  • accept_dispute_claim: 분쟁 청구 수락

배송 추적

  • create_shipment_tracking: 배송 추적 기록 생성
  • get_shipment_tracking: 배송 추적 정보 조회
  • update_shipment_tracking: 배송 추적 정보 업데이트

카탈로그 관리

  • create_product: PayPal 카탈로그에 새 제품 생성
  • list_products: 페이지네이션 및 필터링 옵션으로 제품 목록 조회
  • show_product_details: 특정 제품의 세부 정보 조회

구독 관리

  • create_subscription_plan: 새 구독 플랜 생성
  • list_subscription_plans: 구독 플랜 목록 조회
  • show_subscription_plan_details: 특정 구독 플랜의 세부 정보 조회
  • create_subscription: 새 구독 생성
  • show_subscription_details: 특정 구독의 세부 정보 조회
  • update_subscription: 기존 구독 업데이트
  • cancel_subscription: 활성 구독 취소

보고 및 인사이트

  • list_transactions: 페이지네이션 및 필터링 옵션으로 거래 목록 조회
  • get_merchant_insights: 판매자의 비즈니스 인텔리전스 지표 및 분석 조회

TypeScript

설치

패키지를 수정하려는 경우가 아니라면 이 소스 코드는 필요하지 않습니다. 단순히 패키지를 사용하려면 다음을 실행하세요:

npm install @paypal/agent-toolkit

요구 사항

  • Node 18+

사용법

라이브러리는 PayPal 개발자 대시보드에서 확인할 수 있는 계정의 클라이언트 ID와 시크릿으로 구성해야 합니다.

이 툴킷은 Vercel의 AI SDK와 함께 작동하며 도구 목록으로 전달할 수 있습니다. 자세한 내용은 예제를 참조하세요.

import { PayPalAgentToolkit } from '@paypal/agent-toolkit/ai-sdk';
const paypalToolkit = new PayPalAgentToolkit({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: {
      invoices: {
        create: true,
        list: true,
        send: true,
        sendReminder: true,
        cancel: true,
        generateQRC: true,
      },
      products: { create: true, list: true, update: true },
      subscriptionPlans: { create: true, list: true, show: true },
      shipment: { create: true, show: true, cancel: true },
      orders: { create: true, get: true },
      disputes: { list: true, get: true },
    },
  },
});

샌드박스 모드를 사용하려면 구성에 컨텍스트를 추가하세요.

configuration: {
  context: {
    sandbox: true,
  }
}

워크플로 초기화

import { PayPalWorkflows, ALL_TOOLS_ENABLED } from '@paypal/agent-toolkit/ai-sdk';
const paypalWorkflows = new PayPalWorkflows({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: ALL_TOOLS_ENABLED,
  },
});

사용법

툴킷 사용하기

const llm: LanguageModelV1 = getModel(); // The model to be used with ai-sdk
const { text: response } = await generateText({
  model: llm,
  tools: paypalToolkit.getTools(),
  maxSteps: 10,
  prompt: `Create an order for $50 for custom handcrafted item and get the payment link.`,
});

환경 변수

다음 환경 변수를 사용할 수 있습니다:

  • PAYPAL_ACCESS_TOKEN: PayPal 액세스 토큰
  • PAYPAL_ENVIRONMENT: 샌드박스 모드는 SANDBOX, 프로덕션은 PRODUCTION로 설정 (기본값은 SANDBOX 모드)

이 가이드는 클라이언트 ID와 클라이언트 시크릿을 찾는 방법을 포함하여 PayPal API 통합을 위한 액세스 토큰 생성 방법을 설명합니다.

사전 요구 사항

  • PayPal 개발자 계정 (샌드박스용)
  • PayPal 비즈니스 계정 (프로덕션용)

클라이언트 ID 및 클라이언트 시크릿 찾기

  1. PayPal 개발자 계정 생성:

  2. 자격 증명 접근:

    • 개발자 대시보드에서 메뉴의 앱 및 자격 증명 클릭
    • 필요에 따라 샌드박스와 라이브 모드 간 전환

  3. 앱 생성 또는 보기:

    • 새 앱을 만들려면 앱 생성 클릭
    • 앱 이름을 지정하고 연결할 비즈니스 계정 선택
    • 기존 앱의 경우 앱 이름을 클릭하여 세부 정보 확인

  4. 자격 증명 검색:

    • 앱이 생성되거나 선택되면 다음 정보가 표시된 화면이 나타납니다:
      • 클라이언트 ID: 앱의 공개 식별자
      • 클라이언트 시크릿: 비공개 키 ("표시" 클릭 후 확인 가능)
    • 액세스 토큰 생성에 필요하므로 이 자격 증명을 안전하게 저장하세요.

액세스 토큰 생성

cURL 사용

curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \\
  -H \"Accept: application/json\" \\
  -H \"Accept-Language: en_US\" \\
  -u \"CLIENT_ID:CLIENT_SECRET\" \\
  -d \"grant_type=client_credentials\"

CLIENT_ID 및 CLIENT_SECRET을 실제 자격 증명으로 교체하세요. 프로덕션의 경우 샌드박스 URL 대신 https://api-m.paypal.com을 사용하세요.

Postman 사용

  1. https://api-m.sandbox.paypal.com/v1/oauth2/token에 대한 새 요청 생성
  2. 메서드를 POST로 설정
  3. Authorization에서 Basic Auth를 선택하고 클라이언트 ID와 클라이언트 시크릿 입력
  4. Body에서 x-www-form-urlencoded를 선택하고 키 grant_type에 값 client_credentials 추가
  5. 요청 전송

응답

성공적인 응답은 다음과 같습니다:

{
  "scope": "...",
  "access_token": "Your Access Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32400,
  "nonce": "..."
}

Claude Desktop 통합에 사용할 access_token 값을 복사하세요.

토큰 세부 정보

  • 샌드박스 토큰: 3~8시간 유효
  • 프로덕션 토큰: 8시간 유효
  • 만료 전 토큰 갱신 로직을 구현하는 것이 좋습니다.

Claude Desktop에서 토큰 사용

액세스 토큰을 확보한 후 Claude Desktop 커넥터 구성에서 PAYPAL_ACCESS_TOKEN 값을 업데이트하세요:

{
  "env": {
    "PAYPAL_ACCESS_TOKEN": "YOUR_NEW_ACCESS_TOKEN",
    "PAYPAL_ENVIRONMENT": "SANDBOX"
  }
}

모범 사례

  1. 클라이언트 ID와 클라이언트 시크릿을 안전하게 저장
  2. 토큰 만료를 처리하기 위한 토큰 갱신 로직 구현
  3. 환경별 토큰 사용 (테스트는 샌드박스, 실제 거래는 프로덕션)
  4. 애플리케이션 코드에 토큰을 하드코딩하지 않기

면책 조항

AI 생성 콘텐츠는 부정확하거나 불완전할 수 있습니다. 사용자는 정보를 신뢰하기 전에 독립적으로 확인할 책임이 있습니다. PayPal은 출력의 정확성에 대해 어떠한 보증도 하지 않으며, 그 사용으로 인한 결정, 조치 또는 결과에 대해 책임을 지지 않습니다.