Integrator hooks

​

Setup

1. Deploy a contract that implements the hook. Start from the reference contracts below.
2. Make the contract the store’s payout destination: set its address as the settlement destination through the saved-address and settlement-proposal flow, like any other payout address. The store must use wallet payout mode.
3. Create sessions with hook_data: any JSON value except null, at most 1,024 bytes serialized. It is your reference, for example a player id.

curl -X POST "$TENDR_API_URL/v1/checkout/sessions" \
  -H "Authorization: Bearer $TENDR_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "25", "currency": "USD", "hook_data": { "player": "p_8812" } }'

​

The call

​

EVM

function onTendrDeposit(
    bytes32 paymentId,
    bytes32 sessionId,
    bytes calldata hookData,
    address token,
    uint256 amount,
    bytes32 txHash
) external returns (uint256);

• paymentId, sessionId: the Tendr ids (pay_..., ses_...) as UTF-8 bytes, right-padded to 32.
• hookData: the session’s hook_data as JSON text, UTF-8.
• token: the settlement token. address(0) is the chain’s native coin.
• amount: the settled amount in the token’s base units.
• txHash: the settlement transaction, the transfer into your contract.

​

NEAR

on_tendr_deposit({ payment_id, session_id, hook_data, token, amount, tx_hash })

​

What Tendr will and will not send

​

Gas

• Tendr never sends an EVM hook that needs more than 300,000 gas. Such a call fails at once.
• While gas prices make the call cost more than 10% of the order, the attempt is not sent and is retried later on the normal schedule.
• A hook estimate above 10% of the order makes the quote fail with QUOTE_TOO_SMALL.
• If the network fee plus the hook estimate is above 1% of the order, the network fee falls back to shopper-paid. The hook is still sent and still paid from proceeds.
• If a call costs more than the estimate, the excess is Tendr’s loss, never charged to you.

​

Retries, failure and resend

• A call that cannot be sent or whose outcome is unknown is retried with the webhook schedule: 1 minute, then doubling, for up to 3 days. A call your contract rejects in Tendr’s pre-send check, for example because it is paused, spends no gas and is retried the same way.
• A call that reverts on chain is not retried, because it burned gas. It fails at once.
• After the window, or on an on-chain revert, the hook call is failed. Tendr sends one hook.failed event and one alert email to the store’s notification email. The payment itself stays settled: the funds are in your contract.
• POST /v1/payments/{id}/hook/resend retries a failed call once, now. It returns 409 CONFLICT while an attempt is in flight, while Tendr is still retrying by itself, after the call succeeded, or when the payment has no hook call. A resend that fails again leaves the call failed without another event or email.
• Each hook call can be resent at most 3 times. A fourth resend returns 409 CONFLICT with details: { max_resends: 3, resends: 3 }. Fix the contract before you resend, and contact Tendr support if it still needs to be called after that.
• If your contract reverts on a repeated txHash with AlreadyNotified(bytes32) (EVM) or a panic with exactly already notified (NEAR), Tendr reads that on a retry or resend as “an earlier attempt landed” and marks the call succeeded. Use those exact errors.

​

Hook calls API

{
  "hook_calls": [
    {
      "id": "hook_...",
      "livemode": true,
      "payment_id": "pay_...",
      "session_id": "ses_...",
      "chain": "base",
      "contract": "0x...",
      "hook_data": { "player": "p_8812" },
      "status": "failed",
      "attempts": 11,
      "tx_hash": null,
      "last_error": "execution reverted: paused",
      "next_retry_at": null,
      "retry_until": "2026-10-30T09:00:00.000Z",
      "succeeded_at": null,
      "created_at": "2026-10-27T09:00:00.000Z",
      "updated_at": "2026-10-30T09:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

​

Events

​

Relayer addresses

{
  "relayers": [
    {
      "chain": "base",
      "family": "evm",
      "chain_id": 8453,
      "address": "0x...",
      "calls": "onTendrDeposit"
    },
    {
      "chain": "near",
      "family": "near",
      "chain_id": null,
      "address": "<64 hex>",
      "calls": "on_tendr_deposit"
    }
  ]
}

​

Reference contracts

• EVM: onchain/evm/src/reference/TendrDepositReceiver.sol
• NEAR: onchain/integrator-near

​

Checks your contract must keep

1. Sender. Accept the call only from Tendr’s published relayer address for that chain (the relayer-evm address on EVM, the relayer-near account on NEAR; see GET /v1/relayers above). Without this, anyone can call your function.
2. Balance. Credit at most what has arrived and is not yet accounted for: min(amount, balance(token) - accounted[token]), then add the credited amount to accounted[token]. Even a compromised relayer key then cannot make your contract credit money that never arrived. On NEAR the contract cannot read a balance synchronously, so it asks the token and credits in a callback; the reference does this.
3. Duplicates. Credit each txHash once.
4. Outflows. Anything that moves tokens out of the contract must lower accounted[token] by the same amount, in the same transaction. Never lower it without moving tokens out.

​

The misattribution limit

​

Storage on NEAR