Accept PayPal payments

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)
• Authorize now, capture later
• Capture an authorization in several parts
• Void an authorization
• Refund a sale
• Callbacks
• 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 (partners@payme.io) with the seller's MPL.

Without the service, generate-sale with paypal fails with error 720.

Create a PayPal sale

Call 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)

{
  "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"
}

{
  "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.

Send these URLs on every PayPal sale:

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, 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

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, and every type is on Callback types reference.

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, for the full amount or less, within 7 days. The flow is the same as for cards; see Authorize now, capture later.
• Capture in several parts with multi-capture, sending paypal as the payment method.
• Void the whole authorization with refund-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, 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.

{
  "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.

Reporting

PayPal sales appear in get-sales and 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.

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.