Setup
Follow the PayPal setup instructions before configuring PayPal payments.Vaulting
To allow customers to tokenize their PayPal account for future payments, you need to contact PayPal and request that your account be enabled for Vault. Once Vault has been enabled on your PayPal merchant account, you can toggle the tokenization feature on within the PayPal connector settings in the dashboard.
Ingest billing and shipping details
By default, billing, and shipping details received from PayPal are not imported. To enable this feature, head over to Connections → Configured and select your PayPal connector. Next, go to Credentials and toggle Import billing details and/or Import shipping details. When Import billing details is enabled, any of the user’s name, email address, and billing address are automatically imported into your transaction, merging it with any data already present on the transaction. Linked buyers are not updated, but only the snapshot of the buyer on the transaction. When Import shipping details is enabled, the user’s shipping address is automatically requested and imported into your transaction, merging it with any data already present on the transaction. Linked buyers are not updated, but only the snapshot of the buyer on the transaction.The ingestion of billing and shipping details is not available for tokenized payments.
Payment receiving preferences
By default, PayPal only settles payments automatically if the payment is in the primary currency of the PayPal merchant account. If you need to accept payments in additional currencies, you need to open a PayPal account balance in each of the currencies you intend to accept. Alternatively, you can configure your PayPal merchant account to automatically convert payments into the primary currency. If you receive a payment in a currency that your PayPal merchant account is not configured to accept, the payment enters a pending state and you need to log in to the PayPal merchant dashboard to trigger settlement, either by opening the required currency balance, or converting the payment into the primary currency of your PayPal account.FraudNet
FraudNet is a PayPal-developed JavaScript library that collects browser-based data to help reduce fraud. Upon checkout, the FraudNet library sends data elements to PayPal Risk Services for fraud and risk assessment. When creating transactions, the PayPal FraudNet library must be included on the checkout page for all transactions. When using Embed, the PayPal FraudNet library is included automatically. If you are using the API directly, you need to use the device fingerprinting library which includes the PayPal FraudNet library.Features
PayPal supports the following features:- Payment method tokenization - Store PayPal accounts for recurring or future transactions
- Delayed capture - Authorize a payment and capture it at a later time (up to 3 days for PayPal, 29 days with Vault)
- Over capture - Capture up to 115% of the authorized amount or authorized amount + $75 USD (whichever is less)
- Partial capture - Capture a portion of the authorized amount
- Refunds - Refund transactions in full or in part (up to 180 days)
- Partial refunds - Issue multiple partial refunds up to the captured amount
- Void - Cancel an authorized transaction before capture
- Deep linking - Direct integration with PayPal mobile app using deep links
- Transaction sync - Automatic synchronization of transaction status updates
- Settlement reporting - Detailed settlement reports via SFTP
- Webhook integration - Real-time notifications for payment events
Supported countries
PayPal supports transactions from buyers in the following countries:| Country code | Country code | Country code | Country code | Country code | Country code | Country code | Country code |
|---|---|---|---|---|---|---|---|
AD | AE | AG | AI | AL | AM | AO | AR |
AT | AU | AW | AZ | BA | BB | BE | BF |
BG | BH | BI | BJ | BM | BN | BO | BR |
BS | BT | BW | BY | BZ | CA | CD | CG |
CH | CI | CK | CL | CM | CN | CO | CR |
CV | CY | CZ | DE | DJ | DK | DM | DO |
DZ | EC | EE | EG | ER | ES | ET | FI |
FJ | FK | FM | FO | FR | GA | GB | GD |
GE | GF | GI | GL | GM | GN | GP | GR |
GT | GW | GY | HK | HN | HR | HU | ID |
IE | IL | IN | IS | IT | JM | JO | JP |
KE | KG | KH | KI | KM | KN | KR | KW |
KY | KZ | LA | LC | LI | LK | LS | LT |
LU | LV | MA | MC | MD | ME | MG | MH |
MK | ML | MN | MQ | MR | MS | MT | MU |
MV | MW | MX | MY | MZ | NA | NC | NE |
NF | NG | NI | NL | NO | NP | NR | NU |
NZ | OM | PA | PE | PF | PG | PH | PL |
PM | PN | PT | PW | PY | QA | RE | RO |
RS | RU | RW | SA | SB | SC | SE | SG |
SH | SI | SJ | SK | SL | SM | SN | SO |
SR | ST | SV | SZ | TC | TD | TG | TH |
TJ | TM | TN | TO | TT | TV | TW | TZ |
UA | UG | US | UY | VA | VC | VE | VG |
VN | VU | WF | WS | YE | YT | ZA | ZM |
ZW |
Supported currencies
PayPal supports processing payments in the following currencies:| Currency code | Currency code | Currency code | Currency code | Currency code | Currency code | Currency code | Currency code |
|---|---|---|---|---|---|---|---|
AUD | BRL | CAD | CHF | CNY | CZK | DKK | EUR |
GBP | HKD | HUF | ILS | INR | JPY | MXN | MYR |
NOK | NZD | PHP | PLN | RUB | SEK | SGD | THB |
TWD | USD |
Limitations
The following features are not supported by this connector:- Zero auth - Zero-dollar verification transactions are not supported
- Partial authorization - Partial authorization for insufficient funds is not available
Integration
For PayPal, the default integration is through a redirect to PayPal’s hosted checkout page. Start by creating a new transaction with the following required fields.payment_method.approval_url and the buyer_approval_pending status.
approval_url so they can log in to PayPal, review the transaction, and approve the payment. After approval, the buyer is redirected to the redirect_url you provided when creating the transaction. Do not rely solely on the redirect - either poll the transaction or (recommended) rely on webhooks to detect the final status (for example capture_succeeded or failure states).
Direct integration
PayPal provides client SDKs for a direct integration where PayPal’s own checkout UI runs on your page or in your app. The two platforms differ in one important way:- Web renders PayPal’s Smart Button on the page before the buyer acts, and the button needs the PayPal
clientIdto load. To get that without creating a transaction on every page load, you preload the connection’sclientId/merchantIdfrom a standalone session, then create the transaction and PayPal order lazily inside the SDK’screateOrdercallback. - Mobile does not need this preload. PayPal’s native iOS/Android SDK is launched with an order that already exists, so you create the transaction when the buyer taps and hand the resulting
orderIdto the SDK — there is no button to render up front.
- Web
- Mobile
The Smart Button renders on page load, so you preload the The response body holds just the two IDs. It contains no
clientId/merchantId and defer the transaction to createOrder.- On page load, fetch the standalone session to get the connection’s
clientIdandmerchantId. This requires thetransactions.writescope, so call it from your server. It creates no transaction and makes no call to PayPal.
orderId, because no order exists until the buyer clicks.This call is optional. The
clientId and merchantId are static connection values, so if you already have them you can skip the standalone session and pass them straight to the PayPal JS SDK. The session endpoint exists so you don’t have to hard-code or separately distribute the connection’s credentials to your frontend.- Also on page load, initialize the PayPal JS SDK with the
clientIdfrom the standalone session and render the Smart Button. Setcurrencyto the same currency as the order you create increateOrder(a mismatch fails the integration), and setintentto match the connection’s configured intent. The button defers the work to itscreateOrdercallback, so the transaction and order are created on click (steps 3 and 4).
- Inside the SDK’s
createOrdercallback, create a transaction with theintegration_clientset toweb. Keep this call server-side. Set the transactionintentto match the connection’s configured intent.
- Still inside
createOrder, use thesession_tokenfrom the transaction response to get the session data. This returns theorderIdand adefault_completion_url. It is meant to be called from the frontend and is not exposed in the SDKs, so call it with a plain request authenticated by thesession_token. Return theorderIdfromcreateOrderso the PayPal SDK can open the approval flow.
Complete the transaction
After the buyer completes the payment flow, the PayPal SDK provides anonApprove callback (Web) or a completion block/callback (Mobile). To finalize the payment, call the tokenized default_completion_url from the session response. This URL is safe to call from the client as it contains an embedded token.
On Web, navigate the browser to the URL (for example, window.location.assign(default_completion_url)) so it follows the HTTP 303 redirect back to your redirect_url. On Mobile, send a GET request to the URL from your completion callback.
intent=capture, the system captures the transaction.
Please refer to the PayPal SDK documentation for further guidance.