REST API and webhooks | Krealo Wallet

Authentication

Create a key in the dashboard (API & webhooks). Each key gives access to a single business. Send it in the Authorization header.

Authorization: Bearer kw_live_…

Errors and limits

Errors return { "error": { "code", "message" } } with the matching HTTP status (400, 401, 402 subscription inactive, 403 plan without API, 404, 429). Limits: 300 requests per minute per key, and a daily quota by plan (trial 500, Pro 10,000, Business 100,000). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After (seconds).

Idempotency

Operations that issue a pass or move a balance accept an Idempotency-Key header: the same key within 24 h returns the same response without repeating the operation (Idempotent-Replayed: true header).

Endpoints

Every route, generated from our OpenAPI 3.1 contract. Open a route to see a curl example.

https://krealowallet.com/api/v1/openapi.json

Postman → Import → paste the URL of the OpenAPI contract. Insomnia, Bruno and SDK generators take it too.

Import into Postman

Templates

Company

Customers

Passes

Movements

Notifications

Webhooks

Example: issue a card and add a stamp

curl -X POST https://krealowallet.com/api/v1/passes \
  -H "Authorization: Bearer kw_live_…" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"TEMPLATE_ID","customer":{"name":"Demo Customer","email":"demo@example.com"}}'

curl -X POST https://krealowallet.com/api/v1/passes/PASS_ID/stamps \
  -H "Authorization: Bearer kw_live_…" \
  -H "Content-Type: application/json" -d '{"count":1}'

Webhooks

We send a JSON POST to your HTTPS URL for every event. Reply 2xx within 10 s; otherwise we retry after 1 min, 5 min, 30 min, 2 h and 12 h. Verify the signature with the secret you got at creation.

customer.created (customer created, from any source), pass.voided (card voided), pass.expired (card reached its end date, once), reward.ready (the customer reaches a reward, once per threshold). In the dashboard, “Send a test event” sends a signed ping event; a failed delivery can be resent. After 3 events in a row cannot be delivered, the webhook is disabled and admins get an email.

pass.issuedpass.installedpass.removedpoints.changedreward.redeemedbalance.changedcustomer.createdpass.voidedpass.expiredreward.ready

POST https://your-server.example/hook
Krealo-Event: points.changed
Krealo-Signature: t=1760300000,v1=5f2b…

{ "id": "evt_…", "type": "points.changed", "created": "2026-10-12T20:00:00.000Z",
  "data": { "pass": { "id": "…", "stamps": 4, … }, "movement": { "operation": "sumar", "before": 3, "after": 4 } } }

Verify the signature (Node.js)

import crypto from 'node:crypto';

// header = req.headers['krealo-signature'], body = the RAW body (string, before JSON.parse)
export function verify(header, body, secret) {
  if (typeof header !== 'string') return false;
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(parts.v1, 'hex'), Buffer.from(expected, 'hex'));
}

Shopify

Install the Krealo Wallet app in your store, then link it to your business from the dashboard (Integrations → Shopify). Every paid order adds stamps or points to the chosen card, and every new customer gets the welcome card; its install link is saved in the customer metafield krealo_wallet.install_url. Included in every plan.

No need to wait for the app: the Shopify Flow guide

Shopify Flow → Krealo Wallet (no app needed)

Every paid order adds a stamp, points or cashback to the customer’s card, and creates the card if they don’t have one yet. You need the Pro or Business plan of Krealo Wallet and a Shopify Grow, Advanced or Plus store (Flow’s “Send HTTP request” action isn’t available on Basic). It takes about 10 minutes.

In Krealo Wallet, open Integrations → API and keys and create a key. Copy it right away (it starts with kw_live_ and is shown only once).
Still in Krealo Wallet, open Cards, then the loyalty card to use (it must be published). Its id is the end of the address in your browser, after /plantillas/: copy it.
In Shopify, install the free Shopify Flow app from the Shopify App Store, open it and create a workflow.
Choose the “Order paid” trigger.
Add the “Send HTTP request” action. HTTP method: POST. URL: https://krealowallet.com/api/v1/purchases
Headers: add Key “Authorization” with Value “Bearer”, a space and your key; then Key “Content-Type” with Value “application/json”. Tip: save the key with “Add secret” so it’s never shown in plain text.
Body: paste the text below and replace TEMPLATE_ID with the id copied in step 2. Shopify fills in the {{…}} for each order: don’t change them.
For 4XX responses choose “Fail”; for 5XX/429 keep “Retry”. Nothing is counted twice: the same order sent twice is added once.
Turn on the workflow.

Body to paste:

{
  "template_id": "TEMPLATE_ID",
  "email": "{{order.email}}",
  "phone": "{{order.phone}}",
  "name": "{{order.customer.displayName}}",
  "amount": "{{order.totalPriceSet.shopMoney.amount}}",
  "order_id": "{{order.id}}",
  "source": "shopify-flow"
}

Test it: place a test order with your own email and capture the payment. In Shopify Flow, the run history shows the response (200 = all good). In Krealo Wallet, open Customers: the customer shows up with their card and the movement in its history. On the first order, the response includes install_links: the link to add the card to Apple Wallet or Google Wallet.

When a card is created by POST /purchases (Shopify Flow), the customer gets it by email if they have an address. With Twilio connected, they also get it by text if they have a phone: a short message in their language (FR, EN, ES) with your business name and the install link (shortened with Krealo QR if connected). Customers who reply STOP get no more texts. Card sent by email and text message (Twilio)

Common problems

401: the key is missing or miscopied. Check “Bearer” + space + the full key, or create a new one.
403: your Krealo Wallet plan doesn’t include the API. Upgrade to Pro or Business.
400 “email or phone is required”: the order has neither an email nor a phone (walk-in sale). Nothing is added; that’s expected.
400 on template_id or 404: the card id is miscopied, or it isn’t a loyalty card (stamps, points or cashback).

Card sent by email and text message (Twilio)

When a card is created by POST /purchases (Shopify Flow), the customer gets it by email if they have an address. With Twilio connected, they also get it by text if they have a phone: a short message in their language (FR, EN, ES) with your business name and the install link (shortened with Krealo QR if connected). Customers who reply STOP get no more texts.

In Krealo Wallet, open Integrations → Twilio (SMS) (Pro or Business plan).
Paste the Account SID and Auth Token from your Twilio console (Account Info), or an API key (SK… + secret).
Sender: your Twilio number (+15145550000) or a Messaging Service SID (MG…). Click Connect Twilio: the credentials are checked with Twilio, then encrypted.
Send a test SMS to your number. The card shows Connected.

In the API: send_email and send_sms (true by default in /purchases when the card is created); in POST /passes and the MCP tool issue_pass, enviarCorreo and send_sms are optional. The response has email_sent and sms_sent {sent, error}. Without Twilio, sms_sent.error is twilio_not_configured and the email goes out as usual.

MCP server (Claude and other agents)

Manage your cards from Claude: add a custom connector with the URL below. You sign in with your account (OAuth) and pick the business; an agent that cannot do OAuth can use an API key.

https://krealowallet.com/mcp

Zapier

Connect Krealo Wallet to 7,000+ apps without writing code. Triggers: pass issued, reward redeemed, customer created. Actions: create a customer, issue a pass (with its install link), add stamps.

The Zapier app is invite-only for now: open the link below (or ask Krealo for it) and accept the invite.
In Zapier, create a Zap and search for “Krealo Wallet”.
When connecting, paste an API key (see Authentication); the connection is named after your business.

Accept the Zapier invite

“Add to my Wallet” button

Add a button to your website that opens the sign-up for your loyalty card or coupon. Each card’s code is in the dashboard (Sign-up link and QR): paste it where the button should appear.

<script src="https://krealowallet.com/embed.js" data-carte="/u/ORG_ID/CARD_ID" data-lang="en" async></script>

data-carte takes the /u/… path or the full sign-up URL. Without data-lang, the button follows the page language (fr, en or es). It works with a strict CSP: just add https://krealowallet.com to script-src.

Krealo Wallet API

Authentication

Errors and limits

Idempotency

Endpoints

Templates

GET /templatesList templates

POST /templatesCreate a template

GET /templates/{id}Get a template

PATCH /templates/{id}Update a template (only the fields sent)

POST /templates/{id}/imageUpload the logo or icon of a template (PNG by https URL or base64), resized like the panel does

Company

GET /companyGet the company profile (shown on the back of every pass)

PATCH /companyUpdate the company profile (only the fields sent; branches replaces the list). Passes update.

PUT /company/logoUpload the company logo (PNG by https URL or base64)

POST /company/branchesAdd a branch

PATCH /company/branches/{index}Edit a branch (index from 0; only the fields sent)

DELETE /company/branches/{index}Remove a branch (index from 0)

Customers

GET /customersList or search customers

POST /customersCreate a customer

GET /customers/{id}Get a customer

PATCH /customers/{id}Update a customer

DELETE /customers/{id}Delete a customer; their passes are voided and anonymized

Passes

GET /passesList passes

POST /passesIssue a pass (returns the install links)

GET /passes/lookupFind a pass by the code scanned at the counter (serial or pass id)

GET /passes/{id}Get a pass

POST /passes/{id}/stampsAdd stamps

POST /passes/{id}/pointsAdd points

POST /passes/{id}/purchaseRecord a purchase (stamp, points or cashback)

POST /purchasesRecord a purchase by customer email or phone: finds or creates the customer, issues the pass if needed (Shopify Flow, POS). Idempotent by order_id

POST /passes/{id}/redeemRedeem a reward, a coupon use or a balance amount

POST /passes/{id}/balanceGift card balance: load, charge or set

POST /passes/{id}/voidVoid a pass

Movements

GET /passes/{id}/movementsHistory of a pass, newest first

GET /movementsEvery movement since a date, oldest first (sync a POS or a CRM)

Notifications

GET /notificationsLast 50 notifications

POST /notificationsSend a notification to the lock screen

Webhooks

GET /webhooksList webhooks

POST /webhooksCreate a webhook (the secret is returned once)

DELETE /webhooks/{id}Delete a webhook

GET /webhooks/{id}/deliveriesLast 50 deliveries of a webhook

Example: issue a card and add a stamp

Webhooks

Verify the signature (Node.js)

Shopify

Shopify Flow → Krealo Wallet (no app needed)

Common problems

Card sent by email and text message (Twilio)

MCP server (Claude and other agents)

Zapier

“Add to my Wallet” button