Skip to content

Perform Transaction

Overview

The perform-transaction endpoint is the core of wallet integration. It handles all financial operations including deposits, withdrawals, and rollbacks for bets, settlements, and bonus operations.

Key points:

  • You implement this endpoint with your own URL
  • Notify GR8 Tech about your endpoint URL for configuration
  • Must guarantee idempotency (same transaction ID = same response)
  • Get balance is called after each transaction by default

On this page:

Quick Reference

Transaction Types Overview

Type Direction Required Common Use Cases
withdrawal Money out Yes Bets, cancel settlements, negative adjustments
deposit Money in Yes Settlements, winnings, positive adjustments
rollback Reverse Yes Bet cancellations, reversals

Bonus Integration

Transaction types award, release, and retract are only required if you integrate with the GR8 Tech Bonus System.

Quick Navigation

Endpoint Configuration

URL Format

[POST] /api/v2/wallet/{playerId}/transactions

Request Timeout: 2 seconds

All transaction requests have a 2-second timeout. Your endpoint must respond within this time limit, otherwise:

Ensure your wallet system can process requests quickly and efficiently.

Multi-Tenant Setup

Each brand must use exactly one wallet endpoint. If you operate multiple brands, you can either:

  • Provide different endpoint URLs per brand
  • Use one endpoint URL with routing logic based on X-Brand and X-Operator-Id headers

Request Parameters

Parameter Location Type Required Description
playerId Path string Yes Unique player identifier
X-Brand Header string Yes Tenant identifier representing site and operator (configured during setup, cannot be changed)
X-Operator-Id Header string Yes Tenant identifier representing site and operator (configured during setup, cannot be changed)

Request Structure

Core Fields

Field Type Required Description
id string Yes Unique transaction identifier. Used for idempotency - same ID = same result
currency string Yes ISO 4217 currency code (USD, EUR, KES, etc.)
platform string Yes Platform identifier (typically "sport" or "CRM")
type string Yes Transaction type: deposit, withdrawal, rollback, award, release, retract
initiatedAt string Yes ISO 8601 timestamp when transaction was initiated
createdAt string Yes ISO 8601 timestamp when transaction was created

Context Object

Field Type Required Description
product string Yes Product identifier (sportsbook, crm)
reason string Yes Transaction reason code (see Reference)
betId string No Bet identifier (present for bet-related transactions)
parentId string No Parent transaction ID (required for rollback transactions)
sportBonusOfferId string No Activity ID from Journey Builder (for bonus transactions)
sportBonusPlayerOfferId string No Player-specific bonus activation ID (for bonus transactions)

Amount Breakdown

Field Type Description
cash string Cash amount as decimal string (e.g., "100.50")
bonus string Bonus amount as decimal string
locked string Locked amount as decimal string (used for wagering requirements)
retract string Retract amount as decimal string (bonus funds removed/excess)

Request Schema

Full Request Schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code (e.g., USD, EUR, KES)"
    },
    "platform": {
      "type": "string",
      "description": "Platform identifier (e.g., sport, CRM)"
    },
    "id": {
      "type": "string",
      "description": "Unique transaction identifier (used for idempotency)"
    },
    "type": {
      "type": "string",
      "enum": ["deposit", "withdrawal", "rollback", "award", "release", "retract"],
      "description": "Transaction type"
    },
    "initiatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "When transaction was initiated (ISO 8601)"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "When transaction was created (ISO 8601)"
    },
    "context": {
      "type": "object",
      "properties": {
        "product": {
          "type": "string",
          "description": "Product identifier (e.g., sportsbook, crm)"
        },
        "reason": {
          "type": "string",
          "description": "Transaction reason (see Transaction Types Reference section)",
        },
        "betId": {
          "type": "string",
          "description": "Bet identifier (for bet-related transactions: bet, settle, resettle...)"
        },
        "parentId": {
          "type": "string",
          "description": "Parent transaction ID (for rollbacks)"
        },
        "sportBonusOfferId": {
          "type": "string",
          "description": "Bonus offer ID (Activity ID from Journey Builder)"
        },
        "sportBonusPlayerOfferId": {
          "type": "string",
          "description": "Player-specific bonus activation ID"
        }
      },
      "required": ["product", "reason"],
      "additionalProperties": true
    },
    "amountBreakdown": {
      "type": "object",
      "properties": {
        "cash": {
          "type": "string",
          "description": "Cash amount (decimal string)"
        },
        "bonus": {
          "type": "string",
          "description": "Bonus amount (decimal string)"
        },
        "locked": {
          "type": "string",
          "description": "Locked amount (decimal string)"
        },
        "retract": {
          "type": "string",
          "description": "Retract amount (decimal string)"
        }
      },
      "additionalProperties": true
    }
  },
  "required": ["currency", "platform", "id", "type", "amountBreakdown", "initiatedAt", "createdAt", "context"]
}

Basic Request Example

Bet Placement Request
{
  "id": "5f338453-6172-491f-b8f0-27e382ea05eb",
  "currency": "USD",
  "platform": "sport",
  "type": "withdrawal",
  "createdAt": "2025-01-29T00:34:25Z",
  "initiatedAt": "2025-01-29T00:34:25Z",
  "context": {
    "product": "sportsbook",
    "reason": "bet",
    "betId": "5f338453-6172-491f-b8f0-27e382ea05eb"
  },
  "amountBreakdown": {
    "cash": "13.9",
    "locked": "0",
    "bonus": "0"
  }
}

For more examples, see Transaction Examples.

Response Structure

Idempotency Requirements

Your wallet MUST implement idempotency to handle duplicate transaction requests:

  • Store transaction snapshots for at least 3 days
  • Return the same response for duplicate transaction IDs (same id field)
  • Set alreadyProcessed: true for duplicate requests
  • Store snapshots even for failed transactions (e.g., decline.lowbalance)

This ensures system reliability during network issues and retries.

Success Response

All successful transactions return HTTP 200 with the following structure:

Full Response Schema (JSON Schema) 
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "currency": {
      "type": "string"
    },
    "platform": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": ["deposit", "withdrawal", "rollback", "award", "release", "retract"]
    },
    "balances": {
      "type": "object",
      "description": "Nested structure: platform -> product -> currency -> balance details",
      "patternProperties": {
        "^.*$": {
          "type": "object",
          "patternProperties": {
            "^.*$": {
              "type": "object",
              "patternProperties": {
                "^.*$": {
                  "type": "object",
                  "properties": {
                    "cash": {
                      "type": "string"
                    },
                    "bonus": {
                      "type": "string"
                    },
                    "locked": {
                      "type": "string"
                    },
                    "retract": {
                      "type": "string"
                    }
                  },
                  "required": ["cash", "bonus", "locked"],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "alreadyProcessed": {
      "type": "boolean",
      "description": "True if transaction was already processed (idempotency)"
    },
    "initiatedAt": {
      "type": "string"
    },
    "createdAt": {
      "type": "string"
    },
    "context": {
      "type": "object",
      "properties": {
        "product": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "amountBreakdown": {
      "type": "object",
      "properties": {
        "cash": {
          "type": "string"
        },
        "bonus": {
          "type": "string"
        },
        "locked": {
          "type": "string"
        },
        "retract": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "currency",
    "platform",
    "id",
    "type",
    "balances",
    "alreadyProcessed",
    "initiatedAt",
    "createdAt",
    "context",
    "amountBreakdown"
  ]
}

Response Examples

First Request (New Transaction)

Success Response - First Request
{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "86.1",
          "bonus": "0",
          "locked": "0",
          "retract": "0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "86.1",
          "bonus": "0",
          "locked": "0",
          "retract": "0"
        }
      }
    }
  },
  "alreadyProcessed": false,
  "currency": "USD",
  "platform": "sport",
  "id": "5f338453-6172-491f-b8f0-27e382ea05eb",
  "type": "withdrawal",
  "initiatedAt": "2025-01-29T00:34:25.000Z",
  "createdAt": "2025-01-29T00:34:26.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "bet"
  },
  "amountBreakdown": {
    "cash": "13.9",
    "bonus": "0",
    "locked": "0"
  }
}

Duplicate Request (Idempotency)

If the same transaction ID is sent again, return the exact same response with alreadyProcessed: true:

Success Response - Duplicate Request
{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "86.1",
          "bonus": "0",
          "locked": "0",
          "retract": "0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "86.1",
          "bonus": "0",
          "locked": "0",
          "retract": "0"
        }
      }
    }
  },
  "alreadyProcessed": true,
  "currency": "USD",
  "platform": "sport",
  "id": "5f338453-6172-491f-b8f0-27e382ea05eb",
  "type": "withdrawal",
  "initiatedAt": "2025-01-29T00:34:25.000Z",
  "createdAt": "2025-01-29T00:34:26.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "bet"
  },
  "amountBreakdown": {
    "cash": "13.9",
    "bonus": "0",
    "locked": "0"
  }
}

For more response examples, see Transaction Examples.

Error Responses

Error Response Structure

Return HTTP 400 with the following structure for business logic errors:

Error Response Schema 
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Error code from the error codes list"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message"
        },
        "origin": {
          "type": "string",
          "description": "Your company/system name"
        }
      },
      "required": ["code", "message", "origin"]
    },
    "alreadyProcessed": {
      "type": "boolean",
      "description": "Optional: True if this error was already returned for this transaction ID"
    }
  },
  "required": ["error"]
}

Error Response Examples

New Error

Error Response - First Occurrence
{
  "error": {
    "code": "decline.lowbalance",
    "message": "Not enough funds for performing transaction",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": false
}

Duplicate Error (Idempotency)

If the same transaction ID is sent again and previously failed, return the same error with alreadyProcessed: true:

Error Response - Duplicate Request
{
  "error": {
    "code": "decline.lowbalance",
    "message": "Not enough funds for performing transaction",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": true
}

Common Error Codes

Error Code HTTP Status Description
decline.lowbalance 400 Insufficient funds
decline.parent.notfound 400 Parent transaction not found (for rollbacks)
decline.parent.failed 400 Parent transaction failed (for rollbacks)
decline.player.notfound 400 Player not found
decline.player.blocked 400 Player account is blocked
decline.currency.mismatch 400 Currency mismatch

For a complete list of error codes, see Wallet Error Codes.

Rollback and Retry Requirements

Critical: Must Read

Rollback handling has special requirements including:

  • Specific error codes (decline.parent.notfound, decline.parent.failed)
  • Infinite retries until definitive response
  • High availability requirements

Read the complete guide: Rollback and Retry Logic

Implementation Checklist

Core Integration (Required)

  • [ ] Implement endpoint with your URL structure
  • [ ] Handle core transaction types: deposit, withdrawal, rollback
  • [ ] Implement idempotency check (same id = same response)
  • [ ] Store transaction snapshots for at least 3 days (including failed transactions)
  • [ ] Return correct balance structure in response
  • [ ] Handle core reason codes: bet, settle, resettle, cancelsettle, sport rollback
  • [ ] Implement proper error responses with correct error codes
  • [ ] ⚠️ CRITICAL: Read and implement Rollback and Retry Logic
  • [ ] Test retry scenarios for each operation type
  • [ ] Configure X-Brand and X-Operator-Id header handling
  • [ ] Notify GR8 Tech of your endpoint URL
  • [ ] Test with GR8 Tech team before going live

Bonus Integration (Optional)

Only required if integrating with GR8 Tech Bonus System:

  • [ ] Handle bonus transaction types: award, release, retract
  • [ ] Implement bonus balance tracking (bonus, locked, retract)
  • [ ] Handle bonus reason codes: bonus award, bonus release, bonus limit release
  • [ ] Handle freebet reason codes: freebet award, freebet, settle freebet, etc.
  • [ ] Test bonus award and release flows
  • [ ] Test freebet flows (if applicable)
  • [ ] Review Sport Bonus Amount documentation
  • [ ] Review Freebet documentation (if applicable)

Core Wallet Integration

Bonus System Integration (Optional)