Cashback Claim

How it works

The cashback claim flow is always initiated by your backend. The widget plays no role in triggering a claim — it is purely for display. The sequence is straightforward:

The userRef — the critical link

The userRef you include in a cashback claim must be exactly the same value you use as userRef in the JWT assertion when that user opens the widget. This is how Fruga connects the claim to the right user’s wallet and display.

Idempotency

Every claim request requires a partnerEventId — a unique string you generate for each event. Fruga uses this to make the endpoint idempotent: if the same partnerEventId is submitted more than once, Fruga returns the original response without creating a duplicate payout.

This protects you in real production scenarios — network timeouts, retry logic, or double-submission bugs will not result in a user being paid twice. The safest approach is to derive the partnerEventId from something that is naturally unique in your system, such as a policy transaction ID or order reference.

Redemption context

The redemptionContext field tells Fruga what kind of event triggered the claim. This is used for reporting, display in the widget, and future analytics. Set it to the value that most accurately describes the event.

Payout routing — how your configuration determines what happens next

Once Fruga receives and validates a claim, it determines how to route the payout based on your partner-level configuration, set up by Fruga during onboarding. You do not pass a routing destination in the claim request itself — the routing is always derived from your configuration.

There are two routing modes:

Option A — Pay the user directly (TO_USER)

Fruga pays the end user directly to their bank account. This is the default mode for most integrations. What happens after the claim depends on whether the user has already added their bank details in the widget.

When a user in ACTION_REQUIRED status adds their bank details via the widget, the payout is automatically unblocked and moves to PROCESSING. No further action is needed from your side.

Option B — Pay the partner (TO_PARTNER)

Fruga records the payout entitlement and settles the amount with you as the partner — either via periodic batch settlement or automated transfer, depending on your agreed arrangement. You are then responsible for passing the funds to your end user through whatever mechanism your platform uses.

In TO_PARTNER mode, the widget never asks the user for bank details — that interaction is handled entirely within your platform. The widget simply reflects the claim and its status.

Transaction status reference

Regardless of routing mode, every claim creates a payout transaction in Fruga’s system. Here are all the statuses a payout transaction can have and what they mean.

A complete example

The following shows a full cashback claim request in Node.js, including HMAC signing. This example uses the NEW_POLICY context and includes an optional policy reference.

import crypto from 'crypto';

const submitCashbackClaim = async ({ userRef, amount, eventId, policyId }) => {
  const partnerKey = process.env.FRUGA_PARTNER_KEY;
  const secret = process.env.FRUGA_SIGNING_SECRET;
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const path = '/cashback/claim';

  const body = JSON.stringify({
    partnerEventId: eventId,
    userRef,
    amount,
    redemptionContext: 'NEW_POLICY',
    reference: { policyId },
  });

  // Build the signature
  const bodyHash = crypto
    .createHash('sha256')
    .update(body)
    .digest('hex');

  const signingString = `${timestamp}.POST.${path}.${bodyHash}`;

  const signature = crypto
    .createHmac('sha256', secret)
    .update(signingString)
    .digest('base64');

  const response = await fetch('https://api.fruga.com/cashback/claim', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Partner-Key': partnerKey,
      'X-Partner-Timestamp': timestamp,
      'X-Partner-Signature': signature,
    },
    body,
  });

  if (!response.ok) {
    throw new Error(`Claim failed: ${response.status}`);
  }

  return response.status; // 201 created, 200 idempotent replay
};

Troubleshooting