PayPal AI

https://docs.paypal.ai/
Admin
PayPal AI is a comprehensive platform that enables developers to build AI-powered commerce solutions...
Tokens:981,734
Snippets:5,584
Trust Score:8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install and Start Sample App

Source: https://docs.paypal.ai/payments/methods/cards/fastlane

Run these commands to install dependencies and start the sample application for Fastlane integration.

```bash
npm install
npm start
```

--------------------------------

### Create Setup Token Request

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

This example demonstrates the JSON payload required to create a setup token with card details and experience context. Ensure all required fields for the payment source and experience context are provided.

```json
{
  "payment_source": {
    "card": {
      "number": "4111111111111111",
      "expiry": "2027-02",
      "name": "John Doe",
      "billing_address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "17.3.160",
        "admin_area_1": "CA",
        "admin_area_2": "San Jose",
        "postal_code": "95131",
        "country_code": "US"
      },
      "experience_context": {
        "brand_name": "YourBrandName",
        "locale": "en-US",
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl"
      }
    }
  }
}
```

--------------------------------

### Setup Token Creation

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

This section details the structure and parameters required to create a setup token. It covers the request body and provides an example.

```APIDOC
## POST /v2/checkout/setup-tokens

### Description
Creates a setup token that is used to initiate a PayPal transaction.

### Method
POST

### Endpoint
/v2/checkout/setup-tokens

### Request Body
- **intent** (string) - Required - The intent of the transaction. Must be one of `CAPTURE`, `AUTHORIZE`, or `ORDER`.
- **purchase_units** (array) - Required - An array of purchase units, each representing a distinct part of the order.
  - **amount** (object) - Required - The amount of money for the transaction.
    - **currency_code** (string) - Required - The three-letter ISO-4217 currency code.
    - **value** (string) - Required - The amount of money, as a string, in the smallest currency unit. For example, to represent 10.00 USD, use "10.00".

### Request Example
```json
{
  "intent": "CAPTURE",
  "purchase_units": [
    {
      "amount": {
        "currency_code": "USD",
        "value": "10.00"
      }
    }
  ]
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the setup token.
- **href** (string) - The URL to the PayPal approval page.
- **expires_at** (string) - The date and time when the setup token expires.

#### Response Example
```json
{
  "id": "EC-1A2B3C4D5E6F7G8H",
  "href": "https://www.sandbox.paypal.com/checkoutnow?token=EC-1A2B3C4D5E6F7G8H",
  "expires_at": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Create Setup Token Response

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

This is an example of a successful response when creating a setup token. It includes the setup token ID, customer information, status, and details of the saved payment source. The response also contains links for further actions.

```json
{
  "id": "5C991763VB2781612",
  "customer": {
    "id": "customer_4029352050"
  },
  "status": "APPROVED",
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "expiry": "2027-02",
      "name": "John Doe",
      "billing_address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "17.3.160",
        "admin_area_1": "CA",
        "admin_area_2": "San Jose",
        "postal_code": "95131",
        "country_code": "US"
      }
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2781612",
      "method": "GET",
      "encType": "application/json"
    },
    {
      "rel": "confirm",
      "href": "https://api-m.paypal.com/v3/vault/payment-token",
      "method": "POST",
      "encType": "application/json"
    }
  ]
}
```

--------------------------------

### Start Server

Source: https://docs.paypal.ai/payments/methods/cards/standalone-payment-button

Start the server using npm. The application will be available at http://localhost:8080.

```bash
npm start
```

--------------------------------

### Install Server Dependencies

Source: https://docs.paypal.ai/payments/methods/cards/standalone-payment-button

Navigate to your demo directory and install server dependencies using npm.

```bash
npm install
```

--------------------------------

### Install Client Dependencies

Source: https://docs.paypal.ai/payments/methods/cards/standalone-payment-button

Navigate to the client components directory and install dependencies using npm.

```bash
cd client/components/paypalGuestPayments/html
npm install
```

--------------------------------

### Create Setup Token

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

Creates a setup token for storing payment instruments.

```APIDOC
## POST /v3/vault/setup-tokens

### Description
Creates a setup token that can be used to store payment instruments for future use.

### Method
POST

### Endpoint
/v3/vault/setup-tokens

### Parameters
#### Header Parameters
- **PayPal-Request-Id** (string) - Optional - The server stores keys for 3 hours.

### Request Body
- **payment_source** (object) - Required - The payment method to vault with the instrument details.
  - **card** (object) - Optional - Card details for vaulting.
  - **paypal** (object) - Optional - PayPal wallet details for vaulting.
  - **venmo** (object) - Optional - Venmo details for vaulting.
  - **token** (object) - Optional - Token ID for vaulting.

### Request Example
```json
{
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "expiry": "2027-02",
      "name": "John Doe",
      "billing_address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "17.3.160",
        "admin_area_1": "CA",
        "admin_area_2": "San Jose",
        "postal_code": "95131",
        "country_code": "US"
      }
    }
  }
}
```

### Response
#### Success Response (201)
- **id** (string) - The PayPal-generated ID for the vault token.
- **customer** (object) - Customer details.
- **status** (string) - The status of the payment token.
- **payment_source** (object) - The setup payment method details.
  - **card** (object) - Card details.
    - **last_digits** (string) - The last four digits of the card.
    - **expiry** (string) - The expiration date of the card (YYYY-MM).
    - **name** (string) - The name of the cardholder.
    - **billing_address** (object) - The billing address associated with the card.
      - **address_line_1** (string) - The first line of the address.
      - **address_line_2** (string) - The second line of the address.
      - **admin_area_1** (string) - The state or province.
      - **admin_area_2** (string) - The city or locality.
      - **postal_code** (string) - The postal code.
      - **country_code** (string) - The two-letter ISO 3166-1 country code.

#### Response Example
```json
{
  "id": "5C991763VB2781612",
  "customer": {
    "id": "customer_4029352050"
  },
  "status": "APPROVED",
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "expiry": "2027-02",
      "name": "John Doe",
      "billing_address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "17.3.160",
        "admin_area_1": "CA",
        "admin_area_2": "San Jose",
        "postal_code": "95131",
        "country_code": "US"
      }
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2781612",
      "method": "GET",
      "encType": "application/json"
    },
    {
      "rel": "confirm",
      "href": "https://api-m.paypal.com/v3/vault/payment-token",
      "method": "POST",
      "encType": "application/json"
    }
  ]
}
```

### Error Handling
- **400**: Request is not well-formed, syntactically incorrect, or violates schema.
- **403**: Authorization failed due to insufficient permissions.
- **422**: The requested action could not be performed, semantically incorrect, or failed business validation.
- **500**: An internal server error has occurred.
```

--------------------------------

### FTP or SFTP Feed Example

Source: https://docs.paypal.ai/growth/agentic-commerce/store-sync/product-catalog/connect-product-feed

Example of FTP/SFTP credentials including feed URL, port, username, and password for product feed ingestion.

```text
Feed URL: ftp://products.domain.com/merchant/merchantFeed.csv.gz
Port: 21
Username: feeduser
Password: feedpassword
```

--------------------------------

### Create a setup token

Source: https://docs.paypal.ai/llms.txt

Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer.

```APIDOC
## POST /v1/setup-tokens

### Description
Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer.

### Method
POST

### Endpoint
/v1/setup-tokens

### Parameters
#### Request Body
- **payment_source** (object) - Required - The source of the payment.
- **customer_id** (string) - Optional - The ID of the customer associated with the token.

### Response
#### Success Response (201 Created)
- **setup_token** (string) - The created setup token.
- **vault_id** (string) - The ID of the vault where the payment source is stored.
```

--------------------------------

### Create Setup Token

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

This endpoint allows you to create a setup token. Setup tokens are used to initiate payment flows and can be used to create billing agreements.

```APIDOC
## POST /v1/setup-tokens

### Description
Creates a setup token that can be used to initiate a payment flow or create a billing agreement.

### Method
POST

### Endpoint
/v1/setup-tokens

### Request Body
- **payment_method_config** (object) - Required - Configuration for the payment method.
  - **return_url** (string) - Required - The URL to redirect the user to after the setup is complete.
  - **payment_source** (object) - Required - Details about the payment source.
    - **card** (object) - Required - Card details.
      - **vault_id** (string) - Required - The ID of the stored card.

### Response
#### Success Response (201)
- **setup_token** (string) - The created setup token.
- **expires_in** (integer) - The time in seconds until the setup token expires.

#### Response Example
```json
{
  "setup_token": "st-xxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_in": 3600
}
```
```

--------------------------------

### Start Payment Session with Options

Source: https://docs.paypal.ai/payments/methods/cards/standalone-payment-button

Starts a PayPal payment session using the `start` method, configuring presentation mode and an optional target element for the checkout button.

```javascript
const startOptions = {
  presentationMode: "auto", // "auto", "modal", "popup", or "redirect"
  targetElement: checkoutButton, // Optional: element to attach to
};

await paypalGuestPaymentSession.start(startOptions, createOrder());
```

--------------------------------

### Setup Token Object Structure

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

This details the structure of a setup token object, including its ID, type, and status.

```APIDOC
## Setup Token Object

The setup token, which is a temporary reference to payment source.

### Properties

- **id** (string) - Required - The unique identifier for the setup token.
- **type** (string) - Required - The type of the setup token. Enum: `SETUP_TOKEN`
- **vault_id** (string) - Optional - The PayPal-generated ID for the vault token. MinLength: 1, MaxLength: 36, Pattern: `^[0-9a-zA-Z_-]+$`
- **payment_token_status** (string) - Optional - The status of the payment token. Default: `CREATED`. Enum: `CREATED`, `PAYER_ACTION_REQUIRED`, `APPROVED`, `VAULTED`, `TOKENIZED`
  - `CREATED`: A setup token is initialized with minimal information; more data must be added to the setup-token to be vaulted.
  - `PAYER_ACTION_REQUIRED`: A contingency on payer approval is required before the payment method can be saved.
  - `APPROVED`: Setup token is ready to be vaulted. If a buyer approval contingency was returned, it has been approved.
  - `VAULTED`: The payment token has been vaulted.
  - `TOKENIZED`: A vaulted payment method token has been tokenized for short-term (one-time) use.

### Card Response Entity

Full representation of a Card Payment Token.

#### Properties

- **name** (string) - Optional - The card holder's name as it appears on the card. MinLength: 2, MaxLength: 300, Pattern: `^[A-Za-z ]+$`
- **last_digits** (string) - Optional - The last digits of the payment card. Pattern: `[0-9]{2,}`, MinLength: 2, MaxLength: 4, ReadOnly: true
- **brand** (string) - Optional - The card brand or network. Typically used in the response. ReadOnly: true
- **expiry** (string) - Optional - The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).
- **billing_address** - Optional - Billing address details.
- **verification_status** - Optional - Card Verification status.
- **verification** - Optional - Card verification details.
- **network_transaction_reference** - Optional - Network transaction reference details.
- **authentication_result** - Optional - Authentication result details.
- **bin_details** - Optional - Bank Identification Number (BIN) details used to fund a payment.
- **type** - Optional - The payment card type.

### PayPal Wallet Response

Resource consolidating common request and response attributes for vaulting a Digital Wallet.

#### Properties

- **name** - Optional - Name details.
- **phone** - Optional - Phone number details. Available only when the **Contact Telephone Number** option is enabled in the Profile & Settings for the merchant's PayPal account. The `phone.phone_number` supports only `national_number`.
- **account_id** (string) - Optional - The account identifier for a PayPal account. ReadOnly: true
- **phone_number** - Optional - Phone number details.
```

--------------------------------

### Setup Token Creation

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

This section details the structure for creating a setup token, including address, phone number, and billing cycle information.

```APIDOC
## POST /v1/checkout/setup-tokens

### Description
Creates a setup token that can be used to initiate a PayPal checkout flow. This token encapsulates details about the transaction, including shipping and billing information.

### Method
POST

### Endpoint
/v1/checkout/setup-tokens

### Request Body
- **shipping_name** (object) - Optional - The name of the party for shipping.
  - **full_name** (string) - Required - When the party is a person, the party's full name. Max length: 300.
- **shipping_phone_number** (object) - Optional - The phone number for shipping in E.164 format.
  - **country_code** (string) - Required - The country calling code. Min length: 1, Max length: 3.
  - **national_number** (string) - Required - The national number. Min length: 1, Max length: 14.
- **shipping_address** (object) - Optional - The portable international postal address for shipping.
  - **address_line_1** (string) - Required - The first line of the address. Max length: 300.
  - **address_line_2** (string) - Optional - The second line of the address. Max length: 300.
  - **admin_area_2** (string) - Optional - A city, town, or village. Max length: 120.
  - **admin_area_1** (string) - Optional - The highest-level sub-division (e.g., state, province). Max length: 300.
  - **postal_code** (string) - Optional - The postal code. Max length: 60.
  - **country_code** (string) - Required - The ISO 3166-1 alpha-2 country code.
- **billing_cycle** (object) - Optional - Details of the billing cycle.
  - **tenure_type** (string) - Required - The tenure type of the billing cycle (e.g., REGULAR, TRIAL). Min length: 1, Max length: 24.

### Request Example
```json
{
  "shipping_name": {
    "full_name": "Jane Doe"
  },
  "shipping_phone_number": {
    "country_code": "1",
    "national_number": "4085551234"
  },
  "shipping_address": {
    "address_line_1": "123 Main St",
    "admin_area_2": "San Jose",
    "admin_area_1": "CA",
    "postal_code": "95131",
    "country_code": "US"
  },
  "billing_cycle": {
    "tenure_type": "REGULAR"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the setup token.
- **links** (array) - An array of request-related HATEOAS links.
  - **href** (string) - The URL of the link.
  - **rel** (string) - The relationship of the link (e.g., 'approve', 'cancel').
  - **method** (string) - The HTTP method for the link.

#### Response Example
```json
{
  "id": "TOKEN-12345",
  "links": [
    {
      "href": "https://www.paypal.com/checkoutnow?token=TOKEN-12345",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://www.paypal.com/checkoutcancel?token=TOKEN-12345",
      "rel": "cancel",
      "method": "GET"
    }
  ]
}
```
```

--------------------------------

### Create Setup Token

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

This endpoint is used to create a setup token. It requires specific parameters related to pricing, dates, and authentication status.

```APIDOC
## POST /v1/setup-tokens

### Description
Creates a setup token for PayPal integrations.

### Method
POST

### Endpoint
/v1/setup-tokens

### Parameters
#### Request Body
- **frequency** (object) - Optional - Frequency details.
- **date_no_time** (string) - Optional - The stand-alone date in Internet date and time format (YYYY-MM-DD).
- **pares_status** (string) - Optional - Transactions status result identifier.
- **enrolled** (string) - Optional - Status of Authentication eligibility.

### Request Example
{
  "frequency": {},
  "date_no_time": "2023-10-27",
  "pares_status": "Y",
  "enrolled": "Y"
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the setup token.
- **expires_at** (string) - The expiration date and time of the setup token.

#### Response Example
{
  "id": "st-12345",
  "expires_at": "2023-10-27T10:00:00Z"
}

### Security
This endpoint uses OAuth 2.0 authentication. The following scopes are available:
- `https://uri.paypal.com/services/vault/payment-tokens/readwrite`
- `https://uri.paypal.com/services/vault/payment-tokens/read`
- `https://uri.paypal.com/services/vault/customers/read`
- `https://uri.paypal.com/services/vault/customers/readwrite`
```

--------------------------------

### Create Setup Token

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

Creates a setup token that can be used to tokenize payment information. This is the first step in a multi-step process to tokenize payment details.

```APIDOC
## POST /v1/setup-tokens

### Description
Creates a setup token that can be used to tokenize payment information. This is the first step in a multi-step process to tokenize payment details.

### Method
POST

### Endpoint
/v1/setup-tokens

### Request Body
- **payment_source** (object) - Required - The payment source to tokenize. Supports `card` and `token` types.
  - **card** (object) - Required if `token` is not provided - The card details.
    - **number** (string) - Required - The primary account number (PAN) of the card.
    - **expire_year** (string) - Required - The expiration year of the card (4 digits).
    - **expire_month** (string) - Required - The expiration month of the card (2 digits).
    - **cvv** (string) - Optional - The card verification value (CVV).
    - **billing_address** (object) - Optional - The billing address for the card.
      - **street_address** (string) - Required - The street address.
      - **address_2** (string) - Optional - The second line of the street address.
      - **country_code** (string) - Required - The 2-character ISO 3166-1 code for the country.
      - **state** (string) - Required - The state or province.
      - **city** (string) - Required - The city.
      - **postal_code** (string) - Required - The postal code.
  - **token** (object) - Required if `card` is not provided - The existing token details.
    - **id** (string) - Required - The ID of the existing token.

### Request Example
```json
{
  "payment_source": {
    "card": {
      "number": "4111111111111111",
      "expire_year": "2025",
      "expire_month": "12",
      "billing_address": {
        "street_address": "123 Main St",
        "country_code": "US",
        "state": "CA",
        "city": "San Jose",
        "postal_code": "95131"
      }
    }
  }
}
```

### Response
#### Success Response (201)
- **id** (string) - The ID of the setup token.
- **create_time** (string) - The date and time when the setup token was created.
- **update_time** (string) - The date and time when the setup token was last updated.
- **links** (array) - An array of HATEOAS links related to the setup token.
  - **href** (string) - The complete target URL.
  - **rel** (string) - The link relation type.
  - **method** (string) - The HTTP method for the link.

#### Response Example
```json
{
  "id": "st-12345",
  "create_time": "2023-10-27T10:00:00Z",
  "update_time": "2023-10-27T10:00:00Z",
  "links": [
    {
      "href": "https://api.example.com/v1/setup-tokens/st-12345",
      "rel": "self",
      "method": "GET"
    }
  ]
}
```
```

--------------------------------

### Install Vercel AI SDK

Source: https://docs.paypal.ai/developer/tools/ai/agent-toolkit-quickstart

Install the Vercel AI SDK and the OpenAI integration package using npm.

```bash
npm install ai @ai-sdk/openai
```

--------------------------------

### Install Project Dependencies

Source: https://docs.paypal.ai/payments/methods/digital-wallets/google-pay

Navigate to the Google Pay payment component directory and install the necessary project dependencies using npm.

```bash
cd client/components/googlePayPayments/oneTimePayment/html
npm install
```

--------------------------------

### Retrieve a Setup Token

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/retrieve-a-setup-token

This API allows you to retrieve a setup token. This token is used for future transactions directly with a merchant or on a platform.

```APIDOC
## GET /v1/identity/setup-tokens

### Description
Retrieves a setup token that can be used for future transactions.

### Method
GET

### Endpoint
/v1/identity/setup-tokens

### Parameters
#### Query Parameters
- **customer_type** (string) - Required - The customer type associated with a digital wallet payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer.
  - enum: CONSUMER, BUSINESS
- **return_url** (string) - Required - The URL to which the user will be redirected after the setup is complete.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the setup token.
- **expires_at** (string) - The date and time when the setup token expires, in ISO 4217 format.
- **links** (array) - A list of links related to the setup token.
  - **href** (string) - The URL of the link.
  - **rel** (string) - The relationship of the link (e.g., 'approve', 'cancel').
  - **method** (string) - The HTTP method for the link (e.g., 'GET').

#### Response Example
```json
{
  "id": "TOKEN_ID",
  "expires_at": "2023-10-27T10:00:00Z",
  "links": [
    {
      "href": "https://www.paypal.com/checkout?token=TOKEN_ID",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://www.example.com/cancel",
      "rel": "cancel",
      "method": "GET"
    }
  ]
}
```
```

--------------------------------

### Retrieve Setup Token Details

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/retrieve-a-setup-token

Retrieves the details of a specific setup token. This includes information about the payment method, customer, and the token's status.

```APIDOC
## GET /v1/setup_tokens/{id}

### Description
Retrieves the details of a specific setup token. This includes information about the payment method, customer, and the token's status.

### Method
GET

### Endpoint
/v1/setup_tokens/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the setup token to retrieve.

### Response
#### Success Response (200)
- **vault_id** (string) - The PayPal-generated ID for the vault token.
- **customer** (object) - Customer details.
  - **id** (string) - The unique ID for a customer in merchant's or partner's system.
  - **merchant_customer_id** (string) - Association to your representation of a customer.
- **payment_token_status** (string) - The status of the payment token.
- **card_response_entity** (object) - Full representation of a Card Payment Token.
  - **name** (string) - The card holder's name.
  - **last_digits** (string) - The last digits of the payment card.
  - **brand** (string) - The card brand or network.
  - **expiry** (string) - The card expiration year and month.
  - **billing_address** (object) - Billing address details.
  - **verification_status** (string) - Card Verification status.
  - **type** (string) - The card type.
- **paypal** (object) - PayPal wallet details.
- **venmo** (object) - Venmo response details.

#### Response Example
{
  "vault_id": "YOUR_VAULT_ID",
  "customer": {
    "id": "YOUR_CUSTOMER_ID",
    "merchant_customer_id": "YOUR_MERCHANT_CUSTOMER_ID"
  },
  "payment_token_status": "VAULTED",
  "card_response_entity": {
    "name": "JOHN DOE",
    "last_digits": "1111",
    "brand": "VISA",
    "expiry": "2025-12",
    "billing_address": {},
    "verification_status": "SUCCESS",
    "type": "CREDIT"
  },
  "paypal": {},
  "venmo": {}
}

### Error Handling
#### Error Response (400 or 404)
- **name** (string) - The human-readable, unique name of the error.
- **message** (string) - The message that describes the error.
- **debug_id** (string) - The PayPal internal ID. Used for correlation purposes.
- **details** (array) - Detailed error information.
- **links** (array) - Links to error definitions.
```

--------------------------------

### Ruby Project Setup

Source: https://docs.paypal.ai/payments/methods/paypal/integrate

Initializes a Ruby project with Sinatra, PayPal SDK, and dotenv for environment variables.

```bash
# Create project structure
mkdir paypal-minimal && cd paypal-minimal
bundle init

# Add gems to Gemfile
cat >> Gemfile << 'EOF'
gem 'sinatra'
gem 'paypal-checkout-sdk'
gem 'dotenv'
EOF

bundle install
mkdir public

# Create .env file with development defaults
cat > .env << 'EOF'
# Development/Sandbox Configuration (Default)
# ==========================================
PAYPAL_CLIENT_ID=your_sandbox_client_id
PAYPAL_CLIENT_SECRET=your_sandbox_secret
RACK_ENV=development
PORT=3000

# Negative Testing (Sandbox Only)
# --------------------------------
# Set to true to enable error simulation in sandbox
ENABLE_NEGATIVE_TESTING=false
NEGATIVE_TEST_TYPE=INSUFFICIENT_FUNDS
# Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
# INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

# Production Configuration (Uncomment to use)
# ==========================================
# PAYPAL_CLIENT_ID=your_production_client_id
# PAYPAL_CLIENT_SECRET=your_production_secret
# RACK_ENV=production
# PORT=3000
EOF

# Create empty files
touch app.rb
touch public/index.html

echo "✅ Project structure created! Now copy the code below into the files."
```

--------------------------------

### Retrieve a Setup Token

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/retrieve-a-setup-token

Use this endpoint to get a readable representation of a temporarily vaulted payment source associated with the setup token ID. Ensure you have the necessary OAuth 2.0 scope for reading payment tokens.

```shell
curl -v -X GET https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/{id} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access Token>"
```

--------------------------------

### Get Payment Resource Details Response

Source: https://docs.paypal.ai/payments/pay-links-buttons-api

Example JSON response for a specific payment resource, detailing its properties and associated links.

```json
{
  "id": "PLB-X7MNK9P2QR8T",
  "integration_mode": "LINK",
  "create_time": "2025-11-29T13:13:25.832592Z",
  "status": "ACTIVE",
  "payment_link": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
  "type": "BUY_NOW",
  "reusable": "MULTIPLE",
  "return_url": "https://merchant.example.com/thank-you",
  "line_items": [
    {
      "name": "Wireless Mouse",
      "unit_amount": {
        "currency_code": "USD",
        "value": "29.99"
      }
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
      "rel": "payment_link",
      "method": "GET"
    }
  ]
}
```

--------------------------------

### Run Local Server

Source: https://docs.paypal.ai/payments/methods/paypal/integrate

This bash command starts the local development server for your application. Ensure you have Node.js installed and have configured your environment variables.

```bash
node server.js
```

--------------------------------

### Java Project Setup with Maven

Source: https://docs.paypal.ai/payments/methods/paypal/integrate

Sets up a basic Maven project for a Spring Boot application. Includes a pom.xml with necessary dependencies for Spring Web and PayPal Checkout SDK.

```bash
# Create Maven project structure
mkdir paypal-minimal && cd paypal-minimal
mkdir -p src/main/java/com/paypal/demo
mkdir -p src/main/resources
mkdir -p src/main/resources/static

# Create pom.xml with dependencies
cat > pom.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.paypal</groupId>
    <artifactId>paypal-minimal</artifactId>
    <version>1.0.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.0</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.paypal.sdk</groupId>
            <artifactId>checkout-sdk</artifactId>
            <version>1.0.5</version>
        </dependency>
    </dependencies>
</project>
EOF

# Create application.properties
cat > src/main/resources/application.properties << 'EOF'

```

--------------------------------

### Express Server Setup for PayPal Integration

Source: https://docs.paypal.ai/payments/save/sdk/paypal/js-sdk-v6-vault-w-purchase

Basic Express server configuration including JSON parsing and static file serving. This setup is required for handling API requests related to PayPal transactions. Ensure `dotenv` is installed and configured to load environment variables.

```javascript
const express = require("express");
const path = require("path");
require("dotenv").config();

const app = express();
app.use(express.json());
app.use(express.static(path.join(__dirname, "public")));

// ... route handlers below ...

app.listen(process.env.PORT || 3000, () => {
  console.log(`Server running on port ${process.env.PORT || 3000}`);
});
```

--------------------------------

### PHP Project Setup

Source: https://docs.paypal.ai/payments/methods/paypal/integrate

Sets up a PHP project with PayPal SDK and dotenv for configuration.

```bash
# Create project structure
mkdir paypal-minimal && cd paypal-minimal
composer init -n
composer require paypal/paypal-checkout-sdk vlucas/phpdotenv
mkdir public

# Create .env file with development defaults
cat > .env << 'EOF'
# Development/Sandbox Configuration (Default)
# ==========================================
PAYPAL_CLIENT_ID=your_sandbox_client_id
PAYPAL_CLIENT_SECRET=your_sandbox_secret
APP_ENV=development
PORT=3000

# Negative Testing (Sandbox Only)
# --------------------------------
# Set to true to enable error simulation in sandbox
ENABLE_NEGATIVE_TESTING=false
NEGATIVE_TEST_TYPE=INSUFFICIENT_FUNDS
# Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
# INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

# Production Configuration (Uncomment to use)
# ==========================================
# PAYPAL_CLIENT_ID=your_production_client_id
# PAYPAL_CLIENT_SECRET=your_production_secret
# APP_ENV=production
# PORT=3000
EOF

# Create empty files
touch index.php
touch public/index.html

echo "✅ Project structure created! Now copy the code below into the files."
```

--------------------------------

### Use PayPal Toolkit with AI SDK

Source: https://docs.paypal.ai/developer/tools/ai/agent-toolkit-quickstart

Generate text using the AI SDK, incorporating the PayPal Agent Toolkit's functions and other tools. This example demonstrates creating an order and getting a payment link.

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

--------------------------------

### Java Project Setup

Source: https://docs.paypal.ai/payments/methods/paypal/integrate

Creates the necessary Java project structure for PayPal integration.

```bash
# Create empty Java files
touch src/main/java/com/paypal/demo/PayPalController.java
touch src/main/java/com/paypal/demo/Application.java
touch src/main/resources/static/index.html

echo "✅ Project structure created! Now copy the code below into the files."
```

--------------------------------

### Find Eligible Payment Methods - Exclude Payment Sources

Source: https://docs.paypal.ai/reference/api/rest/find-eligible-methods/find-a-list-of-eligible-payment-methods

Use this example to find eligible payment methods while excluding specific payment sources like PAYPAL. This is useful when you want to guide users towards alternative payment options.

```json
{
  "customer": {
    "country_code": "US",
    "channel": {
      "browser_type": "SAFARI",
      "device_type": "MOBILE",
      "client_os": "IOS"
    }
  },
  "purchase_units": [
    {
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ],
  "preferences": {
    "payment_source_constraint": {
      "constraint_type": "EXCLUDE",
      "payment_sources": [
        "PAYPAL"
      ]
    }
  }
}
```

--------------------------------

### Create Setup Token

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

This endpoint allows you to create a new setup token. Setup tokens are used to initiate specific PayPal flows.

```APIDOC
## POST /v1/identity/setup-tokens

### Description
Creates a setup token that can be used to initiate a PayPal identity or payment flow.

### Method
POST

### Endpoint
/v1/identity/setup-tokens

### Request Body
- **customer_type** (string) - Required - The type of customer for whom the token is being created. Supported values are `MERCHANT` and `BUYER`.
- **return_url** (string) - Required - The URL to which the user will be redirected after completing the PayPal flow.
- **identity_options** (array) - Optional - An array of strings specifying the identity options to be requested. Supported values include `EMAIL`, `PHONE`, `NAME`, `DOB`, `ADDRESS`, `NATIONAL_ID`, `EXT_LOCAL_ID`, `ARTICLE_NUMBER`, `ACCOUNT_NUMBER`, `TAX_ID`, `PAYPAL_USER_ID`.
- **partner_config_override** (object) - Optional - An object to override partner configuration settings.
  - **return_url_hard_expiry** (string) - Optional - The hard expiry time for the return URL in ISO 7186 format.
- **merchant_id** (string) - Optional - The ID of the merchant for whom the token is being created. This is required if `customer_type` is `MERCHANT`.

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the setup token.
- **href** (string) - The URL to which the user should be redirected to complete the flow.
- **expires_in** (integer) - The time in seconds until the setup token expires.
- **nonce** (string) - A unique nonce value used for security purposes.

#### Response Example
```json
{
  "id": "AABC123XYZ",
  "href": "https://www.paypal.com/checkout/identity/AABC123XYZ",
  "expires_in": 1800,
  "nonce": "some_random_string"
}
```
```

--------------------------------

### Retrieve Setup Token

Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/retrieve-a-setup-token

This endpoint allows you to retrieve a setup token. Setup tokens are used to initiate payment flows and are typically short-lived.

```APIDOC
## GET /v1/setup_tokens

### Description
Retrieves a setup token that can be used to initiate a payment.

### Method
GET

### Endpoint
/v1/setup_tokens

### Parameters
#### Query Parameters
- **merchant_id** (string) - Required - The ID of the merchant for whom the token is being generated.
- **return_url** (string) - Required - The URL to which the user will be redirected after the payment process is complete.

### Response
#### Success Response (200)
- **setup_token** (string) - The generated setup token.
- **expires_in** (integer) - The time in seconds until the setup token expires.

#### Response Example
```json
{
  "setup_token": "a1b2c3d4e5f67890",
  "expires_in": 1800
}
```
```

--------------------------------

### Setup and Initialize PayPal Toolkit with LangChain

Source: https://docs.paypal.ai/developer/tools/ai/agent-toolkit-quickstart

Configure and build the PayPal Toolkit for use with LangChain. This involves setting up the OpenAI LLM, PayPal configuration, and retrieving the available tools.

```python
import os
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI 

from dotenv import load_dotenv

from paypal_agent_toolkit.langchain.toolkit import PayPalToolkit
from paypal_agent_toolkit.shared.configuration import Configuration, Context

#uncomment after setting the env file
# load_dotenv()
PAYPAL_CLIENT_ID = os.getenv("YOUR_PAYPAL_CLIENT_ID")
PAYPAL_CLIENT_SECRET = os.getenv("YOUR_PAYPAL_CLIENT_SECRET")
OPENAI_API_VERSION = "2024-02-15-preview"


# --- STEP 1: Setup OpenAI LLM ---
llm = ChatOpenAI(
    temperature=0.3,
    model="gpt-4o",  # or "gpt-3.5-turbo"
)


# --- STEP 2: Setup PayPal Configuration ---
configuration = Configuration(
    actions={
        "orders": {
            "create": True,
            "get": True,
            "capture": True,
        }
    },
    context=Context(
        sandbox=True
    )
)


# --- STEP 3: Build PayPal Toolkit ---
toolkit = PayPalToolkit(client_id=PAYPAL_CLIENT_ID, secret=PAYPAL_CLIENT_SECRET, configuration = configuration)
tools = toolkit.get_tools()
```

--------------------------------

### Node.js Project Setup

Source: https://docs.paypal.ai/payments/methods/paypal/integrate

Sets up a Node.js project with Express, PayPal SDK, and dotenv. Creates a .env file for configuration and empty server.js and index.html files.

```bash
# Create project structure
mkdir paypal-minimal && cd paypal-minimal
npm init -y
npm install express @paypal/checkout-server-sdk dotenv
mkdir public

# Create .env file with development defaults
cat > .env << 'EOF'
# Development/Sandbox Configuration (Default)
# ==========================================
PAYPAL_CLIENT_ID=your_sandbox_client_id
PAYPAL_CLIENT_SECRET=your_sandbox_secret
NODE_ENV=development
PORT=3000

# Negative Testing (Sandbox Only)
# --------------------------------
# Set to true to enable error simulation in sandbox
ENABLE_NEGATIVE_TESTING=false
NEGATIVE_TEST_TYPE=INSUFFICIENT_FUNDS
# Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
# INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

# Production Configuration (Uncomment to use)
# ==========================================
# PAYPAL_CLIENT_ID=your_production_client_id
# PAYPAL_CLIENT_SECRET=your_production_secret
# NODE_ENV=production
# PORT=3000
EOF

# Create empty files
touch server.js
touch public/index.html

echo "✅ Project structure created! Now copy the code below into the files."
```

--------------------------------

### Initialize PayPal SDK Instance

Source: https://docs.paypal.ai/payments/methods/pay-later/get-started

Create an instance of the PayPal SDK by providing necessary configuration options. Ensure you have a valid client ID or client token.

```javascript
const sdkInstance = await window.paypal.createInstance({
  // SDK Instance Options
});
```

--------------------------------

### Bearer Authorization Example

Source: https://docs.paypal.ai/reference/api/rest/externalcallback/receive-updated-order-information-via-callback-url

This example demonstrates how to use Bearer authorization for external API calls.

```http
Authorization: Bearer <ACCESS_TOKEN>
```

--------------------------------

### Python Project Setup

Source: https://docs.paypal.ai/payments/methods/paypal/integrate

Sets up a Python project with Flask, PayPal SDK, and python-dotenv. Creates a .env file for configuration and empty app.py and index.html files.

```bash
# Create project structure
mkdir paypal-minimal && cd paypal-minimal
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install flask paypalrestsdk python-dotenv
mkdir templates static

# Create .env file with development defaults
cat > .env << 'EOF'
# Development/Sandbox Configuration (Default)
# ==========================================
PAYPAL_CLIENT_ID=your_sandbox_client_id
PAYPAL_CLIENT_SECRET=your_sandbox_secret
FLASK_ENV=development
PORT=3000

# Negative Testing (Sandbox Only)
# --------------------------------
# Set to true to enable error simulation in sandbox
ENABLE_NEGATIVE_TESTING=false
NEGATIVE_TEST_TYPE=INSUFFICIENT_FUNDS
# Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
# INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

# Production Configuration (Uncomment to use)
# ==========================================
# PAYPAL_CLIENT_ID=your_production_client_id
# PAYPAL_CLIENT_SECRET=your_production_secret
# FLASK_ENV=production
# PORT=3000
EOF

# Create requirements.txt
cat > requirements.txt << 'EOF'
flask
paypalrestsdk
python-dotenv
EOF

# Create empty files
touch app.py
touch templates/index.html

echo "✅ Project structure created! Now copy the code below into the files."
```

--------------------------------

### Public URL Feed Example

Source: https://docs.paypal.ai/growth/agentic-commerce/store-sync/product-catalog/connect-product-feed

Example of a public URL and authentication credentials for product feed ingestion.

```text
Feed URL: https://www.merchantname.com/productCatalog.csv
Auth (if required): feeduser:feedpassword
```
Tokens:
Raw