### Install and Start Sample App

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

Commands to install dependencies and start the sample application for Fastlane integration. Ensure a backend server is running at http://localhost:8080.

```bash
npm install
npm start
```

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

### Install and Configure ngrok

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

Install ngrok globally and configure your authentication token. Then, start an HTTP tunnel to your local development server.

```bash
npm install -g ngrok
ngrok config add-authtoken YOUR_AUTHTOKEN
ngrok http 3000
```

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

### Create Setup Token Request

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

This example shows the JSON payload for creating a setup token with card details and experience context. Ensure you provide valid payment source information and desired return/cancel URLs.

```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 with 3D Secure

Source: https://docs.paypal.ai/payments/save/api/vault-api-integration-test

This example demonstrates how to create a setup token for a card payment source, incorporating 3D Secure verification. It includes instructions for setting up access tokens, request IDs, and configuring verification methods and return/cancel URLs.

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

### Description
Creates a setup token for a payment source, enabling 3D Secure authentication for enhanced security and fraud reduction. This is particularly useful in regions like PSD2 countries where Strong Customer Authentication (SCA) is mandated.

### Method
POST

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

### Parameters
#### Request Body
- **payment_source** (object) - Required - The payment source details.
  - **card** (object) - Required - Card payment details.
    - **number** (string) - Required - The primary account number (PAN) of the card.
    - **expiry** (string) - Required - The expiration date of the card in 'YYYY-MM' format.
    - **name** (string) - Required - The full name of the cardholder.
    - **billing_address** (object) - Required - The billing address associated with the card.
      - **address_line_1** (string) - Required - The first line of the street address.
      - **address_line_2** (string) - Optional - The second line of the street address.
      - **admin_area_1** (string) - Required - The state or province.
      - **admin_area_2** (string) - Required - The city or locality.
      - **postal_code** (string) - Required - The postal code.
      - **country_code** (string) - Required - The two-letter ISO 3166-1 country code.
    - **verification_method** (string) - Required - Specifies the 3D Secure verification method. Use `SCA_ALWAYS` or `SCA_WHEN_REQUIRED`.
    - **experience_context** (object) - Required - Defines the user experience context for the transaction.
      - **brand_name** (string) - Optional - The brand name to be displayed to the customer.
      - **locale** (string) - Optional - The locale for the user interface, e.g., 'en-US'.
      - **return_url** (string) - Required - The URL where the payer is redirected after approving the 3D Secure flow.
      - **cancel_url** (string) - Required - The URL where the payer is redirected if they cancel the 3D Secure flow.

### Request Example
```bash
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H "PayPal-Request-Id: REQUEST-ID" \
 -d '{ \
     "payment_source": { \
       "card": { \
         "number": "4111111111111111", \
         "expiry": "2027-02", \
         "name": "Firstname Lastname", \
         "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" \
         }, \
         "verification_method": "SCA_WHEN_REQUIRED", \
         "experience_context": { \
           "brand_name": "YourBrandName", \
           "locale": "en-US", \
           "return_url": "https://example.com/returnUrl", \
           "cancel_url": "https://example.com/cancelUrl" \
         } \
       } \
     } \
    }'
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The unique identifier for the setup token.
- **customer** (object) - Information about the customer.
  - **id** (string) - The customer's unique identifier.
- **status** (string) - The status of the setup token. Will be `PAYER_ACTION_REQUIRED` if 3D Secure is triggered.
- **payment_source** (object) - Details of the payment source.
  - **card** (object) - Card details.
    - **last_digits** (string) - The last four digits of the card number.
    - **brand** (string) - The brand of the card (e.g., VISA, MASTERCARD).
    - **type** (string) - The type of card (e.g., CREDIT, DEBIT).
    - **expiry** (string) - The expiration date of the card.
- **links** (array) - HATEOAS links for subsequent actions.
  - **href** (string) - The URL for the action.
  - **rel** (string) - The relationship of the link to the current resource (e.g., `approve`, `confirm`, `self`).
  - **method** (string) - The HTTP method to use for the action.
  - **encType** (string) - The encoding type for the request.

#### Response Example
```json
{
  "id": "5C991763VB2781612",
  "customer": {
    "id": "customer_4029352050"
  },
  "status": "PAYER_ACTION_REQUIRED",
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "brand": "VISA",
      "type": "CREDIT",
      "expiry": "2027-02"
    }
  },
  "links": [{
      "href": "https://paypal.com/webapps/helios?action=authenticate&validate_session_id=82cf4a87-5c40-0a27-1a09-4ffbb0d05fdc",
      "rel": "approve",
      "method": "GET",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
      "rel": "confirm",
      "method": "POST",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    }
  ]
}
```
```

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

### Node.js Project Setup

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

Sets up a Node.js project for PayPal integration, including directory structure, package installation, and environment configuration.

```bash
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."
```

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

### Start Server

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

Start the server using npm. The application will be accessible 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
```

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

### Python Project Setup

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

Sets up a Python project for PayPal integration, including directory structure, virtual environment, package installation, and environment configuration.

```bash
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."
```

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

### Create Setup Token (No Verification)

Source: https://docs.paypal.ai/payments/save/api/vault-api-integration-test

This snippet demonstrates how to create a setup token for a credit or debit card with no verification. It includes sample request and response for the 'Create a setup token' endpoint.

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

### Description
Creates a setup token for a credit or debit card with no verification. The card data is checked only for format.

### Method
POST

### Endpoint
https://api-m.sandbox.paypal.com/v3/vault/setup-tokens

### Parameters
#### Request Body
- **payment_source** (object) - Required - Details of the payment source.
  - **card** (object) - Required - Card details.
    - **number** (string) - Required - The credit or debit card number.
    - **expiry** (string) - Required - The expiry date of the card in 'YYYY-MM' format.
    - **name** (string) - Required - The name of the cardholder.
    - **billing_address** (object) - Required - The billing address associated with the card.
      - **address_line_1** (string) - Required - The first line of the street address.
      - **address_line_2** (string) - Optional - The second line of the street address.
      - **admin_area_1** (string) - Required - The state or province.
      - **admin_area_2** (string) - Required - The city or town.
      - **postal_code** (string) - Required - The postal code.
      - **country_code** (string) - Required - The two-letter ISO 3166-1 country code.
    - **experience_context** (object) - Optional - Context for the payment experience.
      - **brand_name** (string) - Optional - The brand name to be displayed on the PayPal-hosted payment pages.
      - **locale** (string) - Optional - The locale of the payment pages.
      - **return_url** (string) - Required - The URL to redirect the user to after successful payment.
      - **cancel_url** (string) - Required - The URL to redirect the user to if the payment is canceled.

### Request Example
```json
{
  "payment_source": {
    "card": {
      "number": "4111111111111111",
      "expiry": "2027-02",
      "name": "Firstname Lastname",
      "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"
      }
    }
  }
}
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The ID of the setup token.
- **customer** (object) - Information about the customer.
  - **id** (string) - The customer ID.
- **status** (string) - The status of the setup token (e.g., "APPROVED").
- **payment_source** (object) - Details of the payment source.
  - **card** (object) - Card details.
    - **last_digits** (string) - The last four digits of the card number.
    - **expiry** (string) - The expiry date of the card.
    - **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 street address.
      - **address_line_2** (string) - The second line of the street address.
      - **admin_area_2** (string) - The city or town.
      - **admin_area_1** (string) - The state or province.
      - **postal_code** (string) - The postal code.
      - **country_code** (string) - The two-letter ISO 3166-1 country code.
- **links** (array) - HATEOAS links related to the setup token.
  - **href** (string) - The URL for the link.
  - **rel** (string) - The relationship of the link (e.g., "self", "confirm").
  - **method** (string) - The HTTP method for the link.
  - **encType** (string) - The content type for the request.

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

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

### Create a Setup Token

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

This operation creates a setup token that can be used to initiate a payment setup.

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

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

### Method
POST

### Endpoint
/v1/setup-tokens

### Request Body
- **payment_method_preference** (object) - Optional - The preferred payment method. If not provided, the API will use the most relevant payment method.
  - **payment_method** (string) - Required - The payment method to use. Supported values: `VENMO`.

### Request Example
```json
{
  "payment_method_preference": {
    "payment_method": "VENMO"
  }
}
```

### Response
#### Success Response (201)
- **id** (string) - The ID of the created setup token.
- **href** (string) - The HATEOAS link to the setup token resource.
- **status** (string) - The status of the setup token. Possible values: `CREATED`, `APPROVED`, `VOIDED`.
- **payment_method_type** (string) - The type of payment method associated with the token.

#### Response Example
```json
{
  "id": "st-12345",
  "href": "https://api.paypal.com/v1/setup-tokens/st-12345",
  "status": "CREATED",
  "payment_method_type": "VENMO"
}
```
```

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

### Get Setup Token

Source: https://docs.paypal.ai/payments/save/api/vault-api-integration-test

Retrieves 3D Secure verification data associated with a setup token.

```APIDOC
## GET /v3/vault/setup-tokens/{setup_token_id}

### Description
Retrieves 3D Secure verification data associated with a setup token.

### Method
GET

### Endpoint
/v3/vault/setup-tokens/{setup_token_id}

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

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "PayPal-Request-Id: REQUEST-ID"
```

### Response
#### Success Response (200)
- **verification_method** (string) - The verification method value from the request.
- **verification_status** (string) - The status of the verification (e.g., VERIFIED).
- **authorization** (object) - Details from the authorization, including amount, currency, and AVS/CVV results.

#### Response Example
```json
{
  "id": "5C991763VB2771612",
  "status": "APPROVED",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last_digits": "1111",
      "verification_status": "VERIFIED",
      "verification": {
        "network_transaction_id": "20286098380002303",
        "time": "2020-10-07T22:44:41.000Z",
        "amount": {
          "value": "0.00",
          "currency_code": "USD"
        },
        "processor_response": {
          "avs_code": "M",
          "cvv_code": "P"
        },
        "three_d_secure": {
          "type": "THREE_DS_AUTHENTICATION",
          "eci_flag": "FULLY_AUTHENTICATED_TRANSACTION",
          "card_brand": "VISA",
          "enrolled": "Y",
          "pares_status": "Y",
          "three_ds_version": "2",
          "authentication_type": "DYNAMIC",
          "three_ds_server_transaction_id": "3d-secure-txn-id"
        }
      }
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
      "rel": "confirm",
      "method": "POST",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    }
  ]
}
```
```

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

### Create Setup Token

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

This endpoint generates a setup token required to initiate the customer-initiated vault flow. It is crucial for starting the process of securely storing payment details with PayPal.

```APIDOC
## POST /paypal-api/vault/setup-token/create

### Description
Creates a server-side endpoint that generates a setup token to start the customer-initiated vault flow. This is essential for securely capturing and storing payment information for future use.

### Method
POST

### Endpoint
/paypal-api/vault/setup-token/create

### Request Body
- **paymentSource** (object) - Required - Details about the payment source.
  - **paypal** (object) - Required - PayPal specific payment source details.
    - **experienceContext** (object) - Required - Context for the payment experience.
      - **cancelUrl** (string) - Required - The URL to redirect the user to if they cancel the transaction.
      - **returnUrl** (string) - Required - The URL to redirect the user to after successful authorization.
      - **vaultInstruction** (string) - Required - Specifies when the vaulting should occur (e.g., 'OnPayerApproval').
    - **usageType** (string) - Required - The type of usage for the PayPal payment token (e.g., 'Merchant').

### Request Example
```json
{
  "paymentSource": {
    "paypal": {
      "experienceContext": {
        "cancelUrl": "https://example.com/cancelUrl",
        "returnUrl": "https://example.com/returnUrl",
        "vaultInstruction": "OnPayerApproval"
      },
      "usageType": "Merchant"
    }
  }
}
```

### Response
#### Success Response (200)
- **jsonResponse** (object) - The response from the create setup token operation.
- **httpStatusCode** (number) - The HTTP status code of the response.

#### Response Example
```json
{
  "jsonResponse": {
    "id": "SET-UP-TOKEN-ID",
    "status": "CREATED",
    "links": [
      {
        "href": "https://www.paypal.com/checkoutnow?token=SET-UP-TOKEN-ID",
        "rel": "approve",
        "method": "GET"
      }
    ]
  },
  "httpStatusCode": 201
}
```

### Warning
PayPal requires Risk Data Acquisition (RDA) to reduce fraud. Implement risk data collection for all customer-initiated transactions (CIT) using PayPal and Venmo Payment Tokens. Missing RDA data may lead to declined payment attempts.
```

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

### Retrieve a Setup Token API Endpoint

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

This OpenAPI specification defines the GET endpoint for retrieving a setup token. It outlines the request parameters, possible responses, and security requirements.

```yaml
openapi: 3.0.3
info:
  title: Payment Method Tokens
  description: >-
    The Payment Method Tokens API saves payment methods so payers don't have to
    enter details for future transactions. Payers can check out faster or pay
    without being present after they agree to save a payment method.<br><br>The
    API associates a payment method with a temporary setup token. Pass the setup
    token to the API to exchange the setup token for a permanent
    token.<br><br>The permanent token represents a payment method that's saved
    to the vault. This token can be used repeatedly for checkout or recurring
    transactions such as subscriptions.
  version: '3.4'
  contact: {}
servers:
  - url: https://api-m.sandbox.paypal.com
    description: PayPal Sandbox Environment
  - url: https://api-m.paypal.com
    description: PayPal Live Environment
security: []
tags:
  - name: payment-tokens
    description: >-
      Use the `/vault/payment-tokens` resource to create, retrieve, and delete a
      payment token that may optionally be associated with a customer.
  - name: setup-tokens
    description: >-
      Use the `/vault/setup-tokens` resource to create and retrieve temporary
      vault payment methods.
  - name: tokens
    description: >-
      Use the `/vault/tokens` resource to detokenize a vault token to retrieve
      details associated to the underlying payment source.
  - name: tokens-session
    description: >-
      Use the `/vault/tokens/{id}/session` resource to read the token session
      cache and retrieve details associated to the underlying payment source.
  - name: customers
    description: >-
      Use the `/vault/customers` resource to create, update, get and delete a
      customer.
  - name: payment-method-credentials
    description: >-
      Use the `/vault/payment-method-credentials` resource to create payment
      method credentials
externalDocs:
  url: https://developer.paypal.com/docs/api/vault/v3/
paths:
  /v3/vault/setup-tokens/{id}:
    get:
      tags:
        - setup-tokens
      summary: Retrieve a setup token
      description: >-
        Returns a readable representation of temporarily vaulted payment source
        associated with the setup token id.
      operationId: setup-tokens.get
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: >-
            Found requested setup-token, returned a payment method associated
            with the token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setup_token_response'
        '403':
          description: Authorization failed due to insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: The specified resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: >-
            The requested action could not be performed, semantically incorrect,
            or failed business validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
        - Oauth2:
            - https://uri.paypal.com/services/vault/payment-tokens/read
components:
  parameters:
    id:
      name: id
      description: ID of the setup token.
      in: path
      required: true
      schema:
        type: string
        minLength: 7
        maxLength: 36
        pattern: '^[0-9a-zA-Z_-]+$'
  schemas:
    '5':
      readOnly: true
      type: object
      title: Payer
      description: >-
        The customer who approves and pays for the order. The customer is also
        known as the payer.
      format: payer_v1
    '7':
      title: PayPal Wallet Response
      description: Full representation of a PayPal Payment Token.
      type: object
    setup_token_response:
      title: Minimal Setup Token
      description: Minimal representation of a cached setup token.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/vault_id'
          description: The PayPal-generated ID for the vault token.
        customer:
          $ref: '#/components/schemas/customer'

```

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

### Retrieve 3D Secure Verification Data

Source: https://docs.paypal.ai/payments/save/api/vault-api-integration-test

Use this `GET` request to retrieve 3D Secure verification data associated with a setup token. Ensure you have the correct setup token ID.

```bash
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "PayPal-Request-Id: REQUEST-ID"
```

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

### Sample Setup Token Response

Source: https://docs.paypal.ai/payments/save/api/vault-api-integration-test

A successful response for a setup token request includes details like status, payment source, and links for further actions. The status should be 'APPROVED' for successful verification.

```json
{
  "id": "5C991763VB2771612",
  "status": "APPROVED",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last_digits": "1111",
      "verification_status": "VERIFIED",
      "verification": {
        "network_transaction_id": "20286098380002303",
        "time": "2020-10-07T22:44:41.000Z",
        "amount": {
          "value": "0.00",
          "currency_code": "USD"
        },
        "processor_response": {
          "avs_code": "M",
          "cvv_code": "P"
        },
        "three_d_secure": {
          "type": "THREE_DS_AUTHENTICATION",
          "eci_flag": "FULLY_AUTHENTICATED_TRANSACTION",
          "card_brand": "VISA",
          "enrolled": "Y",
          "pares_status": "Y",
          "three_ds_version": "2",
          "authentication_type": "DYNAMIC",
          "three_ds_server_transaction_id": "3d-secure-txn-id"
        }
      }
    }
  },
  "links": [{
      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
      "rel": "confirm",
      "method": "POST",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    }
  ]
}
```

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

### Full PayPal Messages Integration Example

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

A comprehensive example demonstrating the integration of PayPal Messages, including SDK setup, content fetching, amount updates, and handling click events for learn more modals.

```html
// Follow the Message JS Config or HTML Config Steps and add a message to your page 
<head> 
  <script src="https://www.paypal.com/web-sdk/v6/core"></script> 
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script> 
</head> 
<body> 
  <paypal-message></paypal-message> 
  <script> 
    // Option 1: Using clientId  
      const sdkInstance = await window.paypal.createInstance({ 
      clientId: "YOUR_CLIENT_ID" 
    }); 
    
    // Option 2: Using clientToken  
      const sdkInstance = await window.paypal.createInstance({ clientToken }); 

    const messagesInstance = sdkInstance.createPayPalMessages(); 
    const content = await messagesInstance.fetchContent({
      amount: "300.00", 
      currencyCode: "USD", 
      logoType: "MONOGRAM", 
      textColor: "MONOCHROME", 
      onReady: (content) => messageElement.setContent(content),
    }); 

    function triggerAmountUpdate(amount) {
      content.update({ amount });
   }

    // Create a Learn More Instance. Include an option to change the presentation mode 
      const learnMore = await messagesInstance.createLearnMore({
        presentationMode: "POPUP", 
      }); 

    // Handle the Message Click Event 
    // We need to listen to the message clicked event in order to open the learn more modal when clicked 
      messageElement.addEventListener("paypal-message-click", (event) => {
        event.preventDefault(); 
        learnMore.open(event.detail.config);
      }); 

    </script> 
  </body>
```

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

### Express Server Setup

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

Initialize an Express server with JSON parsing and static file serving capabilities.

```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}`);
});
```

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

### Get OAuth 2.0 Token in TypeScript

Source: https://docs.paypal.ai/developer/how-to/security-guidelines

This TypeScript example uses `node-fetch` to get a PayPal OAuth 2.0 access token. It illustrates how to encode client ID and secret for basic authentication and send the POST request body.

```typescript
import fetch from 'node-fetch';

const clientId = 'CLIENT_ID';
const clientSecret = 'CLIENT_SECRET';

async function getAccessToken() {
  const response = await fetch('https://api-m.sandbox.paypal.com/v1/oauth2/token', {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64'),
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'grant_type=client_credentials'
  });
  const data = await response.json();
  console.log(data);
}

getAccessToken();
```

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

### Initializing v6 SDK with Client ID

Source: https://docs.paypal.ai/developer/upgrade/sdk/js/v5-v6

Recommended authentication for v6. Initialize the SDK using `createInstance` with your client ID.

```javascript
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["paypal-payments", "venmo-payments"],
  pageType: "checkout",
});
```

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

### Initialize SDK and Setup Guest Payment Button

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

Initialize the PayPal SDK and set up the guest payment button. This is the recommended approach for initiating the standalone payment button flow.

```javascript
async function onPayPalWebSdkLoaded() {
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
    components: ["paypal-guest-payments"],
  });
  
  setupGuestPaymentButton(sdkInstance);
}

async function setupGuestPaymentButton(sdkInstance) {
  const eligiblePaymentMethods = await sdkInstance.findEligibleMethods({
    currencyCode: "USD",
  });

  const paypalGuestPaymentSession = 
    await sdkInstance.createPayPalGuestOneTimePaymentSession({
      onApprove,
      onCancel,
      onComplete,
      onError,
      onWarn,
    });

  document.getElementById("paypal-basic-card-button")
    .addEventListener("click", async () => {
      const startOptions = {
        presentationMode: "auto",
      };
      await paypalGuestPaymentSession.start(startOptions, createOrder());
    });
}
```

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

### Java Project Setup

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

Initializes a Maven project structure for Java, including necessary directories for source code and resources.

```bash
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>


```

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

### Set up PayPal SDK and Buttons

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

Integrates the PayPal SDK, checks for PayPal eligibility, creates a PayPal button, and initiates a one-time payment session. Replace YOUR_CLIENT_ID with your actual client ID. The SDK is loaded asynchronously.

```html
<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <title>PayPal Checkout</title>
</head>
<body>
  <div id='paypal-button-container'></div>
  <div id="result-message"></div>
  <script>
      // Pass the createOrder, onApprove, onCancel, and onError callbacks to the SDK
      async function createOrder (data) {
          const response = await fetch(
          "/api/orders",
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
            },
            // We don't recommend passing order amounts from the client
            // Your API should exchange a SKU for amount values
            body: JSON.stringify({ sku: 'BDUR24586' })
          },
        );
        const { id } = await response.json();
        return { orderId: id };
      };

      async function onApprove (data) {
        const { orderId } = data;
        const response = await fetch(
          `/api/orders/${orderId}/capture`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
            },
          },
        );
        const orderData = await response.json();
        return orderData;
      };

      function onCancel (data) {
        document.getElementById('result-message').innerHTML = 
          `<p style="color: orange;">Payment cancelled</p>`;
      };

      function onError (err) {
        console.error('PayPal Error:', err);
        let errorMessage = 'An error occurred. Please try again.';
        // Handle specific error codes
        if (err.message && err.message.includes('INSUFFICIENT_FUNDS')) {
          errorMessage = 'Payment declined due to insufficient funds.';
        } else if (err.message && err.message.includes('INSTRUMENT_DECLINED')) {
          errorMessage = 'Your payment method was declined. Please try another.';
        } else if (err.message && err.message.includes('TRANSACTION_REFUSED')) {
          errorMessage = 'Transaction was refused. Please contact support.';
        } else if (err.message && err.message.includes('DUPLICATE_INVOICE')) {
          errorMessage = 'This order has already been processed. Please refresh and try again.';
        }
        document.getElementById('result-message').innerHTML = 
          `<p style="color: red;">${errorMessage}</p>`;
      };

      // After the browser is done downloading the SDK, it will invoke onLoad()
      // and begin the SDK setup
      async function onLoad() {
        try {
          const sdkInstance = await window.paypal.createInstance({
            clientId: "YOUR_CLIENT_ID", // clientId is safe to put in plaintext on the client
            components: ["paypal-payments"]
          });

          const eligibility = await sdkInstance.findEligibleMethods();
          const isPayPalEligible = eligibility.isEligible('paypal');

          if (isPayPalEligible) {
            const paypalButton = document.createElement('paypal-button');
            document.querySelector('#paypal-button-container').append(paypalButton);

            const paypalCheckoutSession = await sdkInstance.createPayPalOneTimePaymentSession({
              onApprove,
              onCancel,
              onError
            });

          paypalButton.addEventListener("click", async () => {
            try {
              // Get the promise reference by invoking createOrder()
              // Do not await this async function since it can cause transient activation issues
              const createOrderPromise = createOrder();
              await paypalCheckoutSession.start(
                { presentationMode: "auto" },
                createOrderPromise,
              );
            } catch (error) {
              console.error(error);
            }
          });
          }
        } catch (error) {
          console.error(error);
        }
      }
    </script>
    <script async src="https://www.sandbox.paypal.com/web-sdk/v6/core"  onload='onLoad()'></script>
  </body>
</html>
```

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

### Auto-start Checkout on Page Load

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

Automatically initiate the standalone payment button checkout process when the page loads. This example extends the standard setup by calling `startGuestPaymentSession`.

```javascript
async function onPayPalWebSdkLoaded() {
  // ... standard setup ...
  
  const checkoutButton = document.getElementById("paypal-basic-card-button");
  
  startGuestPaymentSession(checkoutButton, paypalGuestPaymentSession);
  
  setupGuestPaymentButton(checkoutButton, paypalGuestPaymentSession);
}

async function startGuestPaymentSession(checkoutButton, paypalGuestPaymentSession) {
  const startOptions = {
    targetElement: checkoutButton,
    presentationMode: "auto",
  };
  await paypalGuestPaymentSession.start(startOptions, createOrder());
}
```

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

### Get Payment Resource Details Response

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

Example response for retrieving a specific payment resource's details, including its status, payment link, and line item information.

```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"
    }
  ]
}
```

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

### Initialize the v6 SDK

Source: https://docs.paypal.ai/developer/how-to/sdk/js/v6/configuration

Use `window.paypal.createInstance()` to initialize the SDK. This method configures the SDK with your client ID or client token, specifies the components to load, and manages other configurations like locale and pageType. It returns an SDK instance for payment eligibility checking and session creation.

```APIDOC
## `window.paypal.createInstance(options)`

### Description
Initializes the PayPal SDK with specified configuration options.

### Method
JavaScript

### Parameters
#### Options Object
- **clientId** (string) - Conditional - Your PayPal client ID. Mutually exclusive with `clientToken`.
- **clientToken** (string) - Conditional - A secure token generated by your server. Mutually exclusive with `clientId`.
- **components** (string[]) - Optional - An array of SDK components to load (e.g., `["paypal-payments", "venmo-payments"]`). Defaults to `["paypal-payments"]`.
- **pageType** (string) - Optional - The type of page where the SDK is initialized (e.g., `checkout`, `product-details`).
- **locale** (string) - Optional - The locale for UI components (e.g., `"en-US"`). Defaults to browser locale.
- **clientMetadataId** (string) - Optional - A unique identifier for tracking and debugging.
- **merchantId** (string) - Yes for partners - A unique identifier for the seller.

### Returns
A promise that resolves to an SDK instance object with methods for payment operations.
```

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

### Full PayPal Message Integration Example

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

This HTML and JavaScript code integrates PayPal messages, including SDK setup, message instance creation, content fetching, and amount updating.

```html
<head>
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
</head>
<body>
  <paypal-message amount="300.00"></paypal-message>
  <script>
    const sdkInstance = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["paypal-messages"],
    });
    const messagesInstance = sdkInstance.createPayPalMessages({
      currencyCode: "USD",
    });
    const content = await messagesInstance.fetchContent({
      ...messageElement.getFetchContentOptions(),
      currencyCode: "USD",
      logoType: "MONOGRAM",
      textColor: "MONOCHROME",
    });
    function triggerAmountUpdate(amount) {
      messageElement.setAttribute('amount', amount);
    }
  </script>
</body>
```