Set up tax reporting

You can set up API access and webhook notifications to retrieve and deliver tax reports to your merchants.

Prerequisites

Before you begin, ensure you have:

• Active PayPal Complete Payments partnership.
• REST API and webhook notification integration.
• Merchant onboarding process to collect tax information through KYC/CIP verification.

1. Enable Tax Reporting as a Service

Contact your PayPal account manager to activate Tax Reporting as a Service for your partner account.

PayPal will:

1. Enable the Tax Reporting as a Service feature for your partner account.
2. Configure your account in the tax reporting platform.

After activation, PayPal provides your API credentials and partner account details for integration.

2. Set up webhook notifications

Configure webhook endpoints to receive real-time notifications about tax report events:

1. Subscribe to webhook events using one of the following methods:
   • PayPal developer account:
     1. Log in to your account.
     2. Go to App details page > Features > Webhooks.
     3. Subscribe to webhook events.
   • Webhooks management API: Use the Webhooks management API.
2. In your server-side app code, define a webhook handler that:
   • Listens to the webhook event.
   • Confirms receipt of the webhook event to PayPal.
   • Verifies the source of the event notification.
   • Parses the webhook payload received from PayPal and uses the data to deliver tax reports to merchants.

Available webhook events

Event	Trigger
TAXES.REPORTS.GENERATED	A new tax report was generated and is ready for download. Use the is_corrected field to identify corrected reports.
TAXES.REPORT_COUNT_UPDATED	Aggregate report counts were updated on scheduled dates. Example: April 1 for yearly counts.

TAXES.REPORTS.GENERATED

{
    "id": "WH-COC11055RA711503B-4YM959094A144403T",
    "event_type": "TAXES.REPORTS.GENERATED",
    "resource_type": "TAX-REPORT",
    "resource": {
        "id": "11EF-C99C-DAB460D9-B5FE-CF39DF1DE4AF",
        "account_id": "5U29WL78XSAE",
        "report_type": "1099-K",
        "tax_year": 2024,
        "total_files": 1,
        "is_corrected": false,
        "status": "GENERATION_COMPLETED",
        "create_time": "2025-01-03T06:35:27.540Z",
        "archive_time": "2035-01-01T06:35:27.540Z",
        "files_info": {
            "files": [
                {
                    "sequence": 1,
                    "name": "1099K_2024_5074985856743188092_1736229880213.pdf",
                    "links": [
                        {
                            "href": "https://api.paypal.com/v2/content/documents/CMP-044-11ef-ccbd-4c4e9b80-bd01-b6a073d4df5f/files/1/download",
                            "rel": "self",
                            "method": "GET"
                        }
                    ]
                }
            ]
        },
        "links": [
            {
                "href": "/v2/taxes/reports/11EF-C99C-DAB460D9-B5FE-CF39DF1DE4AF",
                "rel": "self",
                "method": "GET"
            }
        ]
    }
}