API Intergration
Webhooks Overview
Midasbuy provides Webhooks and Order APIs for developers to integrate.
wehhook sample
- user validate
- payment notification
After the user enters their user_id and selects a server_id, Midasbuy initiates the user validation webhook. The webhook request will include the user_id and server_id parameters. Developers can leverage this information to determine whether the user meets the necessary recharge conditions based on their user_id and the targeted server_id.
If the conditions are not met, developers can return the corresponding error response. Alternatively, if developers expect Midasbuy to perform additional validation based on the user's information, they can send back the specific conditions to be checked to Midasbuy. In this case, Midasbuy will execute further validation against the provided conditions.See region lock
When Midasbuy receives successful payment results from payment channels like PayPal, it will send a payment successful notification to the developer's server. Upon receiving and verifying the signature of this notification, developers can proceed to provide the corresponding product to the user. However, if the product cannot be delivered temporarily due to reasons such as the user being offline, developers can return an appropriate error to Midasbuy. In such cases, Midasbuy will continue to push the notification until the product is successfully delivered. Developers should refer to the API section for detailed strategies and best practices regarding notification handling and error management.See introduction
When the order status changes, a correspondingPayment Order Notificaiton will be sent, and the status will be represented by the "order_status" field. Possible values include:
| Order Status | Description | Developer Action |
|---|---|---|
| Created | User created order | Record order creation |
| Paid | Order paid successfully | Credit the purchased items to the user's account |
| Finished | Merchant delivered successfully | Record successful delivery for reconciliation or customer service purposes |
| Refunded | User refunded successfully | Remove the items from the user's account |
The following diagram shows the main transitions flow：
Additionally, if the user's purchase includes free bonus items or promotions, Midasbuy will send a separate promotion notification to the developer's server. Developers can find more information on handling these promotion notifications See promotion notification
We also provide an order query API for checking the order. See order query
Webhooks List
To provide a clear understanding of the event flow, Midasbuy categorize events into synchronous and asynchronous based on their impact on the user interface process.
- Synchronous Events
These events require an immediate response, as users will be waiting for the result. If the response fails, the process will be interrupted, and users will not be able to continue. It's important to note that the system will not automatically retry synchronous events after a timeout. Examples of synchronous events include user validation and product validation.
- Asynchronous Events
In contrast, asynchronous events run in the background and don't require users to wait for a response. Payment order notifications and promotion notifications fall into this category. If the call to your server times out, our system will automatically retry the event, ensuring reliable delivery of the notifications.
| name | type | Required/ Optional |
|---|---|---|
| PaymentNotification | Asynchronous | Required |
| ProductValidate | Synchronous | Optional |
| PromotionNotification | Asynchronous | Optional |
| UserValidate | Synchronous | Required |
Set Up Webhooks in Midasbuy Merchant Platform
To enable receiving webhooks:
- Open your instance in Midasbuy Merchant Platform
- click "Instance integration & Game zone" tab and click "Webhook" tab
- In the "Webhook Server" field, specify the URL of your server where you want to receive webhooks, using the format https://example.com. The webhook URLs for sandbox and production are independent and need to be configured separately.
- A secret key to verify webhooks from Midasbuy is generated by default. The keys for sandbox and production are also independent.
Webhooks API Simulation
You can use the Webhooks API simulation page to simulate sending various Webhook events directly to your server. To simplify the process and reduce the need to switch keys, there is no option to input the Webhook private key on the simulation page. Instead, Midasbuy will use the developer's sandbox private key to sign the request. As the developer, you will need to use the Webhook sandbox public key, obtained from the Midasbuy Merchant Platform, to verify the signature.See payment notificat example
It's important to note that the sandbox environment is designed for testing and development purposes, allowing you to thoroughly validate your Webhook integration before deploying it to the production environment. Once you're ready to go live, you'll need to obtain and configure the production Webhook key from the Merchant Platform.
Handling Webhooks
We have provided sample code to help developers better understand the webhook integration process, including the signature verification mechanism, idempotency logic, and other key processes. See buy-api-library