How can I use OxaPay in a custom platform or mobile app?

For mobile apps or custom platforms, you’ll integrate directly with OxaPay’s API. The flow is similar to the e-commerce integration, but you might use OxaPay’s white-label mode for a seamless in-app experience. Here’s a step-by-step guide:

1. Setup OxaPay API in your app backend: First, obtain your Merchant API key from the dashboard and ensure your backend server can communicate with OxaPay’s API. You’ll be making API calls to create payments and handle callbacks.

   ---

2. Create a payment request via API: When a user in your app initiates a purchase or payment, your backend calls OxaPay to generate a payment. You have two options:

   • Invoice Link Method: Use the Generate Invoice endpoint to get a payment URL. This is simple – OxaPay returns a link which you can open in a webview or the device’s browser for the user to pay.

   • White-Label Method: For a more native experience, use the Generate White Label endpoint. This returns the payment details (crypto address, amount, etc.) without a hosted URL. Your app can then present these details in its own UI. For example, you can show a QR code and address inside the app.

3. ---

   Prompt the user to pay in-app: If using the white-label service, display the cryptocurrency address and QR code in your app’s interface for the user to scan or copy. The user will send the required crypto using their wallet (you can deep-link to popular wallet apps or just instruct them to use their wallet). If using the invoice service, simply load the OxaPay checkout URL in an in-app browser; the user will see OxaPay’s payment page and complete the payment there.

   ---

4. Handle real-time payment updates: Your backend should set up a webhook endpoint to receive OxaPay callbacks. As soon as the user’s transaction is detected, OxaPay will POST a JSON payload to your callback URL with details like payment status, amount, currency, etc. The status will update from “paying” to “paid” once the payment is fully received (this might happen within seconds or minutes, depending on the network).

   ---

5. Validate and confirm the payment: Upon receiving the callback, verify the HMAC signature using your Merchant API key to ensure the data is from OxaPay. Check that the status in the data is paid (do not consider the payment final if the status is only “paying”).

   ---

6. Update the app UI and fulfill the purchase: Once you’ve confirmed a payment is paid, update the user’s status in your app (e.g. unlock premium features, mark an order as paid, or credit their account balance). If you used a redirect or webview that took the user out for payment, make sure to bring them back to the app and show a “Payment successful” message or similar. For white-label flows, you can actively poll or use the webhook to know when to show confirmation in-app. At this point, the flow is complete – the user’s payment is done and you have been notified securely.

   ---

Note: Using the white-label service keeps the entire experience in your app’s branding (the user never sees our platform, even though OxaPay is powering the transaction behind the scenes). This is great for user experience. Just remember that security is key: always use HTTPS for webhooks and verify the signatures. Testing in OxaPay’s sandbox environment is recommended before going live to ensure your integration works smoothly end-to-end. Once set up, your custom app can accept crypto payments just as easily as any web application.