[
{
"title":"Testing",
"link":"https://docs.solidgate.com/payments/testing/",
"text":"Simulate payments to test your integration before launching in production.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/06/icon-customizable.svg"
}
,
{
"title":"Create your payment form",
"link":"https://docs.solidgate.com/payments/integrate/payment-form/create-your-payment-form/",
"text":"Understand how to integrate the payment form into your product.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/06/icon-payments.svg"
}
,
{
"title":"Subscriptions",
"link":"https://docs.solidgate.com/subscriptions/",
"text":"Create and maintain a stable and healthy business subscription model.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/06/icon-global.svg"
}
]
PayPal
API
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
*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
Order initiation: The system creates an order and returns a JavaScript URL to invoke the PayPal button. Before this, the merchant ensures PayPal button integration by inserting the provided script into the website's HTML where the button should appear.
Selection at checkout: Customer select PayPal at checkout, link bank accounts or cards, or use their PayPal balance for transactions.
Authentication and authorization: Customer authorize payment through PayPal account or balance.
Payment initiation: Tokenizing PayPal payment information during the first transaction enables customer to complete future payments with a single tap. The tokenization process also supports
Guide
Create and maintain a stable and healthy business subscription model.
subscriptions
models by handling recurring transactions with a PayPal payment token.
Payment confirmation: Payment is completed through PayPal. Customer authorize payment through their PayPal account or balance.
Merchant notification: Merchant is notified and tokenizes PayPal details for future use.
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.
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
Obtain PayPal sandbox credentials from your Account Manager or request the 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.
Customize the PayPal button appearance using the initialization parameters provided to match your website’s design and branding.
PayPal button initialization params
Expand all
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.
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.
Description
Button shape.
Value sample
pill (default)
rect
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
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.
Description
Confirms the order’s approval for processing, signaling transaction progression.
Description
Marks transaction completion with a status-response detailing the order.
Description
Indicates an attempt to reprocess an already completed order, aiming to prevent duplicates.
Description
Signals that the PayPal button is operational and ready for user action.
Description
Alerts to issues with PayPal button rendering or initialization, crucial for troubleshooting.
Description
Triggered by user interaction with the PayPal button, useful for tracking engagement.
Description
It occurs when a payment process is canceled post-initiation.
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 end user 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 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
.
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.
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 methodology outlined in Solidgate’s documentation for standard
recurring
API
billing procedures.
Use the previously obtained payment token to initiate the transaction.
Error codes:
Guide
The Invalid data code signals validation errors, with the error reason provided in the response body (object error). Similarly, the Order not found code indicates a decline in response to an API request for a non-existent order.
2.01 General reason
: If the request for 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.