PayPal
Get started
Sign In
PayPal
PayPal provides a global online payment platform
PayPal API 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


  1. Order initiation: Creates an order in the system and returns a JavaScript URL to invoke the PayPal button.
  2. PayPal button integration: Insert the provided script into your website's HTML where the PayPal button should appear.
  3. Payment process: Customers select PayPal at checkout, link bank accounts or cards, or use their PayPal balance for transactions.
  4. 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


  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 process by sending an init request API and then integrate the PayPal button using the provided script_url.
  4. Customize the PayPal button appearance using the initialization parameters provided to match your website’s design and branding.

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

The decline 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, a customer might opt to pay via a card or select an alternative payment method instead of 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.

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

 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.

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.
 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:
Guide
“Invalid data” code message is used for validation errors, with the reason for the validation triggering specified in the body (object error) of the response. Also, the code message “Order not found” is used as a decline on orders in case of API response to request on non-existent order.
2.01 General reason
: If the request for zero-amount is declined.
Guide
An error occurred due to the processor not supporting the requested API method.
5.10 Processor does not support requested API method
: If your payment provider doesn't support this method.

Dispute management

PayPal’s dispute resolution process starts with an internal inquiry. Customers file complaints directly through PayPal, allowing merchants to resolve issues directly within 20 days. If the dispute is not resolved, it can escalate to a lawsuit, which involves PayPal mediation when direct communication between the parties ceases and evidence is required.

Merchants also face pre-chargeback alerts, which allow them to respond proactively within 20 hours. Additionally, merchants must deal with external Guide
Manage chargebacks effectively to minimize losses and protect your business.
chargebacks
initiated by the customer’s bank, requiring them to dispute by providing proof of service.

In all of these cases, effective communication and prompt provision of the necessary documentation are crucial for merchants to protect their interests and minimize financial losses.
Internal inquiry Customers can file disputes directly with PayPal. Merchants have seven days to address the issue or 20 days to respond if the dispute is internal. If unresolved, customers can submit a formal claim within 20 days. Contacting the customer via chat in the admin panel is advisable, as PayPal can view these interactions.
Transaction dispute A formal notice from PayPal encourages customers to contact merchants directly. Merchants can use PayPal’s chat in the Solidigate HUB. However, disputes resolved in the merchant's favor can still lead to external chargebacks.
Pre-chargeback alert These alerts indicate potential chargebacks, giving merchants a 20-hour window to issue refunds and respond proactively. Merchants can provide evidence within this window to contest a chargeback once PayPal receives it.
Chargeback If disputes escalate, merchants have 10 days to provide evidence against the claim. Issuing a refund at this stage can prevent further chargebacks.
External chargeback Initiated by the customer’s bank, this requires a merchant response within 10 days. There is no possibility of messaging the customer, but merchants can contest by providing proof of service delivery.
Disputes representment By representing disputes, merchants can protect their business reputation, recover lost revenue, avoid additional fees, and improve customer satisfaction. Necessary documentation may include proof of fulfillment, refund, or other relevant evidence.

Reasons PayPal refuses refunds:

  • External chargeback: An external chargeback prompts the end-user to contact their bank directly. PayPal may temporarily hold the disputed amount pending resolution via the PayPal Resolution Center. Resolving the dispute usually involves issuing a full refund to the customer, thereby closing the case.
  • Insufficient funds: The merchant's PayPal account lacks the necessary funds for a refund. New PayPal users need to process more transactions to ensure a sufficient balance.
  • Suspicious activity: PayPal has flagged the refund request due to unusual activity. In such cases, it is advisable to contact PayPal support.

Maintaining detailed transaction records and effective customer communication is key to successfully navigating this process. Understanding Guide
Gain a better understanding of chargebacks nature and manage them effectively.
chargeback reason codes
and prevention strategies is essential to minimizing disputes and maintaining a healthy chargeback ratio, which should not exceed 0.9% of sales.

Additional info for refund handling

Full refunds are already prohibited if a dispute is open. The same logic should be applied to partial refunds if the dispute status is:

  • WAITING_FOR_BUYER_RESPONSE
  • OPEN
  • WAITING_FOR_SELLER_RESPONSE
  • UNDER_REVIEW

Full and partial refunds should be allowed if the disputed status is RESOLVED.

Dispute reasons and required evidence

  • MERCHANDISE_OR_SERVICE_NOT_RECEIVED
    Provide proof of fulfillment, such as tracking numbers or digital product delivery confirmation.
  • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED
    Offer descriptions, item URLs, return policies, and other relevant product information.
  • UNAUTHORIZED
    Supply proof of fulfillment, such as order logs or buyer communications.
  • CREDIT_NOT_PROCESSED
    Present proof of refund and communications regarding credit issuance.
  • DUPLICATE_TRANSACTION
    Show evidence for original and duplicate transactions.
  • INCORRECT_AMOUNT
    Provide documentation of the correct amount and refund IDs.
  • PAYMENT_BY_OTHER_MEANS
    Demonstrate proof of payment through alternative means.
  • CANCELED_RECURRING_BILLING
    Show evidence of subscription cancellation and associated logs.

General recommendations for representment

  • Provide clear, detailed transaction information.
  • Maintain politeness and respect in communications.
  • Keep detailed records of all related communications.
  • Supply tracking information and product details.
  • Respond promptly to buyer inquiries.
  • Document previous disputes.
  • Be objective and factual in representations.
  • Prepare for additional information provision if escalated.

The dispute defense document is vital for PayPal dispute resolution, allowing merchants to defend themselves against customer claims such as chargebacks. It should include proof of fulfillment, transaction details, message logs, product description, and other relevant evidence.

The file size limit is 50 MB per request. Acceptable file types for uploading include JPG, JPEG, GIF, PNG, and PDF formats.