PayPal

PayPal provides a global online payment platform

PayPal Website is a globally renowned online payment system, established in 1998, offering secure and diverse payment options in over 200 countries. PayPal supports transactions in numerous currencies and is especially popular for its user-friendly interface and the protection of sensitive financial information. Countries Global

Currencies Multiple (including AUD, BRL, CAD, 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

Chargeback Yes

Principle of operation

Order initiation: Creates an order in the system and returns a JavaScript URL to invoke the PayPal button.
PayPal button integration: Insert the provided script into your website's HTML where the PayPal button should appear.
Payment process: Customers select PayPal at checkout, link bank accounts or cards, or use their PayPal balance for transactions.
Subsequent payments:
- One-click: Tokenizing PayPal payment information in the first transaction allows customers to complete subsequent payments with just a tap of the pay button.
- Recurring: Tokenization process extends to Guide
  Create and maintain a stable and healthy business subscription model. subscriptions models, where a PayPal payment token handles recurring transactions.

For Currencies COP, CRC, HUF, LAK, RSD, and TWD, merchants should pass the integer value of the amount with two zeros at the end (for example, XXXX00, which will be transferred to PayPal as XXXX.00).

This approach ensures the accuracy of the payment amount transferred to PayPal. If this format is not followed, the payment amount will be rounded up (for example, from XXX0.99 to XXX1.00 and from XXX0.01 to XXX1.00), potentially affecting the transaction’s precision.

Integration flow

Obtain PayPal sandbox credentials from your Account Manager or by requesting Solidgate support team. Follow the detailed documentation after receiving the API keys for the PayPal sandbox environment. Initiate the payment process by sending an init request API and then integrate the PayPal button using the provided script_url.

These parameters provide flexibility to match the button with your website’s design and branding. You can customize the PayPal button appearance using the following initialization parameters:

PayPal button initialization params

Expand all

data-label

Description

Button label.

Value sample

buynow(default)
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.

data-color

Description

Button color.

Value sample

gold (default)
Our 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 isn’t suitable for your site, consider using the PayPal blue button, a brand color recognized for fostering a sense of trust and security in the user experience, as supported by research.
silver
white
black
If gold or blue doesn’t 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.

data-shape

Description

Button shape.

Value sample

pill (default)
rect

data-height

Description

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

Value sample

To customize the button height, set the height option to a value between 25 and 55.

The width of your button container element must be sufficient to accommodate the payment buttons in your layout. This is particularly important for a horizontal button layout.

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 subsequent order-processed event completes the cycle by delivering a status-response with details on the order/transaction, crucial for analytics and user 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 user action.

button-error

Description

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

button-click

Description

Triggered by user interaction with the PayPal button, useful for tracking engagement.

button-cancel

Description

Occurs when a payment process is cancelled post-initiation.

PayPal button initialization sample

 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


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

FAQ

Expand all

Decline Code 0.02 (Order expired)

Scenario:

Order creation: PayPal orders are generated with each successful initiation request for the PayPal button.
Customer payment choice: Sometimes, a customer might opt to pay via a card or select an alternative payment method instead of PayPal.

The decline code , helps in identifying cases where an order was created due to PayPal button initialization but no attempts were made to pay via PayPal.

PayPal button activity duration:

Time limit: The PayPal button remains active for one hour post-initialization.
Inactivity result: If there are no attempts to make a payment via PayPal within this hour, a declined order with the 0.02 decline code is issued.

An example of how such an order appears can be found in our admin panel, specifically in HUB.

Why is PayPal refusing refund transactions?

External chargeback: An external Guide
Manage chargebacks effectively to minimize losses and protect your business. chargeback received prompts the end-user to directly contact their bank. PayPal may temporarily hold the disputed amount pending resolution via the PayPal Resolution Center. Usually, resolving the dispute involves issuing a full refund to the customer, thereby closing the case.
Insufficient funds: The merchant's PayPal account lacks the funds necessary for a refund. New PayPal users need to process more transactions to ensure sufficient balance.
Suspicious activity: PayPal has flagged the refund request due to unusual activity. Contacting PayPal support is advisable in such cases.

Billing agreement

A billing agreement is a contract between the end user and your platform. It grants you permission 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 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 a payment token

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

This token can be used for subsequent charges.

Required parameters

Expand all

amount

integer

Required

Description

Order amount.

Value

0

Must be zero.

currency

string

Required

Description

The three-letter ISO currency code under ISO-4217.

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

The customer’s email address.

Mandatory but does not affect payment.

Example

user-one@mail.com

Request format

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


POST https://gate.solidgate.com/api/v1/init-payment
Merchant: {{...}}
Signature: {{...}}

{
  "payment_method": "paypal-vault",
  "amount": 0,
  "currency": "EUR",
  "order_id": "buy_73243.pay_token",
  "customer_email": "user-one@mail.com",
  "ip_address": "109.234.2.87",
  "order_description": "obtain pay token",
  "platform": "WEB"
}

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

Response format

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
  "order": {
    "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 will be rendered on the page for payment. Once the user authorizes the payment, the event contains the order and customer information.

Event handling script

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 adheres to 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 will also be duplicated via webhook, allowing real-time status updates.

Importantly, save order: token for future recurring payments.

Subsequent charges

Execute recurring charges following the prescribed methodology outlined in Solidgate’s documentation for standard recurring API billing procedures.

Use the previously obtained payment token to initiate the transaction.

Request format

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


POST https://gate.solidgate.com/api/v1/recurring
Merchant: {{...}}
Signature: {{...}}

{
  "token": "435ft34f5345gh34f5h34g5f3h4",
  "product_id": "faca5fc6-3160-4444-84fe-403199ca07d3",
  "order_id": "buy_73243",
  "customer_email": "user-one@mail.com",
  "ip_address": "109.234.2.87",
  "order_description": "package purchase",
  "platform": "WEB"
}

Error сodes:
: If the request for zero-amount is declined.
: If your payment provider doesn't support this method.

Access to API

Learn to authenticate API requests and fix validation errors effectively.

Payments

Explore diverse payment options for a seamless, secure transaction experience.

Testing

Simulate payments to test your integration before launching in production.