# PayPal Setup

PayPal is available as a payment method in Kustom Checkout (KCO). This guide covers how the integration works, what is handled by Kustom vs. PayPal, and how to get started.

## How it works

Kustom's standard payment method offering covers four layers of the payments stack. When PayPal is the payment method, the ownership is split between Kustom and PayPal:

| Layer | Managed by |
|  --- | --- |
| **Checkout** (end-to-end checkout process) | Kustom |
| **Order Management** (captures, refunds, cancellations via API or portal) | Kustom |
| **Settlement & Reporting** (payouts, reconciliation, financial reporting) | PayPal |
| **Disputes** (evidence submission, response workflows, resolution) | PayPal |


You manage orders, captures, refunds, and cancellations and other order management actions through Kustom, exactly as you do for other payment methods. Settlement and financial reporting is accessed through your **PayPal merchant dashboard**. Disputes on PayPal transactions are managed through **PayPal's Dispute Center**.

## Settlement & Reporting

Transaction-level financial data and reconciliation for PayPal orders live in your PayPal dashboard, not in Kustom. Payout schedules and settlement timing follow PayPal's infrastructure. Your finance team will need to work with two reporting environments: Kustom for order data, and PayPal for settlement data.

### Reconciliation and references

Kustom passes the **Kustom order ID** to PayPal on every transaction. If merchant reference 1 (mref1) is available at the time Kustom captures against PayPal, it is passed in a separate field.

**References are not updated retroactively.** If you set or update mref1 after the order has been captured, it will not be propagated to PayPal. Use the Kustom order ID (always present on both sides) to connect transactions between Kustom and PayPal reporting.

If your workflow involves updating references after order creation, use the Kustom order ID as your primary reconciliation key for PayPal transactions.

## Disputes

Kustom's dispute tooling does not apply to PayPal transactions. The **Disputes tab** in the Kustom Portal shows which orders have active PayPal disputes and their current status. To respond to and resolve disputes, go to **PayPal's Dispute Center** directly. Response timeframes, evidence requirements, and resolution follow PayPal's rules.

## Kustom Portal

### Orders tab

Full functionality is available for PayPal orders, including the Order Report. You can view all PayPal orders, their statuses, and perform order management actions just like any other payment method.

### Settlement tab

PayPal transactions are filtered out from all settlement-related reports (transaction reports, settlement reports, settlement batch reports, and balance reports). Use your PayPal dashboard for PayPal financial data.

### Disputes tab

Shows which orders have active PayPal disputes and their current status. To manage and resolve disputes, go to PayPal's Dispute Center.

## API

### Order Management `/ordermanagement/`

All endpoints are fully supported for PayPal orders. The standard order lifecycle (authorization, capture, cancellation, refunds) works identically to other payment methods.

### Settlement and transaction endpoints `/payouts` `/transactions` `/reports`

PayPal transactions are filtered out from all settlement-related endpoints. Perform financial reconciliation for PayPal orders via PayPal's own reporting or dashboard.

## Getting started

### Prerequisites

Before PayPal can be activated on your KCO integration, you need:

1. **An active, verified PayPal Business account** in a supported market. Kustom does not provision PayPal accounts. If you do not have one, complete PayPal's onboarding and KYC process first. A link is available in the Kustom Portal.
2. **Connect your PayPal account to KCO** using the partner referral link in the portal. Log in to your PayPal Business account, grant Kustom the necessary permissions, and PayPal becomes available as a payment method.


### Production vs. Playground

The account you link depends on the environment:

- **Playground (testing):** Link a sandbox Business Account related to your Main account, found in the “Testing” tab. Use one of the Personal accounts, also found under “Testing” to act as the shopper during testing.
- **Production:** Link your **Main account** directly.