Start here — the ReGenerate Retailer API

Two environments

The sandbox has the same catalogue as production: the same public codes (RG-…), names, values and your prices. A key belongs to the environment that issued it, and each environment has its own portal, account and address list.

1. Sign in to the portal

Your account manager opens the account and you receive an invitation from no-reply@regenerate.co.il. It is written in Hebrew — the subject is “הזמנה לפלטפורמת ReGenerate” — and the link in it is valid for 72 hours and once.

The link asks for a password: at least 8 characters, with an upper-case letter, a lower-case letter, a digit and a symbol. Then it pairs an authenticator app (Google Authenticator, Microsoft Authenticator, 1Password or any TOTP app): scan the picture, or on the phone that holds the app press “Add to authenticator app”, or copy the key by hand. Enter the six digits it shows.

From then on every sign-in asks for a six-digit code, and so does every sensitive action in the portal: issuing, rotating or revoking a key, changing the address list or the Active switch, showing or downloading codes. A code works once; wait for the next one if you need two.

A link that expired can be sent again from the page it opens. Signing in, the portal opens on Overview.

2. The address list

Overview → API credentials → “Where your integration may call from”. List the addresses your integration calls from: single addresses, or blocks no wider than /24 (IPv4) or /64 (IPv6).

On the sandbox the list is optional: without one, any address may call. On production it is required: until a list is saved, every token request is refused with forbidden and a message naming this page; a saved production list can be replaced but not emptied.

List the address of the server that calls, not of the browser you are reading this in. From that server, curl -s https://checkip.amazonaws.com prints it. The portal shows the address your browser comes from, which is only the same when the browser and the integration share an office connection.

The Active switch beside the list stops every call with this environment’s keys at once, until it is switched on again.

3. Get a key

Overview → API credentials → “Issue a key” (or “Rotate key” when one exists), and a fresh code. The key is shown once, in that dialog: copy it into your secret store before closing. We keep a hash, not the key, so it cannot be shown again.

Rotating issues a new key and keeps the old one working for 24 hours, so a fleet of tills can move without an outage. Revoke, beside each key, stops that key at once — the key in the wrong hands case — and the tokens it issued stop with it.

4. The calls, in one shell

Run the first block — it sets BASE and asks for your key — then run the blocks in order in the same shell (bash or zsh); each uses what the ones before it set. You need curl and jq. Amounts are integers in minor units: agorot for shekels, cents for dollars.

# Once per shell. Sandbox first; for production change these two lines only.
BASE=https://api-sandbox.regenerate.co.il/v1
# Paste the rg_test_ key when asked; read -s keeps it off the screen and out of your history.
printf 'API key: '; read -rs KEY; echo

# A token, valid for one hour. The key goes to this endpoint and no other.
TOKEN=$(curl -s -X POST "$BASE/auth/token" \
  -H 'content-type: application/json' \
  -d "{\"apiKey\":\"$KEY\"}" | jq -r .accessToken)
echo "token: ${TOKEN:0:12}..."

# The wallet, in agorot: 200000 is ₪2,000.00.
curl -s "$BASE/balance" -H "authorization: Bearer $TOKEN"

# The catalogue at your price. One entry per SKU.
curl -s "$BASE/catalog" -H "authorization: Bearer $TOKEN" | jq '.items[0]'

# The cheapest fixed-value card you can buy now:
SKU=$(curl -s "$BASE/catalog" -H "authorization: Bearer $TOKEN" \
  | jq -r '[.items[] | select(.available and .pricingMode == "fixed")] | sort_by(.price) | .[0].sku')
echo "sku: $SKU"

# Whether it sells now, and how many you may order at once.
curl -s "$BASE/catalog/$SKU/availability" -H "authorization: Bearer $TOKEN"

# Your reference is the idempotency key: unique per order, the same on every retry.
REF="TILL-0001-$(date -u +%Y%m%d%H%M%S)"
curl -s -X POST "$BASE/orders" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d "{\"sku\":\"$SKU\",\"quantity\":1,\"reference\":\"$REF\"}"

# The same request again is the same order, not a second one: 200 instead of 201.
curl -s -o /dev/null -w '%{http_code}\n' -X POST "$BASE/orders" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d "{\"sku\":\"$SKU\",\"quantity\":1,\"reference\":\"$REF\"}"

# Poll until the order is final (or register a webhook and be told).
until curl -s "$BASE/orders/$REF" -H "authorization: Bearer $TOKEN" \
  | jq -e '.status == "delivered" or .status == "failed" or .status == "refunded"' > /dev/null
do sleep 3; done
curl -s "$BASE/orders/$REF" -H "authorization: Bearer $TOKEN" | jq '{status, codesAvailable}'

# The codes. Store them: this is a retrieval endpoint, not a vault.
curl -s "$BASE/orders/$REF/codes" -H "authorization: Bearer $TOKEN" | jq '.codes'

# A day of orders, for reconciliation (dates are calendar days in Israel time).
curl -s "$BASE/orders?from=$(date -u +%Y-%m-%d)&to=$(date -u +%Y-%m-%d)&pageSize=50" \
  -H "authorization: Bearer $TOKEN" | jq '{total, first: .items[0].reference}'

5. The same orders in the portal

Every order your integration places is in the portal under Order reports, with your reference beside it; search by reference or order id, and filter by dates and product. “Export to Excel” gives the list of orders — no codes in it, and no code needed.

The codes of an order are there too, behind a fresh code. An order of one card offers “Show code”: the code is on screen with a Copy button for 60 seconds, then hidden. An order of several cards offers “Download Excel”: the codes go into a file, one row per code, and never onto the screen.

6. Refunds and failures

An order moves created → processing → delivered. If the supplier refuses it, it goes to failed and then refunded, and the price is back in the wallet — check GET /balance. A short supplier outage is retried for up to fifteen minutes while the order stays processing; only then does it fail and refund.

A delivered order can still become refunded later, when the Admin refunds it on your request.

After failed or refunded, place a new order with a new reference if you still want the card. Never retry a refused or refunded order under its old reference: that returns the old order.

7. Every error, and what to do

Every refusal has the same body: {"error":{"code","message","requestId"}}. Branch on code; the message is for people and may change. Retry only what this table says is safe, and always with the same reference.

8. Rate limits

60 requests a minute per key. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refusal is 429 with Retry-After in seconds. A reconciliation job on its own key cannot use up your tills’ allowance. A higher limit is a setting on your account: ask your account manager.

9. Moving to production

Change the base URL and the key, nothing else. The public codes, names, values and your prices are the same on both sides, so the code that works on the sandbox works on production unchanged.

Before the first call: sign in to the production portal (a separate invitation), save the address list there — production refuses every call without one — and issue an rg_live_ key. Production spends your real wallet and delivers real cards.

Request collection

The same calls as a Postman collection, with an environment for each side. Import all three, choose the sandbox environment, paste your key into apiKey, and run the requests in order: the token request stores the token, the catalogue request picks a SKU, and the order request makes its own reference.

• The collection regenerate-retailer-api.postman_collection.json
• Sandbox environment regenerate-sandbox.postman_environment.json
• Production environment regenerate-production.postman_environment.json