# RevCent MCP Operation: `CreatePayPalAccount`

This document explains how MCP/AI clients should use the `CreatePayPalAccount` operation in RevCent.

`CreatePayPalAccount` creates a new PayPal Account connection in RevCent and returns a unique PayPal Account ID.

Before creating PayPal Accounts, MCP/AI should read the PayPal Account overview:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalAccount.md
```

The overview explains what PayPal Accounts are, why ecommerce businesses should integrate PayPal with RevCent, how PayPal transaction/dispute/refund/tracking data fits into RevCent, and how PayPal Accounts benefit ecommerce operations.

Sources:
- RevCent MCP/API operations:
  - `CreatePayPalAccount`
  - `CreateSecureForm`
  - `EditPayPalAccount`
  - `GetPayPalAccount`
- RevCent PayPal Account overview: `https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalAccount.md`

---

## Operation Summary

`CreatePayPalAccount` creates a connected PayPal Account in RevCent.

A connected PayPal Account allows RevCent to integrate PayPal activity with the broader RevCent ecommerce system.

Benefits include the ability for RevCent to:

```text
Pull PayPal transaction data.
Pull PayPal dispute information.
Process PayPal refunds.
Update PayPal transactions with shipment tracking information.
Associate PayPal transactions with campaigns.
Associate PayPal transactions with third-party shops.
Connect PayPal activity to customers, sales, shipping, refunds, disputes, metadata, AI workflows, and BigQuery reporting.
```

Creating a PayPal Account is a credential-sensitive workflow. MCP/AI must use `CreateSecureForm` to collect authentication values securely.

---

# Read the PayPal Account Overview First

MCP/AI should read the PayPal Account overview before creating PayPal Accounts:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalAccount.md
```

The overview explains:

```text
What PayPal Accounts are.
Why PayPal integration is useful for ecommerce businesses.
How RevCent can pull PayPal transaction and dispute data.
How RevCent can process PayPal refunds.
How RevCent can update PayPal transactions with shipment tracking.
How campaigns and third-party shops affect PayPal attribution.
How PayPal data fits into support, fulfillment, AI, metadata, and BigQuery reporting.
```

This operation guide focuses on the `CreatePayPalAccount` request itself.

---

# Credential Security Requirement

Creating a PayPal Account requires PayPal authentication credentials.

Important:

```text
MCP/AI must not ask the user to paste PayPal credentials directly into chat.
MCP/AI must not include PayPal credentials directly in the CreatePayPalAccount request body.
MCP/AI must use CreateSecureForm.
```

`CreateSecureForm` creates a secure URL where the user can enter sensitive credentials. RevCent encrypts and stores the secure form data internally.

After the user completes the secure form, MCP/AI should pass only:

```text
secure_form_id
```

to `CreatePayPalAccount`.

---

# Secure Form Workflow

The correct MCP/AI workflow is:

```text
1. Gather non-sensitive PayPal Account settings:
   - name
   - description
   - enabled
   - paypal_account_email
   - campaign
   - third_party_shop
   - transaction_confirmation
   - add_tracking

2. Call CreateSecureForm with:
   - form_source = paypal_account

3. Provide the returned form_url to the user.

4. Tell the user they must complete the secure form within 1 hour.

5. Wait for the user to indicate the form is complete.

6. Call CreatePayPalAccount with the secure_form_id and non-sensitive settings.

7. Save/return the created paypal_account_id.
```

Example `CreateSecureForm` request:

```json
{
  "form_source": "paypal_account"
}
```

Example `CreateSecureForm` response shape:

```json
{
  "secure_form_id": "XXXXXXXXXXXXXXXXXXXX",
  "form_url": "https://...",
  "completed": false,
  "expiration_date_unix": 1770000000
}
```

Important:

```text
A secure form is temporary and expires after 1 hour.
After expiration, the secure form URL is no longer valid and saved data is deleted.
The user must be logged into RevCent to access the secure form.
```

---

# CreatePayPalAccount Schema

Input fields:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | Unique internal PayPal Account name. |
| `paypal_account_email` | string | Yes | Email associated with the PayPal account in PayPal. |
| `campaign` | string | Yes | 20-character campaign ID associated with the PayPal Account. |
| `description` | string | No | Internal description of the PayPal Account. |
| `enabled` | boolean | No | Whether the PayPal Account is enabled. |
| `third_party_shop` | array<string> | No | Array of 20-character user shop IDs associated with this PayPal Account. |
| `transaction_confirmation` | boolean | No | Whether to require delayed PayPal transaction confirmation before marking the sale paid. Recommended `false`. |
| `add_tracking` | boolean | No | Whether RevCent should add shipment tracking information to PayPal transactions when shipments are shipped. Recommended `true`. |
| `secure_form_id` | string | No, but required in credential setup workflow | 20-character secure form ID created by `CreateSecureForm`. Used to provide PayPal credentials securely. |

Schema rule:

```text
additionalProperties = false
```

Do not include unknown fields.

---

# Required Fields

`CreatePayPalAccount` requires:

```text
name
paypal_account_email
campaign
```

Although `secure_form_id` is not listed as a required schema field, it is required for the credential workflow when creating a usable PayPal Account with authentication values.

MCP/AI should generally not create a PayPal Account without completing the secure form credential workflow unless the user specifically has a documented reason and understands that credentials may not be saved.

---

# Field: `name`

`name` is the internal RevCent PayPal Account name.

Requirements:

```text
Must be unique from other PayPal Account names.
Should be descriptive.
Should help identify brand/store/currency/region/account purpose.
```

Good examples:

```text
Main PayPal - US Store
Brand A PayPal
Brand B PayPal - WooCommerce
PayPal - Supplements Store
PayPal - EU Store
```

Poor examples:

```text
PayPal
Main
Test
Account
New
```

Before creating a new PayPal Account, MCP/AI should usually check existing PayPal Accounts with:

```text
GetPayPalAccounts
```

to avoid duplicate names or unnecessary new accounts.

---

# Field: `description`

`description` is optional but useful.

Use it to explain what the PayPal Account is for.

Good examples:

```text
Primary PayPal account for Brand A checkout and WooCommerce shop.
PayPal account used for EU store PayPal purchases and refunds.
Backup PayPal account for seasonal campaign traffic.
```

The description should help future users understand why the PayPal Account exists.

---

# Field: `enabled`

`enabled` controls whether the PayPal Account is active in RevCent.

Recommended default:

```json
"enabled": true
```

Use:

```text
enabled = true
```

when the account is ready to be used.

Use:

```text
enabled = false
```

when creating the account in advance, testing, or waiting for final credential/shop/campaign review.

Do not enable a PayPal Account for active sales if credentials, campaign, or shop associations are incomplete or uncertain.

---

# Field: `paypal_account_email`

`paypal_account_email` is the email associated with the PayPal account inside PayPal.

This field is required.

Example:

```json
"paypal_account_email": "payments@example.com"
```

MCP/AI should confirm the email is the correct PayPal account email for the intended store/brand.

If the user operates multiple PayPal accounts, do not assume which one should be used.

---

# Field: `campaign`

`campaign` is the 20-character Campaign ID associated with the PayPal Account.

This field is required.

The campaign associated with the PayPal Account will apply to PayPal transactions associated with this account.

This is important for attribution and reporting.

Examples:

```text
PayPal revenue by campaign.
PayPal refunds by campaign.
PayPal disputes by campaign.
PayPal net revenue by campaign.
PayPal transaction volume by campaign.
```

MCP/AI should not guess the campaign ID.

If the user only provides a campaign name, MCP/AI should retrieve/search the available campaigns and confirm the correct campaign ID before creating the PayPal Account.

---

# Field: `third_party_shop`

`third_party_shop` is an optional array of 20-character user shop IDs.

It associates one or more third-party shops with the PayPal Account.

Example:

```json
"third_party_shop": [
  "XXXXXXXXXXXXXXXXXXXX",
  "YYYYYYYYYYYYYYYYYYYY"
]
```

Why this matters:

```text
By associating third-party shops with the PayPal Account, RevCent can correctly link PayPal transactions from those shops to the correct PayPal Account.
```

This is especially important when a business has:

```text
Multiple brands.
Multiple websites.
Multiple third-party shops.
Multiple shopping cart domains.
Multiple PayPal accounts.
```

Example:

```text
Shop A uses PayPal Account A.
Shop B uses PayPal Account B.
```

MCP/AI should ensure the shop IDs are correct before creating the account.

Do not associate every shop by default.

Only include shops that actually use this PayPal Account.

---

# Field: `transaction_confirmation`

`transaction_confirmation` controls whether RevCent waits for PayPal transaction confirmation before marking the sale as paid.

Recommended value:

```json
"transaction_confirmation": false
```

When `false`:

```text
RevCent creates a sale and marks it as paid immediately upon PayPal purchase.
This is recommended.
```

When `true`:

```text
RevCent waits for PayPal transaction confirmation before marking the sale paid.
This can take between 2 and 4 hours because of lag within the PayPal API, not RevCent.
```

MCP/AI should generally set this to `false` unless the user explicitly wants delayed PayPal confirmation.

Why `false` is usually best:

```text
Faster customer experience.
Faster order creation.
Faster fulfillment.
Less confusion for support teams.
More immediate sale/payment visibility.
```

Why `true` may be chosen:

```text
The business requires PayPal confirmation before treating the order as paid.
The business intentionally accepts delayed order processing.
The business has internal risk/compliance reasons.
```

If setting `transaction_confirmation = true`, MCP/AI should clearly explain that PayPal API lag may delay paid status by 2 to 4 hours.

---

# Field: `add_tracking`

`add_tracking` controls whether RevCent should add shipment tracking information to the respective PayPal transactions when shipments are shipped.

Recommended value:

```json
"add_tracking": true
```

When `true`:

```text
RevCent can update PayPal transactions with shipment tracking information when shipments are shipped.
```

This is valuable for ecommerce businesses selling physical products.

Benefits:

```text
Better PayPal transaction records.
Better customer transparency.
Better fulfillment visibility.
Better dispute defense.
Better delivery evidence.
Reduced support friction.
```

MCP/AI should generally set `add_tracking = true` unless the user explicitly does not want RevCent to update PayPal with tracking.

For digital-only businesses with no shipments, the setting may be less important, but leaving it true is usually harmless if there are no shippable products.

---

# Field: `secure_form_id`

`secure_form_id` is a 20-character Secure Form ID.

It is used so sensitive PayPal credentials are collected securely.

Create it using:

```text
CreateSecureForm
```

with:

```json
{
  "form_source": "paypal_account"
}
```

After the user completes the secure form, include the secure form ID in the `CreatePayPalAccount` request:

```json
"secure_form_id": "XXXXXXXXXXXXXXXXXXXX"
```

Important:

```text
The secure form expires after 1 hour.
The user must complete it before expiration.
Once completed, RevCent internally decrypts the secure form data and associates it with the PayPal Account.
```

---

# Recommended Defaults

For most ecommerce businesses, recommended defaults are:

```json
{
  "enabled": true,
  "transaction_confirmation": false,
  "add_tracking": true
}
```

Explanation:

```text
enabled = true
Use when the account is ready to process/link PayPal activity.

transaction_confirmation = false
Recommended because RevCent can mark PayPal purchases paid immediately. Setting true can delay confirmation by 2 to 4 hours due to PayPal API lag.

add_tracking = true
Recommended so RevCent updates PayPal transactions with shipment tracking when shipments are shipped.
```

---

# Example: Minimal PayPal Account Creation

This example assumes the secure form was already created and completed.

```json
{
  "name": "Main PayPal - US Store",
  "paypal_account_email": "payments@example.com",
  "campaign": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": true,
  "transaction_confirmation": false,
  "add_tracking": true,
  "secure_form_id": "YYYYYYYYYYYYYYYYYYYY"
}
```

---

# Example: PayPal Account With Third-Party Shops

```json
{
  "name": "Brand A PayPal - WooCommerce",
  "description": "Primary PayPal account for Brand A WooCommerce storefront.",
  "paypal_account_email": "brand-a-paypal@example.com",
  "campaign": "CCCCCCCCCCCCCCCCCCCC",
  "third_party_shop": [
    "SSSSSSSSSSSSSSSSSSSS"
  ],
  "enabled": true,
  "transaction_confirmation": false,
  "add_tracking": true,
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Use this when the PayPal Account should be linked to a known third-party shop/storefront.

---

# Example: Disabled Account Created in Advance

```json
{
  "name": "Brand B PayPal - Pending Launch",
  "description": "PayPal account for Brand B launch. Disabled until shop mapping is reviewed.",
  "paypal_account_email": "brand-b-paypal@example.com",
  "campaign": "CCCCCCCCCCCCCCCCCCCC",
  "enabled": false,
  "transaction_confirmation": false,
  "add_tracking": true,
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Use this when the account should be configured but not yet active.

---

# Output Schema

Successful response can include:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1770000000,
  "code": 1,
  "paypal_account_id": "YYYYYYYYYYYYYYYYYYYY",
  "result": "..."
}
```

Important fields:

| Field | Meaning |
|---|---|
| `api_call_id` | API Call ID for the CreatePayPalAccount operation. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` indicates success. |
| `paypal_account_id` | Newly created PayPal Account ID. |
| `result` | Human-readable result message. |

MCP/AI should save or return the `paypal_account_id` because it will be needed for future retrieval, editing, reporting filters, and account management.

---

# Pre-Creation Workflow

Before calling `CreatePayPalAccount`, MCP/AI should:

```text
1. Read the PayPal Account overview.
2. Determine the intended store/brand/use case.
3. Check existing PayPal Accounts with GetPayPalAccounts to avoid duplicates.
4. Confirm the PayPal account email.
5. Confirm the required campaign ID.
6. Confirm whether any third-party shops should be associated.
7. Decide enabled status.
8. Decide transaction_confirmation, normally false.
9. Decide add_tracking, normally true.
10. Create a secure form with CreateSecureForm using form_source = paypal_account.
11. Have the user complete the secure form within 1 hour.
12. Call CreatePayPalAccount with secure_form_id and non-sensitive settings.
```

---

# Checking Existing PayPal Accounts First

MCP/AI should usually call:

```text
GetPayPalAccounts
```

before creating a new PayPal Account.

Reasons:

```text
Avoid duplicate names.
Avoid duplicate PayPal account emails.
Check whether the PayPal account already exists.
Review existing campaign/shop associations.
Decide whether EditPayPalAccount is more appropriate.
```

If a matching PayPal Account already exists, MCP/AI should usually ask whether the user wants to edit the existing account instead of creating a duplicate.

---

# Campaign Selection Guidance

Because `campaign` is required, MCP/AI must have a valid 20-character campaign ID before calling `CreatePayPalAccount`.

Do not guess.

If the user says:

```text
Use my main campaign.
```

MCP/AI should retrieve available campaigns and identify the correct campaign.

The campaign affects attribution for PayPal transactions associated with the PayPal Account, so incorrect campaign selection can distort reporting.

---

# Third-Party Shop Selection Guidance

Only include `third_party_shop` IDs for shops that actually use the PayPal Account.

Do not automatically attach all shops.

Correct:

```text
User confirms Shop A uses this PayPal Account.
MCP includes Shop A's user shop ID in third_party_shop.
```

Incorrect:

```text
MCP attaches every shop because it is unsure.
```

If the user has multiple shops and is unsure which shop uses the PayPal account, MCP/AI should help review available shop configuration before creating the PayPal Account.

---

# Transaction Confirmation Guidance

MCP/AI should strongly understand this setting.

Recommended:

```json
"transaction_confirmation": false
```

Why:

```text
RevCent marks the sale paid immediately upon PayPal purchase.
This is the recommended setting.
```

Setting `true` has a specific operational consequence:

```text
PayPal confirmation may take 2 to 4 hours because of PayPal API lag.
```

This can affect:

```text
Order paid status.
Fulfillment timing.
Customer support visibility.
Automation timing.
Revenue visibility.
```

Only set true when the user explicitly wants delayed PayPal confirmation.

---

# Tracking Update Guidance

MCP/AI should usually recommend:

```json
"add_tracking": true
```

This allows RevCent to update PayPal transactions with tracking information when shipments are shipped.

This is particularly important for:

```text
Physical products.
Shipping/dispute evidence.
PayPal dispute mitigation.
Customer support.
Delivery proof.
```

If the business sells only digital products, ask whether tracking updates are relevant, but `true` is still a safe default unless the user says otherwise.

---

# Secure Form Expiration Handling

Secure forms are temporary.

Important:

```text
Secure forms expire after 1 hour.
After expiration, the form URL no longer works and saved data is deleted.
```

MCP/AI should:

```text
Tell the user they have 1 hour to complete the secure form.
Wait for the user to confirm completion.
If the form expires, create a new secure form.
Never ask the user to paste credentials into chat.
```

---

# Editing Credentials Later

If PayPal credentials need to be changed later, use:

```text
EditPayPalAccount
```

with a new:

```text
secure_form_id
```

Do not ask the user to paste credentials into chat.

`EditPayPalAccount` says `secure_form_id` should only be provided if changing PayPal credentials.

---

# PayPal Account Creation and Ecommerce Operations

Creating a PayPal Account affects more than payment setup.

It can impact:

```text
PayPal transaction visibility.
Customer support.
Refund workflows.
Dispute handling.
Shipment tracking updates.
Campaign attribution.
Third-party shop attribution.
BigQuery reporting.
AI Assistant workflows.
AI Voice Agent support context.
Functions and automation.
```

MCP/AI should treat PayPal Account creation as a business configuration task, not just an API call.

---

# Reporting After Creation

After PayPal transactions start flowing through RevCent, reporting should use:

```text
BigQueryRunQuery
```

not paginated transaction retrieval.

Use `GetPayPalTransactions` only for small paginated retrieval and finding specific PayPal transactions.

Use `BigQueryRunQuery` for:

```text
PayPal revenue by day.
PayPal revenue by campaign.
PayPal revenue by shop.
PayPal transaction volume by account.
PayPal fee analysis.
PayPal refunds by account/campaign/shop.
PayPal dispute trend analysis.
Customer-level PayPal activity.
Metadata-based PayPal analysis.
```

Use:

```text
GetBigQueryTables
```

before writing SQL.

---

# Common Mistakes

## Mistake: Asking User to Paste PayPal Credentials

Wrong:

```text
Please paste your PayPal API credentials here.
```

Correct:

```text
Create a secure form with CreateSecureForm and have the user enter credentials there.
```

---

## Mistake: Creating Duplicate PayPal Accounts

Wrong:

```text
Create a new PayPal Account without checking existing accounts.
```

Correct:

```text
Use GetPayPalAccounts first to see whether the PayPal Account already exists.
```

---

## Mistake: Guessing Campaign ID

Wrong:

```text
Use a random or assumed campaign ID.
```

Correct:

```text
Retrieve/confirm the exact campaign ID before creating the PayPal Account.
```

---

## Mistake: Attaching the Wrong Shops

Wrong:

```text
Attach all shops by default.
```

Correct:

```text
Only attach third-party shops that actually use this PayPal Account.
```

---

## Mistake: Setting Transaction Confirmation to True Without Understanding Delay

Wrong:

```json
"transaction_confirmation": true
```

without explanation.

Correct:

```text
Use false unless the user explicitly wants delayed confirmation. True can delay paid status by 2 to 4 hours due to PayPal API lag.
```

---

## Mistake: Disabling Tracking Updates for Shippable Products

Wrong:

```json
"add_tracking": false
```

without reason.

Correct:

```text
Use add_tracking = true for businesses that ship physical products so RevCent can update PayPal with tracking information.
```

---

## Mistake: Sending Unknown Fields

Wrong:

```json
{
  "name": "Main PayPal",
  "paypal_secret": "...",
  "random_field": true
}
```

Correct:

```text
Use only fields allowed by the schema.
Use secure_form_id for credentials.
```

---

# MCP/AI Decision Guide

Use `CreatePayPalAccount` when:

```text
The user explicitly wants to add/connect a new PayPal Account.
The account does not already exist in RevCent.
The required campaign is known.
The PayPal account email is known.
The secure form has been created and completed.
The user has confirmed transaction_confirmation and add_tracking settings.
The relevant third-party shops are known, if applicable.
```

Use `EditPayPalAccount` instead when:

```text
The PayPal Account already exists.
The user only wants to update settings.
The user wants to update credentials for an existing account.
The user wants to change campaign/shop/confirmation/tracking settings.
```

Use `GetPayPalAccounts` first when:

```text
The user is unsure whether the account already exists.
The user only provides a name/email.
The user wants to review PayPal Accounts.
The MCP needs to avoid duplicate account names.
```

---

# Validation Checklist

Before calling `CreatePayPalAccount`:

1. The user wants to create a new PayPal Account.
2. Existing PayPal Accounts have been checked when appropriate.
3. `name` is unique and descriptive.
4. `paypal_account_email` is confirmed.
5. `campaign` is a valid 20-character campaign ID.
6. `third_party_shop` IDs are valid 20-character user shop IDs, if provided.
7. Shops included actually use this PayPal Account.
8. `transaction_confirmation` is intentionally set, usually `false`.
9. If `transaction_confirmation = true`, user understands PayPal API confirmation may take 2 to 4 hours.
10. `add_tracking` is intentionally set, usually `true`.
11. Secure credentials are collected through `CreateSecureForm`.
12. `secure_form_id` is included after the user completes the secure form.
13. The secure form has not expired.
14. No sensitive credentials are sent directly in the request body.
15. No unknown fields are included.

---

# Key Takeaways

```text
CreatePayPalAccount creates a connected PayPal Account in RevCent.
```

```text
The required fields are name, paypal_account_email, and campaign.
```

```text
Use CreateSecureForm with form_source = paypal_account to collect PayPal credentials securely.
```

```text
Do not ask the user to paste PayPal credentials into AI/MCP chat.
```

```text
transaction_confirmation should usually be false.
```

```text
add_tracking should usually be true.
```

```text
third_party_shop should include only shops that actually use this PayPal Account.
```

```text
The campaign association affects PayPal transaction attribution.
```

```text
Read the PayPal Account overview before creating PayPal Accounts:
https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalAccount.md
```


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.