PayPal

PayPal Agent Toolkit

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

사용 가능한 도구

PayPal Agent Toolkit은 다음 도구를 제공합니다.

인보이스

• create_invoice: 받는 사람의 청구 세부 정보, 라인 항목, 인보이스 메모, 사용자 정의 색상 테마, 선택적 배송 비용 및 결제 방법으로 PAY_BY_BANK를 활성화하는 옵션을 포함하여 PayPal 시스템에 새 인보이스를 생성합니다.
• create_recurring_series: 일정에 따라 인보이스를 자동으로 생성하고 전송하는 반복 인보이스 시리즈를 생성합니다.
• 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,
        createRecurringSeries: 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 모드)

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

사전 요구 사항

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

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

1. PayPal 개발자 계정 생성:

   • PayPal 개발자 대시보드로 이동
   • 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은 출력 정확성에 대해 보장하지 않으며, 그 사용으로 인한 결정, 조치 또는 결과에 대해 책임을 지지 않습니다.