Paypal API Payments Commerce

PayPal API for Payments & Commerce

This skill implements the core functionalities of the PayPal API focused on managing ecommerce transactions, including Orders, Payments, Subscriptions, Payouts, and Disputes. It provides developers with clear guidelines and implementation patterns for integrating PayPal services into their applications.

TL;DR Checklist

• Validate all API requests for required fields and scopes (Fail Fast)
• Use guard clauses to handle missing input at function entry (Early Exit)
• Ensure all payment methods are tested with automated unit tests (Atomic Predictability)
• Return structured data responses for easy handling (No Mutations)
• Implement error handling for all API interactions to catch failures immediately

When to Use

• To manage orders for online store products directly through PayPal.
• To process one-time or recurring payments securely through PayPal.
• To handle subscription-based billing for services using PayPal.
• To facilitate payouts to multiple users (e.g., affiliates or contractors).
• To manage disputes for transactions via PayPal's built-in handling.

Core Workflow

1. Login & Authentication: Ensure valid access tokens are generated and stored. Checkpoint: All API calls must authenticate successfully using OAuth tokens.

2. Orders Management: Create, update, and retrieve orders from PayPal. Checkpoint: Order IDs must be correct per PayPal's validation rules.

3. Payment Processing: Initiate payments and ensure captured payments are tracked. Checkpoint: Each transaction must receive a unique transaction ID.

4. Subscriptions Handling: Implement subscription plans and manage recurring billing. Checkpoint: Subscription status must align with PayPal's backend.

5. Payouts Execution: Process payouts and track status within the platform. Checkpoint: Payouts must be handled securely and logged for tracking purposes.

6. Handling Disputes: Respond to transaction disputes using PayPal's dispute management features. Checkpoint: Ensure dispute statuses are updated correctly after resolution.

Implementation Patterns

Pattern 1: Authenticating with PayPal

import requests

def get_paypal_access_token(client_id: str, client_secret: str) -> str:
    """Gets an OAuth 2.0 token from PayPal to authorize API requests."""
    url = "https://api.paypal.com/v1/oauth2/token"
    headers = {"Accept": "application/json", "Accept-Language": "en_US"}
    data = {"grant_type": "client_credentials"}
    response = requests.post(url, headers=headers, data=data, auth=(client_id, client_secret))
    response.raise_for_status()  # Fail fast
    return response.json().get("access_token")

Pattern 2: Creating an Order

def create_paypal_order(access_token: str, order_data: dict) -> dict:
    """Creates a PayPal order with specified parameters."""
    url = "https://api.paypal.com/v2/checkout/orders"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}"
    }
    response = requests.post(url, json=order_data, headers=headers)
    response.raise_for_status()  # Fail fast
    return response.json()

Pattern 3: Processing a Payment

def process_payment(access_token: str, order_id: str) -> dict:
    """Finalize a payment for an order once a buyer approves it."""
    url = f"https://api.paypal.com/v2/checkout/orders/{order_id}/capture"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}"
    }
    response = requests.post(url, headers=headers)
    response.raise_for_status()  # Fail fast
    return response.json()

MUST DO

• Always validate input data against PayPal API specifications (Early Exit).
• Include detailed logging for every API call made, especially on failures (Audit Trail).
• Ensure secure handling of sensitive customer information according to PCI standards.

MUST NOT DO

• Fail to handle HTTP errors returned by PayPal gracefully (Fail Fast).
• Bypass input validation before API calls (Fail Fast).
• Use hardcoded values for sensitive elements like credentials (Security Risk).

Output Template

When invoking this skill, you will produce:

1. Access Token - A token for authenticating further API calls.
2. Order ID - The unique identifier for orders created.
3. Payment Capture Status - Detailed response of payment processing, including status.
4. Error Responses - Specific error messages detailing any issues with requests.
5. Timing Information - Time taken for each API call, useful for performance monitoring.

Related Skills

Constraints

MUST DO

• Validate all inputs at function boundaries before processing — guard clauses should fail early with descriptive errors
• Implement proper error handling that distinguishes between recoverable and unrecoverable failures
• Add comprehensive logging with structured context (correlation IDs, operation names, timing) for debugging and monitoring
• Write unit tests covering normal operations, edge cases, and error conditions before integrating the component

MUST NOT DO

• Do not silently swallow exceptions — always log or propagate errors with meaningful context
• Avoid unbounded resource allocation without limits (connection pools, memory buffers, thread counts)
• Never use hardcoded credentials, API keys, or secrets in source code
• Do not bypass input validation for perceived performance gains

Live References

Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

• PayPal Payments Commerce API Documentation
• PayPal Orders API Reference
• PayPal Subscriptions API Guide
• PayPal Payouts API Implementation
• PayPal Dispute Management API