PayPal

PayPal is the most popular digital wallet, with over 429 million active users worldwide. Consumers can connect their credit card or bank account to their PayPal account to make online payments, or top up their account with credits. This lets customers complete payments from their computer, smartphone, or tablet without having to fill out their card and bank details each time they make a purchase.

You can start accepting PayPal payments on the Web using the Hosted Payment Page or PayPal Component. No additional configuration is required to use PayPal in the Hosted Payment Page.

Our PayPal Component renders a PayPal button on your payment page. When a customer selects PayPal, the component presents a PayPal overlay where the customer can log in with their PayPal account details to complete the payment process.

Availability

PayPal is available to buyers and sellers across more than 200 markets worldwide. To accept it with MONEI, you connect your own PayPal Business account — see Activation.

Activation

MONEI has a PayPal integration so you can easily add PayPal as a payment method to your online store. To set up PayPal, go to MONEI Dashboard → Settings → Payment methods and click Link PayPal Business Account.

Payment methods page in the MONEI Dashboard settings, with PayPal listed under Available payment methods and the Link PayPal Business Account button

You will be redirected to a PayPal screen where you can connect your PayPal business account with MONEI. If you don't have a PayPal Business account, create one here.

Once you enable PayPal, it becomes available in the Hosted Payment Page, or you can use the PayPal Component to render the button directly on your website. After enabling PayPal, it automatically appears on your checkout page.

Fees

MONEI's PayPal fee is a flat 0.20% + €0.10 per transaction. PayPal also charges its own processing fees, which you negotiate and pay directly to PayPal — for those, visit the PayPal merchant fees page.

For MONEI's pricing on PayPal payments, see MONEI fees.

The advantage of using PayPal through MONEI is that all payments made through PayPal are included in your dashboard, giving you a centralized overview of your transactions alongside all the other payment methods configured in your account.

Payouts

The payout of PayPal transactions works differently from other payment methods. When you receive a PayPal transaction, you are paid out by PayPal itself and not by MONEI. You can adjust your PayPal payout frequency in your PayPal account.

Refunds

PayPal does not allow refunds for transactions older than 180 days. For this reason, if you try to refund a PayPal payment older than 180 days in your dashboard, you will not be able to process it.

Before you begin

This page explains how to add PayPal to your custom payment page. If you don't need a custom checkout experience we recommend using our prebuilt payment page. It already supports all available payment methods and does not require coding.

To accept PayPal payments you need to connect your PayPal business account. To connect your PayPal business account go to MONEI Dashboard → Settings → Payment methods.

To test your integration:

• Use your test mode Account ID and API Key.
• Connect test PayPal Business account in your MONEI Dashboard (in test mode)
• Use the test PayPal Personal account for payments.
• You can check the status of a test payment in your MONEI Dashboard → Payments (in test mode).

Express checkout

Use express checkout to collect shipping addresses directly in the PayPal checkout flow. See the Express Checkout guide for setup and examples.

Integration

1. Create a Payment Server-side

Create a Payment on your server with an amount and currency. Always decide how much to charge on the server side, a trusted environment, as opposed to the client. This prevents malicious customers from being able to choose their own prices.

cURL

POST https://api.monei.com/v1/payments

curl --request POST 'https://api.monei.com/v1/payments' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 110,
  "currency": "EUR",
  "orderId": "14379133960355",
  "description": "Test Shop - #14379133960355",
  "customer": {
    "email": "email@example.com"
   },
  "callbackUrl": "https://example.com/checkout/callback"
}'

(Replace YOUR_API_KEY with your actual MONEI API key)

Node.js

server.js

import {Monei} from '@monei-js/node-sdk';

// Replace YOUR_API_KEY with your actual MONEI API key
const monei = new Monei('YOUR_API_KEY');

const payment = await monei.payments.create({
  amount: 110,
  currency: 'EUR',
  orderId: '14379133960355',
  description: 'Test Shop - #14379133960355',
  customer: {
    email: 'email@example.com'
  },
  callbackUrl: 'https://example.com/checkout/callback'
});

// Pass payment.id to your client-side
const paymentId = payment.id;

PHP

server.php

<?php
require_once 'vendor/autoload.php';

use Monei\Model\CreatePaymentRequest;
use Monei\Model\PaymentCustomer;
use Monei\MoneiClient;

// Replace YOUR_API_KEY with your actual MONEI API key
$monei = new MoneiClient('YOUR_API_KEY');

$payment = $monei->payments->create(
  new CreatePaymentRequest([
    'amount' => 110,
    'currency' => 'EUR',
    'order_id' => '14379133960355',
    'description' => 'Test Shop - #14379133960355',
    'customer' => new PaymentCustomer([
      'email' => 'email@example.com'
    ]),
    'callback_url' => 'https://example.com/checkout/callback'
  ])
);

// Pass payment ID to your client-side
$paymentId = $payment->getId();
?>

Python

server.py

import Monei
from Monei import CreatePaymentRequest, PaymentCustomer

# Replace YOUR_API_KEY with your actual MONEI API key
monei = Monei.MoneiClient(api_key="YOUR_API_KEY")

payment = monei.payments.create(
    CreatePaymentRequest(
        amount=110,
        currency="EUR",
        order_id="14379133960355",
        description="Test Shop - #14379133960355",
        customer=PaymentCustomer(
          email="email@example.com"
        ),
        callback_url="https://example.com/checkout/callback"
    )
)

# Pass payment ID to your client-side
payment_id = payment.id

The following parameters are required:

• amount positive integer - Amount intended to be collected by this payment. A positive integer representing how much to charge in the (e.g., 100 cents to charge 1.00 USD)
• currency string - Three-letter ISO currency code, in uppercase. Must be a supported currency.
• orderId string - An order ID from your system. A unique identifier that can be used to the payment with your internal system.
• callbackUrl string - The URL to which a payment result should be sent asynchronously.

Check all available request parameters.

Included in the returned Payment object is a payment id, which is used on the client side to securely complete the payment process instead of passing the entire Payment object.

2. Add PayPal to your payment page Client-side

Include monei.js on your checkout page by adding the script tag to the head of your HTML file.

checkout.html

<head>
  <title>Checkout</title>
  <script src="https://js.monei.com/v3/monei.js"></script>
</head>

Add MONEI PayPal Component to your payment page. Create empty DOM node (container) with unique ID in your payment form.

checkout.html

<div id="paypal_container">
  <!-- A MONEI PayPal Component will be inserted here. -->
</div>

Initialize PayPal Component

client.js

// Create an instance of the PayPal component.
const payPal = monei.PayPal({
  paymentId: '{{payment_id}}',
  onSubmit(result) {
    moneiTokenHandler(result.token);
  },
  onError(error) {
    console.log(error);
  }
});

// Render an instance of the PayPal component into the `paypal_container` <div>.
payPal.render('#paypal_container');

note

PayPal Component is also available as a React, Vue, Angular, and Svelte component.

Check the MONEI JS Reference for more options.

3. Confirm the payment Client-side

To complete the payment you need to confirm it using monei.js confirmPayment function.

You need to provide a paymentId (obtained in step 1) and paymentToken generated with PayPal Component. You can also provide additional parameters like customer.email. Check all available parameters.

client.js

// Confirm the payment
async function moneiTokenHandler(token) {
  try {
    const result = await monei.confirmPayment({
      paymentId: '{{payment_id}}',
      paymentToken: token
    });
    // At this moment you can show a customer the payment result
    // But you should always rely on the result passed to the callback endpoint
    // on your server to update the order status
    console.log(result);
  } catch (error) {
    console.error(error);
  }
}

note

As an alternative process you can submit generated paymentToken to your server and then confirm payment on the server-side.

4. Process Webhook Notification Server-side

After the client-side interaction and any necessary background processing, MONEI sends the final, authoritative payment status via an asynchronous HTTP POST request to the callbackUrl you provided in Step 1.

The request body contains the full Payment object in JSON format.

This webhook is the only reliable way to confirm the definitive payment outcome.

Crucially, you must:

1. Verify the MONEI-Signature header included in the request. This confirms the webhook genuinely came from MONEI. See the Verify Signatures guide for implementation details.
2. Return a 200 OK HTTP status code immediately upon receiving the webhook to acknowledge receipt. Any other status code tells MONEI the notification failed.

If MONEI doesn't receive a 200 OK, it will retry sending the webhook.

Once the signature is verified, inspect the status field in the Payment object (SUCCEEDED, FAILED, CANCELED, etc.) to determine whether to fulfill the order or handle the failure.

Before you go live

• Make sure that you are using live (production) mode Account ID and API Key.
• Make sure that you have connected your PayPal business account in MONEI Dashboard.

Common questions

Do I need a PayPal account to accept PayPal?

Yes. You connect your own PayPal Business account from MONEI Dashboard → Settings → Payment methods → Link PayPal Business Account.

Can I refund PayPal payments?

Yes — you can issue full or partial refunds for PayPal transactions.

What is Express Checkout?

Express Checkout shows the PayPal button earlier in the flow (for example on the cart or product page) so customers can check out in fewer steps.