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 user-friendly interface and protection of sensitive financial information. Payment type Wallet

Payment flow Redirect

Availability API / 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 via an init payment API request, or the merchant integrates the PayPal button in the payment Guide
    Understand how to integrate the payment form into your product.
    form
    , Guide
    Comprehensive guide for personalizing your payment page.
    page
    , or generates a payment Guide
    Use payment link to sell online without an integration.
    link
    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 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.

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.

We no longer display 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, we returned such orders in the created Guide
Efficiently manage and track alternative payments with real-time updates.
status
created and transferred them to Declined (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.

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>

Handling error code

The error code Guide
The payment was not completed within the allocated timeframe, leading to order expiration.
0.02 Order expired
, helps in identifying cases where an order was created due to PayPal button initialization but no attempts were made to pay via PayPal.

  • Order creation: PayPal orders are generated with each successful initiation request for the PayPal button.
  • Customer payment choice: Sometimes, customers pay via card or select an alternative payment method instead of PayPal.
PayPal button activity duration
  • Time limit: PayPal button remains active for seven days post-initialization.
  • Inactivity result: If there are no attempts to make a payment via PayPal within this period, a declined order with the 0.02 error code is issued.

PayPal Guide
To test failed payments in the sandbox set the API to USD and trigger errors.
testing
in a sandbox environment enables the simulation of failed transactions, helping ensure your system handles 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 a 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
11
12
13
14
POST https://gate.solidgate.com/api/v1/init-payment
Merchant: {{...}}
Signature: {{...}}

{
  "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",
    ....
  },
  "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 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 will also be 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 methodology outlined in Solidgate’s documentation for standard 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
12
13
14
15
POST https://gate.solidgate.com/api/v1/recurring
Merchant: {{...}}
Signature: {{...}}

{
  "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
12
13
14
15
POST https://gate.solidgate.com/api/v1/recurring
Merchant: {{...}}
Signature: {{...}}

{
  "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"
}
Error codes
Guide
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.
2.02 Invalid amount
: If the request with zero-amount is declined.
Guide
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.
3.11 Recurring payment cancelled
: If the subscription or 1-click payment is declined.
Guide
The error occurs when the processor does not support the requested API method.
5.10 Processor does not support requested API method
: If your payment provider doesn't support this method.

Looking for help? Contact us
Stay informed with Changelog