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, where Kustom creates no order at all.
Connecting your PayPal account to Kustom
Section titled “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 | portal.playground.kustom.co |
| PayPal account to connect | Your live PayPal Business account | A PayPal sandbox Business account |
- Open the PayPal onboarding card. In the Kustom Portal, go to Home. A card labelled PayPal onboarding sits in the top section.
- 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, 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.
- Authorize the connection. You’re redirected to PayPal. Log in with the Business account, not a Personal one, and complete PayPal’s prompts.
- 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.
- 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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “Related”- External payment methods — methods Kustom doesn’t process, which work differently
- Capture an order — settle a PayPal order the same way as any other
- Settlements and getting paid — the Kustom side of the reporting your PayPal transactions are absent from
This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.