PayPal
Get in touch
Sign in
PayPal
PayPal provides a global online payment platform

PayPal is a globally renowned online payment system established in 1998. It offers secure and diverse payment options in over 200 countries.

PayPal supports transactions in numerous currencies and is especially popular for its customer-friendly interface and protection of sensitive financial information.

Payment type Wallet

Payment flow Redirect

Integration type API Reference / Payment Form / Payment Page / Payment Link

Countries Global

Currencies Multiple ( currencies Reference AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD, USD)

*see processing notes for specific currencies in the principles of operation.

Recurring Yes

Refund Yes

Partial refunds Yes

Multiple partial refunds Yes

Chargeback Yes

Principle of operation


  1. Order initiation
    The system creates an order for customers to select PayPal.
  2. Selection at checkout
    Customer select PayPal at checkout, link bank accounts or cards, or use their PayPal balance for transactions.
  3. Authentication and authorization
    Customer authorize payment through PayPal account or balance.
  4. Payment initiation
    Tokenizing PayPal payment information during the first transaction allows a customer to complete future payments with a single tap. The tokenization process also supports Guide
    Explore Solidgate subscriptions for seamless recurring customer payments.
    subscriptions
    models by handling recurring transactions with a PayPal payment token.
  5. Payment confirmation
    Payment is completed through PayPal. Customer authorize payment through their PayPal account or balance.
  6. Merchant notification
    Merchant is notified and tokenizes PayPal details for future use.
Payment page example Payment page example Payment page example

For Currencies such as COP, CRC, HUF, LAK, RSD, and TWD, you are required to submit the amount as an integer with two zeros at the end, for example, 10000 or 1226800. This ensures that the amount transferred to PayPal is correctly formatted and avoids rounding issues.

By adhering to this format, you ensure that PayPal processes the exact amount as intended. If this format is not followed, PayPal round the amount, which could lead to inaccuracies. For example, an amount of XXX0.99 may be rounded to XXX1.00, or XXX0.01 may be rounded up to XXX1.00. This potentially affects the transaction’s precision and leads to discrepancies in financial records.

Guide
Scale your business with PayPal's pre-dispute alert.
PayPal prevent alerts
offer a proactive way to manage disputes, notifying merchants of potential chargebacks with a 20-hour window to issue refunds or contest claims. Furthermore, PayPal dispute API report or received PayPal dispute Webhook provides comprehensive information about each dispute. PayPal risk metrics should also be considered to track and Guide
Improve the dispute resolution process to reduce costs and maintain stability.
manage disputes
and chargebacks effectively.

Solidgate no longer displays PayPal orders in Guide
Detailed transaction insights for APMs with customer data.
APM report
and Guide
Optimize your product and payment management with Solidgate HUB.
HUB
where a button was shown, but no payment occurred. Previously, Solisgate returned such orders in the created Guide
Efficiently manage and track alternative payments with real-time updates.
status
created and transferred them to declined Guide
The payment was not completed within the allocated timeframe, leading to order expiration.
0.02
later.

Integration flow


  1. Obtain PayPal sandbox credentials from your Account Manager or request the Solidgate support team.
  2. Follow the detailed documentation after receiving the API keys for the PayPal sandbox environment.
  3. Initiate the payment by init payment API request to create the order, or add the PayPal button to your payment Guide
    Understand how to integrate the payment form into your product.
    form,
    set it up as a payment option on the payment Guide
    Comprehensive guide for personalizing your payment page.
    page,
    or generate a payment Guide
    Use payment link to sell online without an integration.
    link
    with PayPal as the selected method.
  4. Customize the appearance and behavior of the Guide
    Activate and customize the PayPal button on your payment form to ensure a smooth customer experience.
    PayPal button
    on payment form by setting parameters such as color, shape, and label.

After the payment is made, all information about the payer can be obtained from the updated alternative order Webhook and check order status API response for further processing.

It provides key information, such as the payer’s email, first name, and last name, crucial for identifying the payer in the transaction process.


Subscribe to these PayPal button events to track the transaction status:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<div id="paypal-button"></div>
<script>
  var elem = document.getElementById('paypal-button');
  elem.addEventListener('order-started-processing', function (e) {
    console.log('order-started-processing',e);
  }, false);
  elem.addEventListener('order-started-approved', function (e) {
    console.log('order-approved',e);
  }, false);
  elem.addEventListener('order-processed', function (e) {
    console.log('order-processed',e);
  }, false);
  elem.addEventListener('order-already-processed', function (e) {
    console.log('order-already-processed', e)
  }, false);
  elem.addEventListener('button-ready', function (e) {
    console.log('button-ready', e)
  }, false);
  elem.addEventListener('button-error', function (e) {
    console.log('button-error',e);
  }, false);
  elem.addEventListener('button-click', function (e) {
    console.log('button-click',e);
  }, false);
  elem.addEventListener('button-cancel', function (e) {
    console.log('button-cancel',e);
  }, false);
  
  <script type="text/javascript"
          src="https://gate.solidgate.com/widget/9d81b91uisf234bhjb23jhb562cc5101"
          data-label="checkout"
          data-color="blue"
          data-shape="rect"
  >
  </script>

Handle PayPal errors

Specific errors may occur when a PayPal payment attempt using a PayPal button fails.

  • Guide
    The payment was not completed within the allocated timeframe, leading to order expiration.
    0.02 Order expired

    This error occurs when an order is created during PayPal button initialization, but no payment attempt is made. PayPal orders are generated with each successful initiation request for the PayPal button, but customers may choose to pay via card or select an alternative payment method instead of PayPal. The PayPal button remains active for 7 days. If no PayPal payment attempt is made during this time, the order is automatically declined with the 0.02 error code.
  • Guide
    This error indicates an issue with the transaction amount, which may be incorrect or exceed allowable limits.
    2.02 Invalid amount.

    The request with a zero-amount payment is declined. It can be triggered by various factors, encompassing incorrect input, transaction limits set by the acquirer or card issuer, or restrictions on specific card types such as prepaid cards.
  • Guide
    This error indicates that the next subscription or a 1-click payment using a recurring token via this card is not allowed.
    3.11 Recurring payment

    It occurs when a subscription or 1-click payment is declined. This error indicates that the next subscription or a 1-click payment using a recurring token via this payment method is not allowed and should not be retried.
  • Guide
    An error occurred due to the processor not supporting the requested API method.
    5.10 Processor does not support requested API method

    This error occurs when the processor does not support the requested API method. Make sure you use only supported methods when communicating with the gateway.

Besides the listed errors, there are cases when, after using the PayPal button, the customer is asked to enter payment card details. This usually happens because the PayPal account has an invalid funding source:

  • No card or bank account is linked to the PayPal account
  • Insufficient funds
In some situations, the tokenized 1-click payment flow may be triggered instead. This happens when the customer previously paid with PayPal and an active payment token is available.

Consider Guide
PayPal testing allows you to simulate failed transactions using a sandbox environment, which is useful for ensuring that your system correctly handles various scenarios, including negative flows.
testing
payments in a PayPal sandbox environment to simulate failed transactions. This helps ensure your system can handle negative flows and other scenarios correctly.


Billing agreement

A billing agreement is a contract between the customer and your platform. It permits you to withdraw funds from their account in the future, eliminating the need for them to log into their PayPal account for each subsequent transaction. This streamlines the payment process, ensuring seamless transactions without additional sign-ins.

It is recommended to consult the official PayPal documentation Reference for comprehensive understanding and guidance.

This token is especially useful for Merchant Initiated Transactions (MITs) in subscription models, as it allows for automatic, recurring billing without necessitating the customer’s presence on the site.

This seamless integration offers convenience for both the merchant and the customer, ensuring transactions are smooth and uninterrupted.

Create payment token

To create a payment token via Solidgate, initiate a billing agreement with PayPal that returns a token following a successful customer’s approve, set the amount to 0 .

This token can be used for subsequent charges.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "payment_method": "paypal-vault",
  "order_id": "buy_73243.pay_token",
  "amount": 0,
  "currency": "EUR",
  "order_description": "obtain pay token",
  "customer_email": "user-one@mail.com",
  "ip_address": "109.234.2.87",
  "platform": "WEB"
}

Retrieve the script_url from the response and embed it on the webpage.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "order": {
    "method": "paypal-vault",
    "amount": 0,
    "currency": "EUR",
    "order_id": "buy_73243.pay_token",
    /* other fields omitted */
  },
  "pay_form": {
    "script_url": "https://gate.solidgate.com/widget/5f9f74abec73952652ed964d4efd8.js"
  },
  "transactions": [...]
}

Upon successful script loading, a PayPal button is rendered on the page for payment. Once a customer authorizes the payment, the event contains the order and customer information.

1
2
3
4
5
6
<script>
  var elem = document.getElementById('paypal-button');
  elem.addEventListener('order-approved', function (e) {
  console.log('order-approved', e.detail.data)
}, false);
</script>

Order status can be extracted from e.detail.data, which follows the standard structure of an order status response.

The same data can also be obtained via an H2H check order status API method. The order-approved event is also duplicated via updated alternative order Webhook , allowing real-time status updates.

Importantly, save order token for future recurring payments.

Subsequent charges

Make recurring charges following the recurring API billing procedures, comply with all validation and requirements set.

Use the previously obtained payment token to initiate the transaction.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "payment_method": "paypal-vault",
  "token": "435ft34f5345gh34f5h34g5f3h4",
  "order_id": "buy_73243",
  "amount": 10,
  "currency": "EUR",
  "order_description": "package purchase",
  "customer_email": "user-one@mail.com",
  "ip_address": "109.234.2.87",
  "platform": "WEB"
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "payment_method": "paypal-vault",
  "token": "435ft34f5345gh34f5h34g5f3h4",
  "order_id": "buy_73243",
  "product_id": "faca5fc6-3160-4444-84fe-403199ca07d3",
  "order_description": "package purchase",
  "customer_account_id": "4dad42f808",
  "customer_email": "user-one@mail.com",
  "ip_address": "109.234.2.87",
  "platform": "WEB"
}

Buy Now Pay Later

PayPal’s Buy Now Pay Later (BNPL), also referred to as Pay Later offers, allows customers to split purchases into multiple payments, while the merchant receives the full amount upfront. This improves affordability for customers and drives higher conversion and average order value for merchants.

BNPL is available as part of the PayPal Checkout experience. After selecting PayPal at checkout and logging in, eligible customers are presented with Pay Later options.

PayPal assumes the credit risk and immediately pays the merchant the full purchase amount. The customer then repays PayPal over time based on the chosen installment plan.

Per PayPal compliance guidelines, the Pay Later option should be shown across multiple locations to maximize visibility and eligibility checks:

  • Homepage: Announce the availability of PayPal Pay Later on your store.
  • Product list & product detail pages: Show estimated installment amounts to encourage higher-value purchases.
  • Cart page: Remind users they can split payments.
  • Checkout page: Clearly surface BNPL as a payment option.
BNPL is not supported for subscription-based products. Please use the button with the billing agreement logic instead. For one-time purchases, you can offer BNPL. If your account and the user's account are eligible for BNPL, the BNPL flow will be available.

Key conditions:
  • Do not display both the BNPL and billing agreement buttons on the same page to avoid confusion and potential drops in conversion rates
  • For one-time purchases, BNPL is suitable, but for subscriptions, the billing agreement method should be used instead
    This ensures that recurring payments are managed correctly in the billing agreement logic.
  • Available in only seven countries: Australia, Germany, Spain, France, the UK, Italy, and the USA
    If a non-eligible buyer clicks PayPal, they still reach PayPal, but Pay Later won’t be offered.
  • Minimum payment threshold usually applies, varies by country
  • Localized loan terms differ by country, including interest rates and durations

Integration flow

To enable:

  1. Ensure
  2. Configure distinct channels and credentials for PayPal recurring payments model via billing agreement and PayPal BNPL one-time payment model.
    A single channel cannot serve both flows simultaneously.
  3. Implement UI to show buttons separately from each other, PayPal and PayPal BNPL buttons, using the same integration path as the standard Guide
    Understand how to integrate the payment form into your product.
    payment form,
    set it up as a option on the Guide
    Comprehensive guide for personalizing your payment page.
    payment page,
    or generate a Guide
    Use payment link to sell online without an integration.
    payment link.
  4. Follow PayPal's messaging and placement rules to highlight the Pay Later feature at all stages of the purchase.

In Solidgate HUB and Guide
Subscribe for events so your integration can automatically trigger actions.
webhooks,
a BNPL transaction appears as a standard PayPal payment. BNPL details remain within PayPal and are not flagged separately.


Looking for help? Contact us
Stay informed with Changelog