Skip to main content

Seamless Wallet Setup & Security

This guide will help you set up and configure Seamless Wallet integration with EvenBet Gaming.

What is Seamless Wallet?​

In Seamless Wallet integrations, the EvenBet system does not store player funds. Your system remains the single source of truth for player balances. Whenever money needs to be withdrawn or deposited, our system makes a callback request to your server, and you handle the actual balance changes.

Prerequisites​

Before you begin integration, the following configuration is required:

CALLBACK_URL​

  • The URL endpoint where EvenBet will send all transaction requests
  • Provide this URL to us, and we'll configure it on our end
  • Must be accessible via HTTPS
  • Example: https://your-domain.com/api/evenbet/wallet

SEAMLESS_KEY​

  • A secure key used to sign and verify all requests
  • We provide this key to you during setup
  • Must be different for test and production environments
  • Keep this key secure and never expose it in client-side code
warning

If your seamless key is compromised, immediately notify EvenBet support. For better security, we recommend periodic key rotations.

Communication Protocol​

All communication between EvenBet and your system follows these rules:

Request Format​

  • Method: HTTP POST
  • Content Type: JSON
  • Authentication: Signature-based (see Security section below)

Response Format​

  • Content Type: JSON
  • Required fields: Vary by request type (see individual API references)
  • Error handling: Return appropriate error codes (see Error Reference)

Security​

All requests are secured using signature-based authentication to ensure data integrity and prevent unauthorized access.

Request Signature​

Every request from EvenBet includes a signature in the HTTP header that you must validate.

Header name: sign

How the signature is generated:

  1. The complete JSON request body is converted to a string
  2. Your SEAMLESS_KEY is appended to this string
  3. SHA256 hash is applied to the combined string
  4. The resulting hash is sent in the sign header

Signature Validation Example (PHP)​

<?php
// Step 1: Get the incoming request data
$jsonMessage = file_get_contents('php://input'); // Raw JSON string
$sign = $_SERVER['HTTP_SIGN']; // Signature from header
$SEAMLESS_KEY = 'your_seamless_key_here'; // Your seamless key

// Step 2: Calculate expected signature
$expectedSign = hash('sha256', $jsonMessage . $SEAMLESS_KEY);

// Step 3: Validate signature
if ($sign !== $expectedSign) {
    // Invalid signature - return error
    http_response_code(200);
    header('Content-Type: application/json');
    echo json_encode([
        'errorCode' => 1,
        'errorDescription' => 'Invalid signature'
    ]);
    exit;
}

// Step 4: If valid, parse and process the request
$request = json_decode($jsonMessage, true);
// ... continue with your business logic
?>

Signature Validation Example (Node.js)​

const crypto = require('crypto');

function validateSignature(req, SEAMLESS_KEY) {
    // Get the raw body and signature
    const jsonMessage = JSON.stringify(req.body);
    const receivedSign = req.headers['sign'];
    
    // Calculate expected signature
    const expectedSign = crypto
        .createHash('sha256')
        .update(jsonMessage + SEAMLESS_KEY)
        .digest('hex');
    
    // Validate
    if (receivedSign !== expectedSign) {
        return false;
    }
    
    return true;
}

// Usage in Express.js
app.post('/api/evenbet/wallet', (req, res) => {
    if (!validateSignature(req, process.env.SEAMLESS_KEY)) {
        return res.json({
            errorCode: 1,
            errorDescription: 'Invalid signature'
        });
    }
    
    // Continue processing...
});
Important Notes
  • The signature is calculated using the exact raw JSON string as received
  • Do not parse the JSON before validating the signature
  • The SEAMLESS_KEY is not sent in the request - only you and EvenBet know it
  • Different SEAMLESS_KEY values should be used for test and production environments

IP Whitelisting​

For production environments, IP whitelisting is required for both sides:

EvenBet side:

  • Our specialists will configure IP whitelisting on our servers
  • Only requests from your whitelisted IPs will be accepted

Your side:

  • You must whitelist EvenBet's IP addresses
  • Only accept requests from EvenBet's IPs
  • We will provide you with the IP addresses to whitelist

To request IP whitelist changes:

  • Contact your EvenBet account manager
  • Provide your server IP addresses
info

IP whitelisting is not required for test/staging environments, but is mandatory for production.

Testing Your Integration​

Manual Testing Tool​

EvenBet provides a manual testing tool to verify your integration implementation:

Test Tool URL: https://tests.evenbetgaming.com/seamless/

Use this tool to:

  • Verify your signature implementation
  • Test request/response formats
  • Simulate different transaction scenarios
  • Debug integration issues
Recommendation

Thoroughly test your integration in the staging environment before going live. Test all transaction types and error scenarios.

Automated Testing Suite​

Before going live, you must pass our comprehensive automated test suite. This includes 35+ automated tests covering all API methods and edge cases.

Access to automated tests:

  • Login credentials will be provided by your EvenBet account manager after initial setup is complete
  • Tests must be successfully completed before production launch
  • The automated test suite validates signature implementation, error handling, idempotency, and all transaction flows

Contact your account manager for automated test access credentials when you're ready for final validation.

Integration Checklist​

Before going live, ensure you have completed the following:

Essential​

  • Provided CALLBACK_URL to EvenBet
  • Provided IP whitelist to EvenBet
  • Implemented signature validation on your server
  • Configured EvenBet IP whitelisting for production
  • Tested integration using manual test tool: https://tests.evenbetgaming.com/seamless/
  • Passed all automated tests (credentials provided by EvenBet account manager)
  • Implemented proper error handling
  • Implemented idempotency checks (prevent duplicate transactions)
  • Set up monitoring and logging for all requests
  • Documented your integration for your team

What's Next?​

Now that your integration is set up and tested, learn how the transaction flow works:

  1. Seamless Wallet Transaction Flow - Understand when each API is called and see complete transaction scenarios
  2. API References:
  3. Error Reference - Handle errors properly

Support​

If you encounter any issues during integration: