This page documents our automatic reconciliation processes for both debit and credit requests that have failed during processing.

Overview

Depending on the operator implementation, when a debit transaction fails due to network issues, timeouts, or server errors, it can leave a transaction in a "hanging" or inconsistent state. It’s important to distinguish that on the Splash side, transactions are consistent and marked failed should a debit failure happen, but the operator side may be more complicated due to round and other game play mechanics.

To resolve this, we run automated reconciliation scripts multiple times a day. These scripts sweep for failed requests and attempt to gracefully reconcile them.

Reconciliation Workflows

Our scripts handle failures differently depending on whether the debit request itself failed, or if the debit succeeded but the subsequent credit failed.

1. Failed Debit Requests

• Triggers: Debit requests that fail on our side due to read timeouts or other 5xx server errors but succeed on client side.

• Reconciliation Action: The script attempts to reconcile these by sending a debit cancellation request (url provided by client in the contribution callbacks field) to reconcile the hanging debit transaction.

  Endpoint

  POST <client_base_url>/debit/cancel
  

  Headers

  Content-Type: application/json
  Authorization: Bearer <jwt-token>
  

  Cancel Debit

  Request Body

  Field	Type	Required	Description
  sessionId	string	Yes	SessionId used in request to contribute
  roundId	string	Yes	Unique transactionId used in request to contribute
  transactionId	string	Yes	Unique id of this debit request
  amount	number	Yes	Amount to withdraw from user wallet
  jackpotId	uuid (string)	Yes	Unique identifier of jackpot user has contributed to
  userId	string	Yes	The JWT token’s sub field from the original contribution call.

  Example Request

  [POST] <client_base_url>/debit/cancel 
  
  {
    "sessionId": "SESS-992834",
    "roundId": "RND-110022",
    "transactionId": "TX-556677",
    "amount": 120.50,
    "jackpotId": "JP_GOLD_001",
    "userId": "ext-1234"
   }
  

2. Failed Credit Requests (with Successful Debit)

• Triggers: The debit request was completed successfully, but the associated credit request failed.
• Reconciliation Action: The script will retry the failed credit request to ensure the debit transaction has a closing credit transaction to match.

Limits & Stop-Loss Policy

To prevent infinite loops and reduce unnecessary load on our systems and clients, we enforce a strict retry cap on our reconciliation scripts:

• Retry Limit: All failed requests are retried up to 5 times.
• Terminal State: If all 5 reconciliation attempts fail, we stop trying to automatically reconcile that hanging debit transaction.