# PayPal

PayPal is a digital wallet that Kustom offers in the checkout, managed like any other payment method. How to connect your PayPal Business account, and what differs from other methods, such as payouts made directly by PayPal.

Kustom offers PayPal in the checkout and manages PayPal orders exactly as it manages any
other. The difference is behind the scenes: PayPal pays out the money and handles disputes. This
page covers connecting your PayPal account and what that means for payouts and reconciliation.

Nothing here applies to PayPal added as an
[external payment method](/checkout/external-payment-methods/), where Kustom creates no order
at all.

## Connecting your PayPal account to Kustom

You need an active, verified PayPal Business account in a supported market first. Onboarding
to PayPal happens with PayPal, not Kustom: if you don't have an account, complete PayPal's own
onboarding and KYC before starting. The connection is per store, so check the store selector
before you begin.

These steps connect either your production or your playground account. The only difference is
which Portal you use and which PayPal account you log in with.

| | Production | Playground |
| --- | --- | --- |
| Kustom Portal | [portal.kustom.co](https://portal.kustom.co/) | [portal.playground.kustom.co](https://portal.playground.kustom.co/) |
| PayPal account to connect | Your live PayPal Business account | A PayPal sandbox Business account |

1. **Open the PayPal onboarding card.** In the Kustom Portal, go to **Home**. A card labelled
   **PayPal onboarding** sits in the top section.
2. **Have your PayPal Business login ready.**
   - **Production:** the login for your live PayPal Business account.
   - **Playground:** a sandbox Business account. At
     [developer.paypal.com/dashboard](https://developer.paypal.com/dashboard), go to
     **Testing Tools → Sandbox Accounts** and find the account whose type is **Business**.
     Use the three-dot menu and **View/Edit account** to reveal its password.
   - **Also for playground:** keep one of the **Personal** sandbox accounts from the same list.
     It acts as the customer when you test.
3. **Authorize the connection.** You're redirected to PayPal. Log in with the **Business**
   account, not a Personal one, and complete PayPal's prompts.
4. **Check the status.** Back in the Kustom Portal, reopen the **PayPal onboarding** card.
   It should show your store name and a Merchant ID with status **Completed**. If it shows
   anything else, close and reopen the card, or start again from step 1, **Open the PayPal
   onboarding card**.
5. **Tell your Kustom contact.** Share the store name and the Merchant ID from the card,
   for example `PM00477018`. Kustom enables PayPal in your checkout configuration. The
   connection alone doesn't switch it on.

## What Kustom owns and what PayPal owns

Kustom's payment offering normally covers four layers. With PayPal, the bottom two move.

| Layer | Managed by |
| --- | --- |
| Checkout — the end-to-end checkout experience | Kustom |
| Order Management — captures, refunds, cancellations, by API or Portal | Kustom |
| Settlement and reporting — payouts, reconciliation, financial reporting | PayPal |
| Disputes — evidence, response workflow, resolution | PayPal |

Practically: you manage PayPal orders exactly as you manage every other order, through the
Kustom API or the Portal. Reconciliation for PayPal is done outside Kustom, directly against
PayPal: transaction-level financial data and payout timing live in the PayPal dashboard and
follow PayPal's schedules.

Disputes on PayPal transactions aren't handled by Kustom's dispute tooling. The
**Disputes** tab in the Kustom Portal shows you which orders have an open PayPal dispute
and its status. Responding and resolving happens in PayPal's Dispute Center, on PayPal's
timeframes and evidence rules.

### Capture models, and how long you have to capture

A PayPal order runs on one of two capture models. They're mutually exclusive, Kustom
configures which one your store uses, and **separated authorization and capture is the
default**. If you're not sure which yours is, ask your Kustom contact before you build
capture timing or reconciliation around it.

| | Separated authorization and capture (default) | Delayed disbursement |
| --- | --- | --- |
| Captures in PayPal | One for each capture you make in Kustom | One, for the full amount, when the order is created |
| Time to capture in Kustom | 10 days | 28 days |
| Reconciling against PayPal | Per capture | Per order |

**Separated authorization and capture.** Each capture you make in Kustom produces a matching
capture in PayPal, so you can reconcile capture by capture.

**Delayed disbursement.** Kustom captures the full amount against PayPal when the order is
created. The funds sit on your PayPal account and are disbursed once you capture in full
through Kustom. Because there's one PayPal capture per order, a partial capture in Kustom
creates nothing separate in PayPal. It trades per-capture reconciliation for a longer
window.

**The capture window also caps order expiry.** A PayPal order expires after at most 10 days
on separated authorization and capture and 28 on delayed disbursement, whatever longer
expiry you've configured for other payment methods.

### Where PayPal orders appear, and where they don't

| Where | Behavior for PayPal orders |
| --- | --- |
| Portal — **Orders** tab | Full functionality, including the Order Report |
| Portal — **Settlement** tab | Absent from settlement, settlement batch and balance reports. Kustom doesn't settle PayPal transactions and creates no payout for them |
| Portal — **Disputes** tab | Listed with status, but resolved in PayPal's Dispute Center |
| API — `/ordermanagement/` | Fully supported. Authorization, capture, cancellation and refund behave identically to other methods |
| API — `/payouts`, `/transactions`, `/reports` | No payout is created for a PayPal transaction, so PayPal is absent from settlement data. Reconcile through PayPal instead |

## Reconciling PayPal transactions

Kustom passes the **Kustom order id** to PayPal when the order is created, in PayPal's
`custom_id` field, which PayPal's reporting shows as **Custom Field**. It's there in both
capture models, so it's the one value guaranteed to be present on both sides. Use it as
your reconciliation key.

`merchant_reference1` travels in PayPal's `invoice_id` field, but only if it's already set
when Kustom captures against PayPal. When that happens depends on your capture model:

| Capture model | Kustom captures against PayPal | Set `merchant_reference1` |
| --- | --- | --- |
| Separated authorization and capture (default) | When you capture the order | Before you capture |
| Delayed disbursement | When the order is created | In the create order call |

A value set later than that never reaches PayPal. And PayPal requires the invoice id to be
unique per transaction, so `merchant_reference1` must be unique per order.

## Related

- [External payment methods](/checkout/external-payment-methods/) — methods Kustom doesn't process, which work differently
- [Capture an order](/order-management/capture/) — settle a PayPal order the same way as any other
- [Settlements and getting paid](/finance/) — the Kustom side of the reporting your PayPal transactions are absent from