Hyperfold AI

PayPal Integration

Enable PayPal payments with Billing Agreements for agent commerce.

Overview

The PayPal integration enables buyers to use their PayPal accounts for agent-mediated purchases. Using Billing Agreements, buyers pre-authorize agents to charge their PayPal account without requiring authentication for each transaction.

Setup

# Connect PayPal
$ hyperfold integrate add paypal
Enter your PayPal Client ID: xxx
Enter your PayPal Client Secret: xxx
Testing connection...
✓ Connected to PayPal (Live Mode)
PAYPAL CONNECTED
  Merchant ID:      MERCHANT123
  Mode:             live
  Capabilities:     payments, billing_agreements, refunds
# View connection status
$ hyperfold integrate show paypal
INTEGRATION: PayPal
Merchant ID:        MERCHANT123
Business:           Acme Sports Inc.
Mode:               live
Status:             active
CAPABILITIES
  ✓ PayPal Checkout
  ✓ Billing Agreements
  ✓ Refunds
  ✓ Disputes API

Prerequisites

  • PayPal Business account
  • REST API credentials (Client ID and Secret)
  • Billing Agreements enabled (contact PayPal support if needed)

Billing Agreements

Billing Agreements allow agents to charge PayPal accounts without per-transaction authentication:

# 1. Buyer sets up Billing Agreement (one-time authorization) - in buyer's app
# 2. User approves in PayPal, buyer stores agreement_id
# Agreement ID: BA-1AB23456CD789012E
# 3. During ACP checkout, buyer sends Billing Agreement reference

POST /acp/checkout/finalize
{
  "checkout_id": "chk_xyz789",
  "payment": {
    "method": "paypal_ba",
    "billing_agreement_id": "BA-1AB23456CD789012E"
  }
}

# 4. Hyperfold charges against the Billing Agreement
# No additional user authentication required

Agreement Lifecycle

StatusDescription
ACTIVEReady for reference transactions
SUSPENDEDTemporarily disabled by user
CANCELLEDPermanently cancelled

Checkout Flow

# PayPal checkout in agent transactions
@OnACPEvent("checkout.finalize")
async handlePayPalCheckout(event: CheckoutEvent) {
  if (event.payment.method !== "paypal_ba") {
    return this.handleOtherPayment(event);
  }
  const ba = await this.tools.payments.validateBillingAgreement(
    event.payment.billing_agreement_id
  );
  if (!ba.valid || ba.status !== "ACTIVE") {
    return {
      status: "payment_failed",
      error: "Invalid or inactive billing agreement"
    };
  }
  const payment = await this.tools.payments.charge({
    provider: "paypal",
    billing_agreement_id: event.payment.billing_agreement_id,
    amount: event.total,
    currency: "USD",
    description: `Order ${event.order_id} from Acme Sports`,
    metadata: {
      order_id: event.order_id,
      session_id: event.session_id
    }
  });
  if (payment.status === "COMPLETED") {
    return {
      status: "success",
      order_id: event.order_id,
      payment_id: payment.id
    };
  }
  return {
    status: "payment_failed",
    error: payment.error_description
  };
}

Configuration

# Configure PayPal settings
$ hyperfold integrate config paypal \
  --mode=live \
  --currency=USD \
  --brand-name="Acme Sports" \
  --logo-url="https://cdn.acme.com/logo.png"
# Enable additional features
$ hyperfold integrate config paypal \
  --enable-seller-protection \
  --enable-risk-assessment \
  --dispute-auto-response=true
# Set transaction limits for agents
$ hyperfold pay delegate \
  --agent=sales-negotiator \
  --provider=paypal \
  --max-transaction=500 \
  --daily-limit=5000
# View PayPal transaction history
$ hyperfold pay transactions --provider=paypal --since=7d

Supported Currencies

PayPal supports transactions in: USD, EUR, GBP, CAD, AUD, and 20+ additional currencies. Currency conversion is handled automatically by PayPal.