Leanpay Gateway configuration

1. Log in to the Leanpay Gateway panel for the desired environment
2. Go to the Company section
   1. 
3. Scroll to the Development section
   1. Set the API URL to:
      1. https://extapp.leanpay.si/callback/webhook
   2. Set the Secret Word and note it down
   3. 

This API URL is essential for synchronizing order and payment status updates between Leanpay and Shopify. Incorrect configuration may lead to orders becoming stuck in an unresolved state.

Shopify Application Installation and Setup

1. Visit the Shopify integration endpoint at – https://extapp.leanpay.si
2. Enter your Shopify store URL –
   1. 
   2. You will be redirected to Shopify, to the application installation screen
      1. 
3. Once the application is installed, you’ll get redirected to the configuration view.
   1. 
   2. The API Key is available in the Leanpay Gateway panel under Company → Development.
   3. The API Secret corresponds to the “Secret Word” defined during the gateway configuration.
   4. The Default Environment will be utilized in cases where the target country doesn’t have a matching environment.
   5. The Mode determines which Leanpay API endpoint will be used. Don’t use “Sandbox” in a Production setting, but if you must, ensure the Payment Method has “Test Mode” enabled. (See – 7.)
4. Once saved, the Leanpay payment method will be activated.
   1. 
5. After completing the configuration, go to Settings → Payments → Add payment method.
   1. 
6. Search for Leanpay (by provider), and select it from the available options.
   1. 
7. Proceed to configure the payment method settings.
   1. 
   2. The test mode setting doesn’t determine whether the application communicates with Leanpay’s production or sandbox environment. It’s entirely for Shopify visibility and processing purposes.
      1. Disable Test mode for production use.
      2. Ensure the selected environment corresponds with the configured API key and secret in the application settings.
8. Once configured, the Leanpay payment method will be available during checkout.
   1. 

Shopify Refunds/Disputes

For detailed information on dispute handling, please refer to the official Leanpay documentation.

1. When issuing a refund for a paid order, it is essential to refund the full amount of the original payment. Partial refunds are not supported, as they are not treated as traditional refunds within this integration and may lead to technical issues in Shopify.
   1. If the refund amount does not exactly match the total paid, including all items and shipping costs, the request will be rejected with an error.
   2. To ensure successful processing, always select all order items and the associated shipping cost when submitting a refund.
   3. 

Important Notes

1. The Leanpay environment is determined based on the customer’s delivery address.
   1. For example, the Slovenian Leanpay service and endpoint will only be used when the delivery address is in Slovenia and the corresponding configuration is provided.
      1. 
      2. If the endpoint configuration (API Key and Secret) is removed and saved, the Leanpay payment method will be disabled for the corresponding environment.
   2. If no matching environment for the destination is available, the configured fallback environment will be used for API calls.
2. All configured environments must align with the selected mode—either all in production or all in sandbox.
   1. Using mismatched credentials (e.g., production API keys with sandbox mode enabled) will result in misconfigured payment methods that will fail to function correctly for the corresponding destinations or environments.
3. The Secret Word is used to authenticate incoming webhook requests from the Leanpay Gateway, ensuring their integrity and origin. Ensure this value exactly matches the configuration in the Leanpay Gateway panel; otherwise, order and payment status updates will fail.
4. For technical reasons, the Leanpay application automatically performs currency conversion when the currency provided by Shopify does not match the expected currency of the target environment (e.g., Slovenia and Croatia require EUR, Romania requires RON).
   1. To avoid discrepancies, ensure that your Shopify store is configured to use the correct currency based on the customer’s shipping destination. Otherwise, the price displayed during Shopify checkout may differ from the amount shown on the Leanpay payment page.
   2. The application-layer currency conversion uses the most up-to-date exchange rates available, which may technically be more accurate than those provided by Shopify. However, this can still lead to visible price differences for the customer during checkout.
5. Uninstalling the Leanpay app from your Shopify store will result in the permanent loss of all store-related data, including the base store connection, API configurations, and any linked records such as transaction logs or webhook history.
   1. It is strongly advised not to uninstall the app if there are unprocessed transactions or pending orders. Reinstalling the app will not restore previously handled transactions, as these are managed independently from Shopify and the Leanpay Gateway server.
   2. If you need to temporarily disable the payment method, it is recommended to clear the API keys in the configuration and save the changes. This will keep webhook functionality intact while preventing the Leanpay payment option from appearing at checkout.
6. Currently, a single Leanpay environment does not support sending webhooks to multiple stores. For example, if Leanpay is integrated with both Magento and Shopify, webhook delivery cannot be configured for both platforms simultaneously.
   1. If your setup involves multiple stores using the Leanpay payment method, please contact Leanpay support for further guidance.