Skip to main content
Webhooks allow your system to receive real-time notifications from smatvirtual whenever a transaction occurs. Our system uses a Bulk Payload architecture to ensure high throughput and reliability, especially during high-traffic tournament events.

​
Configuration

  1. Log in to the smatvirtual Merchant Dashboard.
  2. Navigate to the Webhook Settings section.
  3. Enter your listener URL and save the changes.
  4. You can enable receiving webhooks for specific event types to a specific URL only, by checking the checkbox for the seperate webhook URL field.

​
Event Types

All events share a similar payload structure but represent different financial movements.
EventDescription
charge.bulk.debitStandard game entry or stake deduction.
charge.bulk.creditWinnings distribution at the end of a game round.
tournament.bulk.creditFlagship Engine: Bulk reward distribution for tournament winners.
charge.debit.refundReversals for failed transactions or Retention Refunds.

​
Payload Structure

Every request sent to your webhook URL will follow this bulk format. Even if there is only one transaction, it will be sent inside an array (bulkData) to maintain consistency.
JSON
{
  "event": "charge.bulk.debit",
  "bulkData": [
    {
      "playerId": "string",
      "roundId": "string",
      "sessionId": "string",
      "gameName": "string",
      "status": "PENDING | ENDED",
      "transactionId": "string",
      "stakeAmount": 10.0,
      "amountWon": 0,
      "metadata": "optional_string"
    }
  ]
}

​
Field Definitions

  • transactionId: A unique ID for the specific transaction. Required for idempotency checks.
  • status: PENDING if the game round is ongoing; ENDED if the round is finalized.
  • stakeAmount: The amount to be deducted (in debits) or the original bet (in credits).
  • amountWon: The amount to be added to the player’s wallet.

​
Specialized Refund Logic

The charge.debit.refund event is unique to smatvirtual and is triggered in two specific scenarios:
  1. Technical Anomalies: If a debit cannot be validated or a system error occurs, a refund is issued to ensure player fairness.
  2. Retention Strategy: To enhance player satisfaction, our system automatically triggers a refund if a player suffers five (5) consecutive losses within a single session.

​
Response Requirements

Your server must acknowledge the webhook by returning an HTTP 200 or 201 status code.
Status CodeMeaning
200 OKEvent received and processed successfully.
201 CreatedEvent acknowledged.
Any other codesmatvirtual will consider this a failure and attempt retries.
{
  "status": 200,
  "message": "processed"
}
If your system is not ready to process the transaction immediately, it is better to return a 200 OK with a “pending” message than to return an error. This prevents unnecessary retry attempts.

​
Best Practices & Security

Always store the transactionId. If you receive a webhook with an ID you have already processed, return 200 OK immediately without adjusting the player’s balance a second time.
Your webhook should respond within 2 seconds. If your wallet processing takes longer, acknowledge the webhook first and process the transaction in the background.
For enhanced security, ensure that your webhook endpoint only accepts traffic from smatvirtual’s authorized IP addresses.
Need to test? Use a tool like Webhook.site or Ngrok during development to inspect the raw payloads sent from the smatvirtual dashboard.