Embed & SDKs

Security model (required)

[Claim widget / Shopify theme]
        │  claimCode + destinationWallet only
        ▼
[Your backend / Shopify App Proxy]  ← API key + HMAC live here
        │  JWT + X-Timestamp + X-Signature
        ▼
POST https://api.coinharbour.co.za/v1/claims/redeem

• Never put coinharbour.co.za_live_ / coinharbour.co.za_test_ or HMAC secrets in front-end JS, React bundles, Liquid, or mobile apps.
• Serve the redeem proxy over HTTPS. Validate wallet format (0x + 40 hex) before calling us.
• Rate-limit your proxy; optionally require a logged-in session on your site before redeem.

1. React widget

Copy examples/widget/CoinHarbourClaim.tsx into your app:

import { CoinHarbourClaim } from './CoinHarbourClaim';

export function RewardsPage() {
  return (
    <CoinHarbourClaim redeemUrl="/api/coinharbour/redeem" />
  );
}

2. Vanilla JS include

<div id="ch-claim"></div>
<script src="https://YOUR_CDN_OR_ORIGIN/examples/coinharbour-claim.js"></script>
<script>
  CoinHarbourClaim.mount('#ch-claim', {
    redeemUrl: '/api/coinharbour/redeem',
  });
</script>

Local portal copy: /examples/coinharbour-claim.js

3. Node.js (Express) proxy

Full file: examples/server-node/redeem-proxy.js

# Env
COINHARBOUR_API_BASE=https://api.coinharbour.co.za/v1
COINHARBOUR_API_KEY=coinharbour.co.za_test_…
COINHARBOUR_HMAC_SECRET=coinharbour.co.za_hmac_…

node redeem-proxy.js
# Widget posts to http://localhost:8080/api/coinharbour/redeem

4. PHP proxy

Drop examples/server-php/redeem.php behind your web server; set the same three env vars; point redeemUrl at that script.

$payload = $ts . '.POST./v1/claims/redeem.' . $raw;
$sig = hash_hmac('sha256', $payload, $hmacSecret);

5. C# (ASP.NET Minimal API)

Use examples/server-csharp/RedeemProxy.cs as Program.cs. Same env vars; route POST /api/coinharbour/redeem.

6. Shopify store module

Scaffold under examples/shopify/:

• Theme app extension: claim form block (Liquid + JS).
• App Proxy: POST /apps/coinharbour/redeem signs and forwards to CoinHarbour.
• Merchant installs the app, adds the block in the theme editor. No secrets in the storefront.

1. Create a Shopify app (Remix) in Partners.
2. Copy extension + route from examples/shopify.
3. Configure App Proxy subpath coinharbour.
4. Set COINHARBOUR_* on the app host (sandbox keys first).
5. Deploy, install on a dev store, place the claim block, redeem a sandbox claim code.

Details: examples/shopify/README.md in the zip / repo.

Issuing codes vs claiming

• Issue (your backend only): POST /v1/claims/issue after crediting points, usually from CRM/POS when a reward is earned.
• Claim UI (this page): end user pastes the code + wallet; your proxy calls POST /v1/claims/redeem.

Full auth/HMAC walkthrough: Integration guide.