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.

PayPal Billing Agreements are equivalent to Stripe's Shared Payment Tokens for the ACP protocol. Both enable pre-authorized agent payments.

Setup

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# 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
 
WEBHOOKS
  Endpoint:         https://api.hyperfold.io/webhooks/paypal/xxx
  Events:           PAYMENT.*, BILLING.*
  Status:           active

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:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# PayPal Billing Agreements for agent commerce
 
# 1. Buyer sets up Billing Agreement (one-time authorization)
# This happens in the buyer's app, not during checkout
 
POST https://api.paypal.com/v1/billing-agreements/agreement-tokens
{
  "description": "Hyperfold Agent Purchases",
  "payer": {
    "payment_method": "PAYPAL"
  },
  "plan": {
    "type": "MERCHANT_INITIATED_BILLING",
    "merchant_preferences": {
      "return_url": "https://buyer-app.com/paypal/success",
      "cancel_url": "https://buyer-app.com/paypal/cancel"
    }
  }
}
 
# 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

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
# PayPal checkout in agent transactions
 
@OnACPEvent("checkout.finalize")
async handlePayPalCheckout(event: CheckoutEvent) {
  if (event.payment.method !== "paypal_ba") {
    return this.handleOtherPayment(event);
  }
 
  // Validate billing agreement
  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"
    };
  }
 
  // Create reference transaction
  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

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# 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
 
PAYPAL TRANSACTIONS (7 days)
 
DATE          ORDER           AMOUNT      STATUS
Jan 20        ord_123         $156.00     completed
Jan 19        ord_122         $89.50      completed
Jan 19        ord_121         $234.00     completed
Jan 18        ord_119         $45.00      refunded
Jan 18        ord_118         $312.00     completed
 
Summary:
  Total:        $1,247.50
  Refunds:      $45.00
  Net:          $1,202.50

Supported Currencies

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

PayPal Billing Agreements have daily and monthly limits set by PayPal based on merchant history. Monitor your limits in the PayPal dashboard.
For card payments, consider adding Stripe as an alternative payment method.