# Accept PayPal payments Building with an AI agent? Start at https://docs.payme.io/agents.md ## Prerequisites - The seller's seller_payme_id (MPL) - The PayPal service active on the seller's account and connected to the seller's PayPal account - A public HTTPS URL for sale_callback_url ## Related - [Create a sale (hosted payment page)](/payments/hosted-payment-page/post-generate-sale) - [Authorize now, capture later](/accepting-payments/capture-and-saved-cards/capture-sale) - [Capture an authorization in several parts](/accepting-payments/capture-and-saved-cards/multi-capture) - [Void an authorization](/payments/post-sale-actions/void-sale) - [Refund a sale](/payments/post-sale-actions/post-refund-sale) - [Callbacks](/payments/getting-started/callbacks) - [Handle chargebacks](/accepting-payments/after-the-sale/handle-chargebacks) With PayPal, the buyer pays from their PayPal account. The seller connects its own PayPal account to PayMe, and the money from PayPal sales goes to that PayPal account. You create the sale with `sale_payment_method: paypal`, the buyer approves the payment on PayPal, and PayMe completes it and sends you the result. How PayPal differs from cards: - **The money stays in PayPal.** PayPal sales aren't added to the seller's PayMe balance, so they aren't part of PayMe withdrawals. Refunds are paid from the seller's PayPal account. - **No platform fee.** PayMe doesn't apply `market_fee` to PayPal sales. - **Not on the `multi` page.** Create a sale with `sale_payment_method: paypal` to offer PayPal. - **One payment.** A `paypal` sale with more than one installment fails with error `351`. - **No saved payment method.** `capture_buyer` with `paypal` returns error `4`. - **Payment page only.** Hosted Fields has no PayPal method. ## Turn on PayPal PayPal must be active on the seller's account and connected to the seller's PayPal account. To set it up, contact PayMe Partners () with the seller's MPL. Without the service, `generate-sale` with `paypal` fails with error `720`. ## Create a PayPal sale Call [`generate-sale`](/payments/hosted-payment-page/post-generate-sale) from your server with `sale_payment_method: paypal`. `POST https://sandbox.payme.io/api/generate-sale` (production: `https://live.payme.io/api/generate-sale`) ```json { "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "sale_payment_method": "paypal", "sale_price": 1000, "currency": "ILS", "product_name": "Order 1234", "transaction_id": "order-1001", "sale_callback_url": "https://your-server.example.com/payme/callback", "sale_return_url": "https://your-site.example.com/payment/success", "cancel_url": "https://your-site.example.com/payment/canceled", "language": "en" } ``` ```json { "status_code": 0, "session": "AtsJ0as5", "sale_url": "https://sandbox.payme.io/sale/generate/SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX", "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX", "payme_sale_code": 12345678, "price": 1000, "transaction_id": "order-1001", "currency": "ILS", "sale_payment_method": "paypal" } ``` Store `payme_sale_id`, and redirect the buyer to `sale_url` in the full browser window. The page sends the buyer straight on to PayPal, so don't show it in an iframe. Partners also send `payme_client_key`; see [Authentication](/payments/getting-started/authentication). Send these URLs on every PayPal sale: | Field | Why | |---|---| | `sale_callback_url` | Where PayMe sends the result. See [Callbacks](/payments/getting-started/callbacks). | | `sale_return_url` | Where the buyer goes after approving the payment on PayPal. | | `cancel_url` | Where PayPal sends a buyer who cancels. Without it, a buyer who cancels on PayPal doesn't come back to your site. | ## What the buyer does 1. The buyer opens `sale_url`, and PayMe sends them to PayPal. 2. The buyer logs in to PayPal and approves the payment. 3. PayMe completes the payment, sends `sale-complete` to your `sale_callback_url`, and the buyer is sent to `sale_return_url`. The buyer can reach `sale_return_url` before your callback arrives. Fulfil the order on `sale-complete`, or after you check the sale with [`get-sales`](/payments/query-apis/post-get-sales), not on the redirect. If the buyer cancels on PayPal, PayPal sends them to `cancel_url`. The sale stays `initial` and PayMe sends no callback. The buyer can open `sale_url` again to pay. ## Outcomes and callbacks | `notify_type` | When | |---|---| | `sale-complete` | The buyer approved and PayMe completed the payment, or you captured an authorization. `sale_payment_method` is `paypal`. | | `sale-authorized` | The buyer approved a sale created with `sale_type: authorize`. | | `sale-failure` | PayPal declined the payment, or PayMe couldn't complete it. The reason is in `status_error_code`. | | `refund` | The sale was refunded, or the authorization was voided. | `buyer_name`, `buyer_email` and `buyer_phone` come from the buyer's PayPal account. When PayPal doesn't share one, PayMe uses the value you sent in `sale_name`, `sale_email` or `sale_mobile`. Callback fields, signature and delivery rules are on [Callbacks](/payments/getting-started/callbacks), and every type is on [Callback types reference](/payments/getting-started/callback-types). ## Authorize now, capture later PayPal supports authorizations. Create the sale with `sale_type: authorize`. When the buyer approves, the sale becomes `authorized` and PayMe sends `sale-authorized`. Then: - **Capture once** with [`capture-sale`](/payments/post-sale-actions/post-capture-sale), for the full amount or less, within 7 days. The flow is the same as for cards; see [Authorize now, capture later](/accepting-payments/capture-and-saved-cards/capture-sale). - **Capture in several parts** with [multi-capture](/accepting-payments/capture-and-saved-cards/multi-capture#paypal), sending `paypal` as the payment method. - **Void the whole authorization** with [`refund-sale`](/payments/post-sale-actions/void-sale), leaving out `sale_refund_amount`. Partial voids aren't supported for PayPal. To charge less than you authorized, capture a lower amount instead. ## Refunds Refund a PayPal sale with [`refund-sale`](/payments/post-sale-actions/post-refund-sale), in full or in parts. The money goes back to the buyer through PayPal, and is paid from the seller's PayPal account, not from the PayMe balance. ```json { "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX", "sale_refund_amount": 500, "language": "en" } ``` The rules on the `refund-sale` page apply, for example the minimum amount of each partial refund. Refund through `refund-sale` rather than in PayPal, so that PayMe records the refund and sends the `refund` callback. ## Disputes A dispute that a buyer opens on a PayPal payment is handled in PayPal, between the buyer, PayPal and the seller's PayPal account. PayMe isn't notified, so it sends no `sale-chargeback` callback for it. Chargebacks on other payment methods are covered in [Handle chargebacks](/accepting-payments/after-the-sale/handle-chargebacks). ## Reporting PayPal sales appear in [`get-sales`](/payments/query-apis/post-get-sales) and [`get-transactions`](/payments/query-apis/post-get-transactions) like other sales, with `paypal` as the payment method. Because the money is paid out by PayPal, they don't appear in [withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals). ## Test PayPal Ask PayMe how to test PayPal in the sandbox before you go live. You can test the rest of your integration (callbacks, `get-sales`, refunds) with the cards on [Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods).