API Reference

Complete endpoint documentation for the SideBet round-up API

Authentication

All requests require a Bearer token in the Authorization header. Obtain your API key from the Hedge Payments dashboard under Settings → API Keys.

Authorization Headerbash

curl -X POST https://api.hedgepayments.com/api/roundup/initiate \
  -H #98C379]">"Authorization: Bearer sk_live_your_api_key" \
  -H #98C379]">"Content-Type: application/json" \
  -d #98C379]">'{ ... }'

Base URLs

Environment	URL
Sandbox	https://api-sandbox.hedgepayments.com
Production	https://api.hedgepayments.com

POST/api/roundup/initiate

Calculate and initiate a round-up ACH debit for a consumer bet. The round-up amount is determined by the provided strategy (or the merchant's default), subject to per-transaction and daily caps.

Request Body

Parameter	Type	Required	Description
`betAmount`	integer	Required	Bet amount in cents (e.g., 2347 for $23.47)
`consumerId`	string	Required	The consumer's unique ID from bank linking
`strategy`	string	Required	Round-up strategy: nearest-dollar, nearest-5, percentage, fixed-amount, or dynamic
`merchantId`	string	Required	Your merchant ID
`strategyValue`	number	Optional	Required for percentage (1-10), fixed-amount (cents), and dynamic (multiplier)

Requestjson

{
  #98C379]">"betAmount": 2347,
  #98C379]">"consumerId": "cust_j4k5l6m7",
  #98C379]">"strategy": "nearest-dollar",
  #98C379]">"merchantId": "merch_xyz789"
}

Response — 200 OKjson

{
  #98C379]">"id": "roundup_9f8e7d6c",
  #98C379]">"roundUpCents": 53,
  #98C379]">"betAmountCents": 2347,
  #98C379]">"status": "pending",
  #98C379]">"skipped": false,
  #98C379]">"consumerId": "cust_j4k5l6m7",
  #98C379]">"merchantId": "merch_xyz789"
}

Response — daily cap reachedjson

{
  #98C379]">"id": null,
  #98C379]">"roundUpCents": 0,
  #98C379]">"betAmountCents": 2347,
  #98C379]">"status": "skipped",
  #98C379]">"skipped": true,
  #98C379]">"consumerId": "cust_j4k5l6m7",
  #98C379]">"merchantId": "merch_xyz789"
}

GET/api/roundup/consumer/:consumerId

Retrieve a consumer's round-up transaction history and current daily total. Useful for displaying round-up activity in your UI.

Path Parameters

Parameter	Type	Required	Description
`consumerId`	string	Required	The consumer's unique ID

Response — 200 OKjson

{
  #98C379]">"consumerId": "cust_j4k5l6m7",
  #98C379]">"dailyTotalCents": 247,
  #98C379]">"dailyMaxCents": 5000,
  #98C379]">"transactions": [
    {
      #98C379]">"id": "roundup_9f8e7d6c",
      #98C379]">"roundUpCents": 53,
      #98C379]">"betAmountCents": 2347,
      #98C379]">"status": "completed",
      #98C379]">"createdAt": "2026-03-24T14:30:00Z"
    },
    {
      #98C379]">"id": "roundup_a1b2c3d4",
      #98C379]">"roundUpCents": 94,
      #98C379]">"betAmountCents": 1506,
      #98C379]">"status": "initiated",
      #98C379]">"createdAt": "2026-03-24T15:12:00Z"
    },
    {
      #98C379]">"id": "roundup_e5f6g7h8",
      #98C379]">"roundUpCents": 100,
      #98C379]">"betAmountCents": 5000,
      #98C379]">"status": "pending",
      #98C379]">"createdAt": "2026-03-24T16:45:00Z"
    }
  ]
}

POST/api/roundup/configure

Configure or update the round-up strategy for a merchant. Sets the default strategy, transaction caps, and settlement preferences.

Request Body

Parameter	Type	Required	Description
`merchantId`	string	Required	Your merchant ID
`strategy`	string	Required	nearest-dollar, nearest-5, percentage, fixed-amount, or dynamic
`strategyValue`	number	Optional	Value for percentage (1-10), fixed-amount (cents), dynamic (multiplier)
`perTransactionMaxCents`	integer	Optional	Per-transaction ceiling in cents. Default: 1000 ($10)
`dailyMaxCents`	integer	Optional	Daily cap per consumer in cents. Default: 5000 ($50)
`settlementType`	string	Optional	USDC (instant) or USD (3 business days). Default: USD

Requestjson

{
  #98C379]">"merchantId": "merch_xyz789",
  #98C379]">"strategy": "percentage",
  #98C379]">"strategyValue": 5,
  #98C379]">"perTransactionMaxCents": 1000,
  #98C379]">"dailyMaxCents": 5000,
  #98C379]">"settlementType": "USDC"
}

Response — 200 OKjson

{
  #98C379]">"merchantId": "merch_xyz789",
  #98C379]">"strategy": "percentage",
  #98C379]">"strategyValue": 5,
  #98C379]">"perTransactionMaxCents": 1000,
  #98C379]">"dailyMaxCents": 5000,
  #98C379]">"settlementType": "USDC",
  #98C379]">"updated": true
}

GET/api/roundup/merchant/:merchantId/summary

Retrieve aggregate round-up statistics for a merchant. Includes total volume, active consumers, and current strategy configuration.

Path Parameters

Parameter	Type	Required	Description
`merchantId`	string	Required	Your merchant ID

Response — 200 OKjson

{
  #98C379]">"merchantId": "merch_xyz789",
  #98C379]">"strategy": "nearest-dollar",
  #98C379]">"perTransactionMaxCents": 1000,
  #98C379]">"dailyMaxCents": 5000,
  #98C379]">"settlementType": "USDC",
  #98C379]">"stats": {
    #98C379]">"totalRoundUpsCents": 458320,
    #98C379]">"totalTransactions": 12847,
    #98C379]">"activeConsumers": 1923,
    #98C379]">"completedCount": 12105,
    #98C379]">"failedCount": 42,
    #98C379]">"returnedCount": 18,
    #98C379]">"pendingCount": 682,
    #98C379]">"avgRoundUpCents": 36
  }
}

Webhook Events

SideBet sends webhook events as ACH payments progress through the pipeline. See the Webhooks page for full payload structures, signature validation, and retry policy.

Event	Description	Payload Key Fields
`roundup.initiated`	ACH debit submitted to consumer's bank	data.roundupId, data.amount, data.consumerId
`roundup.completed`	Funds received and settled to merchant	data.roundupId, data.amount, data.fees
`roundup.failed`	Payment could not be processed	data.roundupId, data.reason
`roundup.returned`	Bank returned the debit (e.g., insufficient funds)	data.roundupId, data.returnCode, data.reason

Error Codes

All error responses follow a consistent envelope. The field property is included when the error relates to a specific request parameter.

Code	Meaning	Common Causes
`400`	Bad Request	Missing required fields, invalid JSON body
`401`	Unauthorized	Missing or invalid API key in Authorization header
`404`	Not Found	Consumer or merchant ID does not exist, no linked bank account
`409`	Conflict	Duplicate round-up for the same bet event (idempotency)
`422`	Unprocessable Entity	Bet amount is zero or negative, invalid strategy, percentage out of range
`429`	Too Many Requests	Rate limit exceeded — see Rate Limits below
`500`	Internal Server Error	Unexpected server error — contact support if persistent

Error Response Formatjson

{
  #98C379]">"error": {
    #98C379]">"code": 422,
    #98C379]">"message": "betAmount must be a positive integer",
    #98C379]">"field": "betAmount"
  }
}

Rate Limits

Rate limits are enforced per merchant API key. All limits use a sliding window.

Endpoint	Limit	Window
`POST /api/roundup/initiate`	100 requests	per minute per merchant
`GET /api/roundup/consumer/:id`	300 requests	per minute per merchant
`POST /api/roundup/configure`	10 requests	per minute per merchant
`GET /api/roundup/merchant/:id/summary`	60 requests	per minute per merchant

Rate limit headers

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. When you receive a 429, wait until the reset timestamp before retrying.

Quickstart

Step-by-step integration guide with working code

Webhooks

Full payload structures, signature validation, and retry policy

API Reference

Base URLs

Request Body

Path Parameters

Request Body

Path Parameters

Webhook Events

Error Codes

Rate Limits

Related

Quickstart

Webhooks