↑↓ selectEnter openEsc close

    1. Elbuz

    How to accept PayPal payments in your store

    6 min readUpdated

    PayPal adds its buttons to checkout: wallet, Pay Later, card without an account, in the EU — iDEAL, BLIK, Przelewy24 and more. They appear once the order is confirmed; the store charges the exact amount and sets the status.

    When you need this:

    • You sell to the EU, UK or US — customers expect PayPal.
    • The customer wants instalments — Pay Later, and you get paid in full.
    • No PayPal account — pay by card in the PayPal window.
    • A refund — a button in the Elbuz order card, no PayPal login.

    Where to start: “Store settings” → “Checkout & payment” → PayPal → keys, webhook and the “Enabled” switch.

    What PayPal payments can do

    How to connect PayPal

    You need your company's PayPal business account (type Business, not Personal). Elbuz has no shared keys: the module works only with the keys of your own PayPal app.

    1. Create a PayPal app and copy the keys — where exactly.
    2. Open the module screen. “Store settings” → the “Checkout & payment” section → the PayPal card.
    3. Enter the keys. Test ones go in the “Sandbox keys” block, live ones in “Live keys”.
    4. Add a webhook in the PayPal app and enter its “Webhook ID” — how.
    5. Turn on the “Enabled” switch at the top of the screen.
    6. Click “Save”. The settings go to the store right away.
    7. Check a payment in the sandbox and switch to live mode — how.
    The “Checkout & payment” section of Store settings with the module cards, including PayPal
    1PayPal card
    2Status switch
    1. The PayPal card — click it to open the PayPal settings screen.
    2. The switch on the card shows whether shoppers see this payment method and whether the latest changes have reached the store.
    The maximized PayPal module window with the Connection block and the side cards
    1Enabled switch
    2Test mode (sandbox)
    3Webhook address
    4Webhook events
    5Still to set up
    6Mode row
    1. Enabled — shows PayPal to customers after saving.
    2. Test mode (sandbox) — on: payments go to the PayPal test environment with sandbox keys; off: real payments with live keys.
    3. Webhook address — paste this address into the PayPal app under Webhooks → Add Webhook.
    4. Webhook events — the events to tick in the webhook.
    5. Still to set up — what is missing for the payment to work.
    6. Mode — which mode is working now.

    An enabled module won't save without the Client ID and Secret of the current mode. How the window works in general is covered in “Store settings”.

    PayPal appears at checkout only for currencies it accepts: USD, EUR, GBP, PLN, CZK, CHF and others. PayPal doesn't accept hryvnias, and the store doesn't convert amounts. If no store currency fits, the right side shows “None of the store currencies is supported by PayPal — customers will not see PayPal”.

    Add the currency in “Directories → Currencies and rates” — active, with a rate and the “Show on site” mark. It goes to the store with the next export.

    Where to get the keys and Webhook ID

    The keys come from the PayPal developer site — developer.paypal.com; log in with the same business account.

    1. Open Apps & Credentials. At the top there is a Sandbox / Live toggle: each mode has its own apps and keys.
    2. Create App → the store name, type Merchant → save.
    3. Copy the Client ID into the “Client ID” field.
    4. Next to Secret key 1, click Show and copy it into “Secret key”.
    Block on the screenKeys of which appWhen they work
    Sandbox keysThe app in Sandbox mode“Test mode (sandbox)” is on: no real money
    Live keysThe app in Live modeTest mode is off: real customer payments

    The key card of the current mode is expanded and marked “in use now”. Only this mode's keys are required.

    The Sandbox keys card expanded and the Live keys card collapsed
    1in use now
    2Client ID
    3Secret key
    4Webhook ID
    5Live keys
    1. The keys of this mode are in use now; only they are required.
    2. Client ID of the PayPal app (Apps & Credentials).
    3. Secret key from the same page; after saving it is not shown, only a mark that it is set.
    4. Webhook ID from the Webhooks section of the same app.
    5. Keys of the other mode; click to expand.

    The secret key isn't shown after saving — the field only says “set”. To change it, click “Replace” and paste a new one.

    Why you need a webhook and how to add it

    A webhook is a message from PayPal about what happened after payment. Without it, payments work, but the store won't learn:

    • that a pending payment was completed or declined;
    • that you refunded money in your PayPal account;
    • that the customer paid and closed the tab without waiting for the store.
    1. In the “Connection” block, copy the “Webhook address” with the “Copy” button.
    2. On developer.paypal.com: the same app → Webhooks → Add Webhook. Paste the address.
    3. Tick the events from the “Webhook events” field — you can copy them with the “Copy all” button. Save.
    4. PayPal shows the Webhook ID — enter it in the “Webhook ID” field of the same key block.
    5. Repeat for the other mode: Sandbox and Live have separate webhooks.

    While the current mode's Webhook ID is empty, the right side shows “No Webhook ID — PayPal events will not arrive…”.

    The store verifies every message with PayPal itself by the Webhook ID, and asks PayPal about the payment once more. A forged message won't change the order. The webhook address must be https:// and must not be behind a site password or bot protection.

    How to check in the sandbox

    The sandbox is a test PayPal: no real money, and you need no contract or company.

    1. On developer.paypal.com: Testing Tools → Sandbox Accounts. A test business account and a test personal account for the customer are already there.
    2. On the module screen, “Test mode (sandbox)” is on, and “Sandbox keys” has the keys and Webhook ID. Save.
    3. Switch the storefront to a PayPal currency, such as EUR, and place an order with PayPal.
    4. Above the buttons you'll see “PayPal test mode (sandbox): no real money is charged.” Log in with the test personal account and pay.
    5. The order in Elbuz gets the status from the “Paid” field. The payment itself is visible in the PayPal sandbox account.
    6. Turn off “Test mode (sandbox)”, fill in “Live keys” and save.

    While test mode is on, the right side shows “Test mode is on — no money is charged. Turn it off before you start selling”.

    After switching to live, the store closes unpaid test attempts itself. A test payment in live mode won't make the order paid.

    Which buttons the customer sees

    PayPal draws the buttons itself. The “Checkout buttons” block sets their look and which methods to allow. Whether to show a method to a given customer is up to PayPal: by country, currency and amount.

    The Checkout buttons block with layout, color, shape, text and four switches
    1Layout
    2Pay Later
    3Local EU methods
    4Card button
    5Card form on the page
    1. Look of the buttons: PayPal's own options.
    2. The customer pays in installments, the store receives the full amount at once.
    3. iDEAL, Bancontact, EPS, MyBank for EUR; BLIK and Przelewy24 for PLN.
    4. Card payment without a PayPal account.
    5. Card fields right in the store, if PayPal has enabled Advanced Credit and Debit Card Payments.
    FieldWhat it doesDefault
    Pay LaterThe customer pays PayPal in instalments, the store gets the full amount at once. Only in countries where PayPal offers it, for example UK, DE, FR, ES, IT, USOn
    Local EU methodsSeparate buttons for local methods: in euros — iDEAL, Bancontact, EPS, MyBank; in zloty — BLIK and Przelewy24On
    Card button“Debit or Credit Card”: card payment without a PayPal account, no separate contract neededOn
    Card form on the pageCard fields right in the store, with 3-D Secure when the bank requires it. Needs Advanced Credit and Debit Card Payments in your PayPal account. Without it, the form won't appear and the card button staysOff

    “Layout”, “Colour”, “Shape” and “Text on the button” are PayPal's own options. Vertical puts all methods one under another, horizontal puts two buttons side by side.

    The button language is the store's main language: English, Polish, German, French, Spanish, Italian or Russian. PayPal has no Ukrainian — for it, the buttons are in English.

    How the customer pays and for which orders

    At checkout the method is called “PayPal”. After the order is confirmed, the buttons appear, the customer picks a method and pays in the PayPal window.

    What happenedWhat the customer sees
    PaidThe order success page
    Closed the PayPal window“Payment cancelled. Choose a payment method again.”
    The bank declined the cardPayPal offers another method in the same window
    Changed the cart in another tab“The order total has changed. Press the PayPal button again.” PayPal won't charge the old amount
    The buttons didn't load“Could not load PayPal…” — most often an ad blocker is in the way

    The store calculates the payment amount: it's the current order total in the currency the customer chose. For the wallet and Pay Later, PayPal doesn't ask for a shipping address — the order already has it.

    For which orders to show it

    • “Geo zone” — PayPal only for customers with an address in this zone; “All zones” — for everyone.
    • “Minimum order total” — PayPal appears from this total, in the store's main currency. Empty or 0 — always.
    • “Sort order” — the position in the payment list; a smaller number goes higher.

    Order statuses

    The store sets the status itself, and that's the status you see in Elbuz. Payment details are in your PayPal account. You choose which statuses to set in the “Order statuses” block.

    The Order statuses block with four status fields
    1Paid
    2Pending
    3Declined
    4Refunded
    1. Set when PayPal has taken the money.
    2. PayPal held the payment; the module sets Paid itself later.
    3. PayPal declined a payment that was waiting.
    4. Set after a full refund.
    FieldWhen it is setDefault
    PaidPayPal charged the money. The customer gets the usual order email“Processing”
    PendingPayPal accepted the payment but is holding it: eCheck, review, a local method with late confirmation“Pending”
    DeclinedPayPal declined a pending payment“Denied”
    RefundedThe full amount was refunded to the customer“Refunded”

    Until the customer pays, the order stays unconfirmed. Another payment attempt doesn't create an extra order. From “Pending”, the order moves to “Paid” or “Declined” by itself via the webhook or after “Refresh status” in the order card.

    When the status doesn't change

    • Wrong amount. The cart was changed right during payment. The money is in your PayPal account, but the order isn't paid: refund the payment or charge the difference.
    • A second payment. The order is already paid, but your PayPal account has two payments for it: refund the extra one.
    • A test payment in live mode. A sandbox payment won't make the order paid.

    Refunds and payment status in the order card

    A site order arrives in Elbuz as a “Customer order” document with the “PayPal” payment type. Its card has a “Payment in PayPal” block: payment state, amount, charged, refunded and how much can still be refunded. Below are all payment attempts.

    Only the buttons available to the order right now are shown:

    ButtonWhat it does
    RefundReturns the full amount or part of it to the customer. The amount field is already filled with the balance: to refund everything, keep the suggested amount
    Refresh statusGets the payment state from PayPal if the webhook didn't arrive

    Before a refund, the app asks for confirmation with the warning “This operation cannot be undone.”. The order status changes just as after a PayPal message.

    A full refund sets the status from the “Refunded” field. After a partial one the status stays, and the “Payment in PayPal” block shows the refunded amount. No refund email goes to the customer.

    If the store doesn't respond, you'll see “It is unknown whether the operation went through. Click “Retry”: the money will not move a second time”. “Retry” repeats the same operation, while clicking “Refund” again starts a new refund.

    Only a user with the “Payment operations: refund, hold, credit” right can refund money — by default, the owner. “Refresh status” is available to everyone who can see the order.

    You can also refund in your PayPal account: the payment → Refund, in full or in part. The order learns about it via the webhook if the Webhook ID is filled in.

    Once there have been orders through PayPal, the module screen header shows the last 30 days: count, total, average order value and the share of canceled or refunded ones.

    Scenarios

    Home appliances: a washing machine in instalments in Germany

    A washing machine costs €900, and the customer isn't ready to pay it all at once. Turn on EUR in currencies, keep “Pay Later” on, and set “Layout” to vertical. The customer picks Pay Later, and the order becomes paid on its own.

    Electronics: a laptop without a PayPal account

    The customer doesn't want to sign up for PayPal. “Card button” stays on — under PayPal there will be “Debit or Credit Card”. If PayPal has enabled Advanced Credit and Debit Card Payments for you, turn on “Card form on the page”.

    Headphones to the Netherlands, Belgium and Poland

    Customers there are used to iDEAL, Bancontact and BLIK. Turn on “Local EU methods” and the EUR and PLN currencies. A Dutch customer sees iDEAL, a Belgian one Bancontact, and a Polish one paying in zloty — BLIK and Przelewy24.

    Clothing: refunding one size

    The customer ordered a jacket in two sizes and returns one. In the order card, click “Refund” and enter the price of one jacket. The order status stays paid; the refund appears in the “Payment in PayPal” block.

    Souvenirs: PayPal only for abroad and from $30

    In “Geo zone”, choose a zone with the countries you need. “Minimum order total” — $30, converted to the store's main currency. Only customers abroad with a cart from this total see PayPal.

    What to do when payments don't work

    What you seeWhyWhat to do
    The customer doesn't see PayPal at checkout The module is off, the current mode has no keys, prices are in a currency PayPal doesn't accept (such as hryvnias), the total is below the minimum, or the address isn't in the geo zone Check “Enabled”, the keys, the storefront currency, “Minimum order total” and “Geo zone”
    The method is there, but the buttons don't appear The customer has an ad blocker, or the Client ID has an error Paste the Client ID again. Check from another browser
    The customer sees “Could not start the PayPal payment” The keys are from the other mode (Sandbox instead of Live) or from another app Enter the keys of the app for the mode that is in use now
    The payment is “Pending” and doesn't change The webhook doesn't arrive: no Webhook ID, a different address, missing events, or the address is behind site protection Click “Refresh status” in the order card. Then check the webhook in the PayPal app against the “Connection” block
    No Pay Later or local method PayPal shows them only for certain countries, currencies and amounts Check that the switch is on. The rest is up to PayPal
    “The store did not accept the settings” or “The store did not accept some values: see the highlighted fields” The store didn't respond or rejected some fields Fix the highlighted fields and save. If no fields are highlighted, the changes will go with the next export

    FAQ

    Can a store from Ukraine accept PayPal?

    The module works with any PayPal business account, and PayPal sets the account terms. Storefront prices must be in dollars, euros or another PayPal currency: it doesn't accept hryvnias.

    What happens if I turn the module off?

    PayPal disappears from checkout. The keys and settings are kept: turn it back on and everything is in place.

    Can I send the customer a PayPal payment link from Elbuz?

    No. Payment links from the order card work with other services: Payment links.

    How do I refund a PayPal payment to the customer?

    In the order card in Elbuz, click “Refund” in the “Payment in PayPal” block. The customer gets no refund email.

    The zone I need isn't in the “Geo zone” list — what do I do?

    Elbuz support creates the zone, for example “EU countries”. Then choose it in the “Where to show” block.

    Can I change the method name at checkout?

    Yes, through Elbuz support. The module screen has no such field.

    Where to find it and who has access

    Menu
    Directories → Operations → Store settings → “Checkout & payment” → PayPal
    Access rights
    the “Store settings” window in group permissions
    Prepare
    a PayPal business account, Sandbox and Live apps, a PayPal currency in the store

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free