Principle of operation

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

Additionally, 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. The PayPal dispute API report provides comprehensive information about each dispute. Guide
Effectively managing PayPal disputes and chargebacks. PayPal risk metrics should also be considered to track and manage disputes and chargebacks effectively.

Integration flow

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

Set the height option between 25 and 55 to customize the button height.

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 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 customer’s action.

button-error

Description

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

button-click

Description

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

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.

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.

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.

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 .

Required parameters

Expand all

amount

integer

=0

Required

Description

Order amount.

Value

0

Must be zero.

currency

string

3

Required

Description

The three-letter ISO-4217 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
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 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 webhook, allowing real-time status updates.

Subsequent charges

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

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