Welcome to the Lopay Partner API Getting Started Guide! This guide will walk you through the basic steps to start integrating with the Lopay Partner API, whether you're acting as a platform facilitating payments for your customers or taking payments for your own business.Important notes#
Always send the header x-region in all requests you make to the Partner API to ensure your requests get routed correctly to the right region. Omission of the x-region header will route requests based on the identified client IP address.
Lopay Partner API keys are region locked.
Prerequisites#
Before you begin, ensure you have the following:Your Lopay Partner API key. You’ll need this key to authenticate your requests to the Lopay API.
Getting Started Steps#
1. Register Lopay Merchant Account#
Depending on your business model, you’ll need to register a Lopay merchant account:As a Platform: Create a Lopay merchant account for each of your customers. This ensures that any payments processed via a payment link are paid directly to your customer. Refer to the "Register a New Merchant Endpoint" section for details on how to accomplish this.
For Your Own Business: If you're only accepting payments for your business, create a single Lopay merchant account for yourself. You’ll use the merchant ID associated with this account in the x-merchant-id header when creating payment links.
We can link your existing Lopay merchant account to your Partner entity if you already have an account in production. If you would like this performed, please contact your Lopay representative.You will still need to create a new merchant account within the staging environment.
2. Complete Merchant Onboarding#
Merchants must complete Stripe's onboarding before being able to take any form of payment. This can be done via the Lopay app, or through the merchant onboarding link (see Get merchant onboarding link for API documentation).The staging environment accepts mock details, and has functionality to provide mock documents for certain steps.Whilst merchant onboarding is usually quick in production, sometimes it can take longer to complete for some merchants. If a merchant is struggling with onboarding, please reach out to Lopay's support.
3. Create a Payment Link#
Once your merchant account is registered and fully onboarded, you can create payment links. Please see Create a new payment link for API documentation.Having issues creating payment links? Ensure that the merchant has fully completed onboarding.
In some cases Lopay can restrict a merchants ability to take payments. This could be due to suspected fraud, terms of service violations, or other reasons. Lopay is unable to provide details in these cases, and the merchant should contact Lopay's support team for assistance.If you experience this behaviour in the staging environment, please notify your Lopay representative for assistance.
4. Send the Payment Link#
After creating the payment link, you can send it to your customers:Using the Lopay Partner API: Use the "Send Payment Link" endpoint to send the payment link directly to your customer via email and/or SMS.
Manual Sending: Alternatively, you can retrieve the link property from the API response and send it manually via your preferred communication channel.
theme query parameter. (Allowed values: light, dark)5. Subscribe to Webhooks#
To receive notifications about payment events, you'll need to subscribe to webhooks. You can do this by either:Using the available Lopay Partner API endpoints to configure your webhooks programmatically.
Using the Lopay Webhook Portal for a more user-friendly interface.
6. Fetch and Refund Payments#
Fetching and refunding payments is not enabled by default for partners. If you’re interested in enabling this feature, please contact your Lopay representative.
To view payment details, see Get existing payment API documentation. This returns information such as the payment type, amount, taxes, and current status. To issue a refund, see Refunds a payment API documentation. Ensure the amount (in minor units) is a negative value. Refunds can be processed in full or partially, depending on your integration and the payment type. Only payments made via a payment link or subscription are eligible for refunds.
You're now ready to start accepting payments with the Lopay Partner API! For more advanced features and details, please refer to the full Lopay Partner API documentation. 