Bonus and withdrawal checks

1. Screen the sign-up as before, and send your own accountId for the player with it. InlineShield binds the account to that sign-up.
2. When the player claims a bonus or asks for a withdrawal, your server calls the event endpoint with the accountId, the player's current ip and, for a withdrawal, the payout account as a fingerprint.
3. InlineShield compares the event with the sign-up, with the account's linked group, with your other accounts that used the same payout account, and with the IP. It answers with a decision, an action, a recommendedAction, a riskScore and the reasons.
4. Pay, hold or refuse. A held event waits in Review › Held for up to 72 hours, and the outcome reaches your server by webhook or by polling.

The checks add to what the sign-up screening knows. They only hold or advise, with one exception: an event is BLOCKED when the IP and bot checks of your sign-up rules would block it (see Decision and advice).

The checks work best when InlineShield knows which sign-up an account came from. There are two ways to tell it:

• Send accountId with the sign-up call: POST /api/v1/verify or POST /api/v1/siteverify. The account is bound to the screening that call recorded.
• Send signupRequestId (the requestId, AUD-…, of the sign-up) with a bonus or withdrawal event, for an account that is not bound yet.

• The first binding stays. A later call with the same accountId and another sign-up changes nothing, and so does a signupRequestId on an event for an account that is already bound.
• An accountId is 1 to 128 printable characters, and not only white space. Anything else gets 400 INVALID_ACCOUNT_ID and nothing is screened.
• Accounts are yours alone: the same accountId in another InlineShield account is another player. Test keys and live keys have separate accounts, so a test event never meets a live sign-up.

An event for an account with no sign-up bound is still answered. Its reasons say "Sign-up not linked to this account", and nothing that needs the sign-up (its country, its verdict, its linked group) is checked. There is no penalty for that.

Call it before you credit a bonus. Only accountId is required; the more you send, the more it can check.

curl -X POST https://api.inlineshield.io/api/v1/events/bonus \
  -H "X-Api-Key: $INLINESHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "player-1042",
  "ip": "203.0.113.24",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
  "bonusType": "welcome",
  "amount": 50,
  "currency": "EUR"
}'

Every field, answer and error: POST /api/v1/events/bonus.

Call it before you pay a withdrawal. accountId, amount and payout are required.

curl -X POST https://api.inlineshield.io/api/v1/events/withdrawal \
  -H "X-Api-Key: $INLINESHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "player-2087",
  "ip": "203.0.113.24",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
  "amount": 120,
  "currency": "EUR",
  "payout": {
    "type": "wallet",
    "fingerprint": "3f9a1c7e5b2d48a0b6c1e9d4f7a28b35"
  }
}'

Every field, answer and error: POST /api/v1/events/withdrawal.

Limits on the text fields, as in the API reference: userAgent 1,024 characters, bonusType 40, currency 3, token 512, signupRequestId 128, accountId 128. A longer value gets 400 BAD_REQUEST (INVALID_ACCOUNT_ID for accountId) before anything is screened, stored or counted.

InlineShield never receives the card number, IBAN or wallet address of a payout account, and refuses it when it is sent. You send a fingerprint of the account instead: your payment provider's fingerprint of the card or bank account (for example Stripe's fp_…), or a value you compute yourself from the account with a secret key that stays with you. It must be the same string every time the same account is used, so that two accounts that pay out to one card are recognised.

• payout.type is one of card, iban, wallet or other. The same fingerprint under another type is another payout account.
• payout.fingerprint is 16 to 128 characters of A-Z, a-z, 0-9, _, -, : and .. Anything else gets 400 BAD_REQUEST with field: "payout".

What is refused

A value that looks like raw payment data gets 400 RAW_PAYMENT_DATA, whatever type says. This check comes before the other payout checks, so a card number with spaces is RAW_PAYMENT_DATA, not BAD_REQUEST.

The refusal message never repeats the value you sent.

What is stored

• Only a keyed hash: HMAC-SHA256 of your InlineShield account, the payout type and the fingerprint, with a key that only InlineShield's servers hold. The fingerprint itself is never stored or logged.
• The hash includes your account, so the same fingerprint in two InlineShield accounts gives two different hashes: payout accounts are never compared across customers.
• The hash is removed from the stored event after 180 days, with the IP address and User-Agent (the default retention period). Payout accounts are compared over the last 180 days.

Computing it with the SDK

With SDK 1.1.0 or later, payoutFingerprint(type, value, secret) computes the fingerprint on your server: a lower-case hex HMAC-SHA256 of type:normalized value, keyed by a secret key of at least 16 bytes that only you hold. A card is reduced to its digits (no expiry), an IBAN loses its white space and is upper-cased, a wallet is trimmed (and lower-cased for a 0x address), and any other type is trimmed. An unknown type or an empty value throws an error (nothing is sent). The card number, IBAN or wallet address never leaves your server, and the result is 64 characters, which InlineShield accepts. Call it on your server only, never in the browser, and keep the secret the same forever: changing it makes every payout account look new.

import { payoutFingerprint } from '@inlineshield/node';

const fingerprint = payoutFingerprint('card', cardNumber, process.env.PAYOUT_FINGERPRINT_SECRET);

from inlineshield import payout_fingerprint

fingerprint = payout_fingerprint("card", card_number, os.environ["PAYOUT_FINGERPRINT_SECRET"])

use InlineShield\Client;

$fingerprint = Client::payoutFingerprint('card', $cardNumber, getenv('PAYOUT_FINGERPRINT_SECRET'));

Both endpoints answer 200 with the same fields:

• action: allow (pay), hold (do not pay until the review is decided) or block.
• The requestId of an event starts with EVT-. Store it with the payment.
• A live hold carries a reviewId; a held test event does not.

Each signal that fires adds its points and a line to reasons, and its code to triggers. The riskScore is the sum, at most 100.

• A signal whose facts are not known never fires: no IP, no token, no bound sign-up, or a lookup that did not finish in time (see Time budget).
• Unbound accounts count toward PAYOUT_SHARED: an account that never had a sign-up bound still counts as another account using the payout account. PAYOUT_SHARED_WITH_FRAUD and the same_payout links can only come from accounts bound to a sign-up.
• Only the ip in the body is used. The address of the request is your server's, so without ip the IP signals (country, datacenter, VPN, Tor, time zone) are unknown.

BLOCKED comes first: an event that your sign-up rules would block is BLOCKED even if a hold rule also fired.

A held bonus claim with a score of 50 or more is deny_bonus, not review. Read recommendedAction as well as action: an ALLOWED event can still say deny_bonus or deny.

In the console, Settings › Rules › Bonus and withdrawal checks has five switches and one number. They hold or advise; nothing is denied automatically.

A stored change applies to the next event. An account without stored rules uses the defaults above.

The lookups of one event (your rules, the bound sign-up and its links, the token's browser signals, the account's history, the other accounts of the payout account, the bonus claims of the linked group) start together and share one budget of 150 ms. A lookup that fails or has not finished by then is treated as unknown: it never fires a signal, and the reasons say "Some checks did not finish in time; this answer uses what was known."

Binding the account to signupRequestId happens before that clock starts, and the event is stored after it, so a slow lookup never costs you the record.

token is optional. It is the token that /check (the browser script on your sign-up page) gave this player at sign-up, and it lends the event that check's browser signals: the time zone and the automation hints. Without a token the event is screened from server-side data only (the body, the bound sign-up and the account's history), and those two signals are unknown.

• Only the sign-up token works. It can be used only within its 10-minute life, and only if your backend has not already redeemed it with /siteverify. In practice that means an event sent right after sign-up, for example a welcome bonus claimed at once.
• Never run /check on your bonus or cashier pages. Each /check records a new sign-up screening: it counts against your quota and creates false links between the player and their own earlier sign-up.
• An event spends the token. The unused /check token of your account is redeemed by the event, so a later POST /api/v1/siteverify with the same token answers success: false with TOKEN_ALREADY_USED. If you need both, call /siteverify first and screen the event without the token.
• A token of the other mode (a test token with a live key, or the other way round) is left unused and ignored. An unknown, expired or already used token is ignored too: the event is still answered.
• A token is single-use for 10 minutes, as for /siteverify.

Retries and timeouts

• A retried request is a second event. There is no idempotency key: a request you send again is screened and stored again, counts again against your quota, and counts as another withdrawal toward WITHDRAWAL_VELOCITY. Do not retry after a timeout; wait for the webhook instead.
• After a timeout, the webhook decides. If the SDK timed out and failed open (you let the claim or withdrawal through), a later bonus.held or withdrawal.held webhook for that event is authoritative: the event was held, so stop or reverse the payout and wait for its *.approved or *.rejected.

• A held live event has a reviewId (rev_…). It creates one review, counted once, and sends one bonus.held or withdrawal.held webhook.
• It waits in the console under Review › Held, next to held sign-ups, with a Bonus claim or Withdrawal badge, the amount, the reasons and the account id masked to its first 2 characters and ***.
• GET /api/v1/reviews/{reviewId} answers for both kinds, with the same fields: GET /api/v1/reviews/{reviewId}.
• A review nobody decides within 72 hours is rejected with decisionReason: "expired". No label is written for that.
• Rejecting marks the event's sign-up as fraud. Approving marks it legit, unless the sign-up was blocked or already carries a fraud mark from any source: an approval never clears one, whether it is the approval of an event or of the held sign-up itself. An event whose account has no sign-up bound writes no label.

See Hold and review for the flow.

Eight events: bonus.allowed, bonus.held, bonus.approved, bonus.rejected and withdrawal.allowed, withdrawal.held, withdrawal.approved, withdrawal.rejected. They are signed and retried like the others: see Webhooks.

• They go to every enabled endpoint, whatever its subscriptions. An endpoint that subscribes to the registration events only receives them too.
• *.allowed and *.held are sent when the event is screened (live events only). Nothing is sent for a BLOCKED event. *.approved and *.rejected are sent when the review is decided or expires.
• Deliveries can arrive in any order. Each delivery is sent and retried on its own, so bonus.approved or withdrawal.approved can arrive before the *.held of the same event. Key your handler on reviewId and requestId, not on the order.
• The payload carries your own accountId, the amount and the reasons. It has no IP address and no User-Agent.

bonus.allowed, bonus.held, withdrawal.allowed, withdrawal.held: data

bonus.approved, bonus.rejected, withdrawal.approved, withdrawal.rejected: data

A test key behaves as it does for sign-ups: events are screened and stored (shown with "Show test data"), but they never count against the quota, and they create no review, webhook, label or alert and no linked-accounts links. Test events only meet test accounts. See Test mode.

Two magic account ids give a fixed answer without any lookups, with test keys only. The match is exact, and each applies to its own endpoint; on the other endpoint, or with a live key, they are ordinary account ids.

The held answer of payout-shared@test has no reviewId: test mode creates no review.

• Each live event counts once against your monthly quota, like a /verify screening, and live answers carry the X-Quota-* headers. Over the quota, the event endpoints answer 402 QUOTA_EXCEEDED. Test keys never count.
• Live events are limited per key, like /siteverify: the key's own per-minute limit (1,200 for a live key as created, 600 for a key without a limit of its own), one bucket for both endpoints. Test keys use a separate bucket of 300 per minute for your account, again for both endpoints together.
• Event calls with a test key also count toward the daily test cap of 10,000 per UTC day (then 429 TEST_LIMIT), the one that /verify and /check use.
• If the event was screened but could not be stored you get 500 PERSISTENCE_FAILURE, and nothing is counted. Decide in advance whether to pay or wait; see Errors and HTTP codes.

• Each event is stored for your account: your accountId as you sent it, the kind, the amount and currency, the bonusType or payout type, the IP address, User-Agent, the keyed payout hash and the result.
• After 180 days (the default retention period) the IP address, User-Agent and payout hash are removed from the event; the result stays.
• The console shows the account id masked. Account ids and payout data are never written to InlineShield's logs.
• See Data and privacy for everything else.