RefundCam

Developers

API docs

One call creates a claim link. Send that link to your customer. When they have taken the photo, we post the result to your webhook.

Keys and test mode

Every call sends your secret key as a Bearer token. Keys that start with rpc_test_ create sandbox sessions: nothing is billed, and you can force any result with simulate. Keys that start with rpc_live_ are for real claims. Keep keys on your server, never in an app or a web page.

Base URL: https://api.refundcam.example

Create a claim link

POST /v1/sessions returns a link that is valid for 30 minutes.

FieldRequiredWhat it is
claim_refyesYour order or claim id, 1 to 128 characters.
categoryyesfood, apparel or other.
customer_refnoYour own customer id. Do not send names or phone numbers.
max_attemptsnoHow many tries the customer gets, 1 to 3.
localenoen or hi.
item_labelnoShown to the customer, for example “Blue running shoes”. Up to 200 characters.
return_urlnoAn https page on your allowlist to send the customer back to.
metadatanoUp to 20 string values, returned to you in the webhook.

Send an Idempotency-Key header so a retried request does not create a second link. A replay returns 200 with the header Idempotent-Replayed: true.

curl https://api.refundcam.example/v1/sessions \
  -H "Authorization: Bearer $RPC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-55821-R1" \
  -d '{
    "claim_ref": "ORD-55821-R1",
    "category": "apparel",
    "item_label": "Blue running shoes",
    "locale": "en"
  }'
// Node 18+ (server side)
const res = await fetch('https://api.refundcam.example/v1/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RPC_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ORD-55821-R1',
  },
  body: JSON.stringify({ claim_ref: 'ORD-55821-R1', category: 'apparel' }),
});
const session = await res.json();
// send session.url to your customer by SMS, WhatsApp or email

Response 201 Created:

{
  "id": "ses_9fK2mQ7xL4pR8tVb",
  "url": "https://capture.refundcam.example/#…",
  "expires_at": "2026-11-21T10:30:00Z",
  "status": "created",
  "sandbox": true
}

Get the result by webhook

We send a POST with a JSON body to the webhook URL in your dashboard. Event types:

HeaderWhat it is
X-RPC-EventUnique event id. Use it to ignore a delivery you have already handled.
X-RPC-Event-TypeOne of the event types above.
X-RPC-Signaturet=<unix seconds>,v1=<hex>. During a secret rotation there can be more than one v1.
X-RPC-Delivery-Attempt1 for the first try, then 2, 3 and so on.

Answer with any 2xx within 5 seconds. If you don’t, we try again after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours.

Example session.completed body (shortened):

{
  "id": "ses_9fK2mQ7xL4pR8tVb",
  "claim_ref": "ORD-55821-R1",
  "status": "completed",
  "decision": {
    "band": "review",
    "p_fake": 0.71,
    "calibration": null,
    "reason": "Worth a look by your team."
  },
  "attempts": [ … ]
}

Check the signature

The signature is an HMAC-SHA256 of <t>.<raw body> with your webhook secret, written in hex. Check it against the raw body, before parsing the JSON, and reject events older than 5 minutes.

// Express example
import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.post('/refundcam/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-RPC-Signature') ?? '';
  const parts = header.split(',').map((p) => p.split('='));
  const t = Number(parts.find(([k]) => k === 't')?.[1]);
  const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400);

  const expected = crypto
    .createHmac('sha256', process.env.RPC_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`)
    .digest('hex');
  const ok = sigs.some((s) => s.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  // save event.decision.band against event.claim_ref, then:
  res.sendStatus(200);
});

What the result means

bandCustomer sawWhat to do
passThank youNothing suspicious was found. That is not proof the claim is true; handle it as usual.
retakePlease retakeThe customer used all tries without a usable photo. Ask again or handle by hand.
reviewThank youWorth a look by your team. A person decides; RefundCam never refuses a refund by itself.

RefundCam catches some AI edits, not all. Use the result as one input to your refund process.

Read, delete and simulate

curl -X POST https://api.refundcam.example/v1/sessions/ses_9fK2mQ7xL4pR8tVb/simulate \
  -H "Authorization: Bearer $RPC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"band":"review"}'

Questions about the API? Start a free pilot and we will set you up with test keys.