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.
| Field | Required | What it is |
|---|---|---|
claim_ref | yes | Your order or claim id, 1 to 128 characters. |
category | yes | food, apparel or other. |
customer_ref | no | Your own customer id. Do not send names or phone numbers. |
max_attempts | no | How many tries the customer gets, 1 to 3. |
locale | no | en or hi. |
item_label | no | Shown to the customer, for example “Blue running shoes”. Up to 200 characters. |
return_url | no | An https page on your allowlist to send the customer back to. |
metadata | no | Up 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:
session.completed: the customer took the photo and it has a result.session.abandoned: the customer left without finishing.session.expired: the link was not used within 30 minutes.
| Header | What it is |
|---|---|
X-RPC-Event | Unique event id. Use it to ignore a delivery you have already handled. |
X-RPC-Event-Type | One of the event types above. |
X-RPC-Signature | t=<unix seconds>,v1=<hex>. During a secret rotation there can be more than one v1. |
X-RPC-Delivery-Attempt | 1 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
band | Customer saw | What to do |
|---|---|---|
pass | Thank you | Nothing suspicious was found. That is not proof the claim is true; handle it as usual. |
retake | Please retake | The customer used all tries without a usable photo. Ask again or handle by hand. |
review | Thank you | Worth 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
GET /v1/sessions/:idreturns the session and, once finished, the same result as the webhook.DELETE /v1/sessions/:iddeletes the session and all its photos and frames. Returns204.GET /v1/photos/:idreturns a photo for your review screen.POST /v1/sessions/:id/simulatewith{"band":"pass"|"retake"|"review"}finishes a sandbox session with that result and sends the webhook. Test keys only.
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.