PayPal

Principle of operation

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. If this format is not followed, PayPal rounds 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, affecting transaction precision and financial records.

Guide
Configure PayPal pre-dispute alerts to receive early notifications about buyer complaints and resolve issues before chargeback escalation. 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 v1 report or received PayPal dispute Webhook provides comprehensive information about each dispute. PayPal risk metrics should also be considered to track and Guide
Respond to PayPal disputes with structured case handling, evidence submission, and resolution workflows to reduce costs and protect revenue. manage disputes and chargebacks effectively.

Integration flow

PayPal button initialization params

Expand all

data-color

Description

Color Reference of the PayPal button.

• gold
  PayPal globally recognized gold color, confirmed by research and carefully selected for optimal conversion, enhances your website with PayPal’s renowned recognition and preference.
• blue
  If gold is not suitable for your site, consider using the PayPal blue button, a brand color recognized for fostering a sense of trust and security in the customer experience, as supported by research.
• silver
• white
• black
  If gold or blue does not match your site’s design, consider using the silver, white, or black buttons, which are less attention-grabbing and thus serve as a secondary color alternative.

Default

gold

data-shape

Description

Shape Reference of the PayPal button.

• pill
• rect
• shape

Default

pill

data-label

Description

Label Reference displayed on the PayPal button.

• buynow
  Displays the PayPal Buy Now button and initializes the checkout flow.
• checkout
  Displays the Checkout button.
• paypal
  Displays the PayPal logo.
• pay
  Displays the Pay With PayPal button and initializes the checkout flow.

Default

buynow

data-height

Description

Height Reference of the PayPal button.

Default

By default, the button adapts to the size of its container element.

data-disable-max-width

Description

Disables the maximum width Reference constraint of 750px on the PayPal button, allowing it to expand to the full width of its container.

Default

false

After the payment is made, all information about the payer can be obtained from the updated alternative order Webhook and check order status API v1 response for further processing, including the payer’s email, first name, and last name.

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

PayPal button events params

Expand all

order-started-processing

Description

The event marks the initiation of order processing, signaling the start of the payment process. It lays the foundation for transaction tracking.

The follow-up order-processed event completes the cycle by delivering a status-response with details on the order and transaction, crucial for analytics and customer notifications.

order-approved

Description

Confirms the order’s approval for processing, signaling transaction progression.

order-processed

Description

Marks transaction completion with a status-response detailing the order.

order-already-processed

Description

Indicates an attempt to reprocess an already completed order, aiming to prevent duplicates.

button-ready

Description

Signals that the PayPal button is operational and ready for the customer’s action.

button-error

Description

Alerts to issues with PayPal button rendering or initialization, crucial for troubleshooting.

button-click

Description

Triggered by the customer’s interaction with the PayPal button, useful for tracking engagement.

button-cancel

Description

It occurs when a payment process is cancelled post-initiation.

 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 payment method 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 — usually because the PayPal account has an invalid funding source (no linked card or bank account, or insufficient funds). In some situations, the tokenized 1-click payment flow may be triggered instead 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 in a PayPal sandbox environment to simulate failed transactions and verify that your system handles negative flows 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 follow-up transaction. The resulting token is especially useful for Merchant Initiated Transactions (MITs) in subscription models, allowing automatic recurring billing without requiring the customer’s presence on the site.

Create payment token

To create a payment token via Solidgate, initiate a billing agreement with PayPal that returns a token following a successful customer approval. Set the amount to 0 . This token can be used for follow-up charges.

Required parameters

Expand all

amount

integer

=0

Required

Description

Order amount.

Value

0

Must be zero.

currency

string

3

Required

Description

Three-letter ISO-4217 Wiki currency code.

Additionally, it is imperative to specify currencies for multi-currency subscription-based products, such as in USD and EUR.

Value

EUR

Any valid currency code.

customer_email

string

100

Required*

Description

Customer’s email address.

Mandatory but does not affect payment.

Example

user-one@mail.com

 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

{
  "order": {
    "method": "paypal-vault",
    "amount": 0,
    "currency": "EUR",
    "order_id": "buy_73243.pay_token"
  },
  "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 v1 method. The order-approved event is also duplicated via updated alternative order Webhook , allowing real-time status updates.

Follow-up charges

Make recurring charges following the recurring API v1 billing procedures. Comply with all validation and requirements set.

 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 customers they can split payments.
• Checkout page: Clearly surface BNPL as a payment option.

Integration flow

To enable:

In Solidgate Hub and Guide
Configure webhook endpoints to receive real-time event notifications for payment status changes, subscription updates, and refund outcomes. webhooks, a BNPL transaction appears as a standard PayPal payment. BNPL details remain within PayPal and are not flagged separately.