SectionsOverview
The plusmore RaaS API
One API instead of a deal with every gift card brand. With it a partner resells plusmore’s live gift card catalogue and keeps the full rate on every sale. Demo store open now. Sandbox open now. Go live in the partner portal. Start with the sandbox below; the v1 reference after it is the contract the sandbox and the live API both serve.
A live gift card catalogue
Amounts and live availability for each gift card brand, refreshed as gift card stock moves.
A float you control
Fund it in USDC on Base to your own float address; orders never spend more than is credited.
One quote, one order
A quote right before you take your buyer’s money, then an order with your own idempotency key.
Idempotent by design
The same order reference always replays the same gift card; a payment can never issue two.
A sandbox to start
Create a key with no name and no email, then build on the real API with demo gift cards.
Every order, tracked
Follow every order by its reference, from its quote to the gift card’s delivery and its events.
Try the sandbox
The sandbox is the plusmore RaaS API with nothing real behind it. Every call, every error and every event behaves as it will in production, against two fictional brands, Demo Coffee and Demo Books, with a test balance and demo gift card codes that have no value. Nothing you do in the sandbox can move real money.
Get a key in one click. Press Create a sandbox key. We ask for no name and no email. You get three values, shown once:
| Value | Looks like | What it is for |
|---|---|---|
| API key | pmr_test_ then a key id and a secret | the Authorization: Bearer header of every request |
| Signing secret | pmrsig_test_... | signing every request (never sent) |
| Webhook secret | pmrwh_test_... | checking the signature of every event (never sent) |
Store all three in your secrets manager. A sandbox key starts with a test balance of 100 US dollars, works for 30 days, and can be revoked by its holder at any time (POST /v1/sandbox/keys/revoke). An address can create two keys a day. A key and everything it made are deleted 2 days after the key expires.
Create a sandbox key
No name and no email. One press runs a short security check, then your API key, signing secret and webhook secret appear here, shown once.
What is in the sandbox
| Gift card | Slug | Amounts | Rate |
|---|---|---|---|
| Demo Coffee (US, USD) | demo-coffee | 10.00, 25.00, 50.00 | 5% |
| Demo Books (GB, GBP) | demo-books | any amount from 10.00 to 100.00 | 3% |
| Demo Books, limited today | demo-limited | 10.00 to 50.00 today | 3% |
Your cost is the face value less the rate: cost_minor = face_minor - floor(face_minor * rate_bps / 10000). Your balance is in US dollars with six decimals (usd6); the sandbox converts at fixed rates (1 GBP = 1.25 USD), never market rates.
Test values. Each one reaches a path you must handle in production:
| Send | You get |
|---|---|
Demo Books at 13.37 (face_minor 1337) | 503 restocking, retry after an hour |
| Demo Books at 66.60 | 502 upstream_failed, nothing charged; retry with the same client_ref |
| Demo Books at 99.99 | 409 price_changed with the new cost (122.50 US dollars, above a new key's 100) and a fresh quote in details; fund first, then order again with that quote_id (quickstart step 8) |
demo-limited above 50.00 | 409 denomination_unavailable (limited today) |
end_customer.country XX | 451 region_blocked |
a client_ref starting pending- | the first one each day answers 202 pending and issues 30 seconds later |
Codes. Every issued order carries a code like DEMO-7K2M-Q9XA-4TBC. Its link opens a page that says "Demo gift card. It has no value." Demo codes can never be redeemed anywhere.
Funding. A live float takes USDC on Base, and GET /v1/funding answers the live shape here too: asset USDC, chain_id 84532 (Base Sepolia, simulated), no token_address or deposit_address in the sandbox, and the notice: "Float top ups can take up to 3 days to arrive." Every deposit row carries asset USDC and its amount_usd6. In the sandbox, POST /v1/sandbox/deposits/simulate with { "plus_amount": "100" } credits your test balance at once, converted at a fixed reference price of 3.00 US dollars per test PLUS, less the 0.30% pool fee: at most 10,000 test PLUS a deposit and 50 deposits a key.
Events. v0 sends no webhooks out. GET /v1/sandbox/events shows every event as the delivery your endpoint would get: the raw body and the real plusmore-signature header, signed with your webhook secret at the time you read it, so you can test your verification today. POST /v1/sandbox/webhooks/test makes a test event of any type (50 a key).
Quickstart (curl)
Every request carries the API key and a signature. The signature is an HMAC-SHA256, keyed by your signing secret, over seven lines joined by a newline:
v1
<METHOD>
<path>
<query, sorted by name, RFC 3986 encoded, or an empty line>
<x-plusmore-timestamp: unix seconds, within 300 seconds of our clock>
<x-plusmore-nonce: a new UUID for every request>
<hex SHA-256 of the raw body; for a GET, of zero bytes>and is sent as x-plusmore-signature: v1=<hex>. In the query a space is %20 and a plus sign is %2B: a raw +, a raw space or a # anywhere in the request target is refused with 400 invalid_request, so there is one way to write each request and the signature covers exactly what we read. A POST /v1/orders also carries Idempotency-Key, equal to the body's client_ref. When a signature fails, the sandbox answers 401 signature_invalid with an x-plusmore-signature-debug header that holds the reason, the SHA-256 it computed for your body and the exact string it signed (base64url): compare it with yours. Production never explains a failure.
1. Set your values and the signing function (bash, curl and openssl; nothing to install on macOS or Linux)
export RAAS_API_KEY='pmr_test_...'
export RAAS_SIGNING_SECRET='pmrsig_test_...'
# plusmore_call METHOD PATH [CANONICAL_QUERY] [BODY]: one signed request to the sandbox
plusmore_call() {
local METHOD="$1" REQ_PATH="$2" CANONICAL_QUERY="${3:-}" BODY="${4:-}"
local TS NONCE BODY_SHA CANONICAL SIG URL
if [[ "$REQ_PATH$CANONICAL_QUERY" == *[\ +#]* ]]; then
echo 'encode a space as %20 and a plus sign as %2B: a raw space, + or # is refused' >&2
return 2
fi
TS=$(date +%s)
NONCE=$(uuidgen | tr 'A-Z' 'a-z')
BODY_SHA=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
CANONICAL=$(printf 'v1\n%s\n%s\n%s\n%s\n%s\n%s' "$METHOD" "$REQ_PATH" "$CANONICAL_QUERY" "$TS" "$NONCE" "$BODY_SHA")
SIG=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$RAAS_SIGNING_SECRET" -hex | sed 's/^.* //')
URL="${RAAS_BASE:-https://raas-sandbox.plusmore.xyz}$REQ_PATH"
if [ -n "$CANONICAL_QUERY" ]; then URL="$URL?$CANONICAL_QUERY"; fi
local ARGS=(-sS -X "$METHOD" "$URL"
-H "Authorization: Bearer $RAAS_API_KEY"
-H "x-plusmore-timestamp: $TS" -H "x-plusmore-nonce: $NONCE" -H "x-plusmore-signature: v1=$SIG")
if [ -n "$BODY" ]; then ARGS+=(-H "content-type: application/json" --data-binary "$BODY"); fi
if [ -n "${IDEMPOTENCY_KEY:-}" ]; then ARGS+=(-H "Idempotency-Key: $IDEMPOTENCY_KEY"); fi
curl "${ARGS[@]}"
}2. Check your key
plusmore_call GET /v1/ping3. List the catalogue (query parameters sorted by name)
plusmore_call GET /v1/catalogue 'country=GB&limit=10'4. Get a quote
plusmore_call POST /v1/quotes '' '{"slug":"demo-coffee","currency":"USD","face_minor":2500}'5. Place an order (the client_ref is your own id for the purchase; send the same one to retry safely)
IDEMPOTENCY_KEY=order-0001 plusmore_call POST /v1/orders '' \
'{"client_ref":"order-0001","slug":"demo-coffee","currency":"USD","face_minor":2500,"end_customer":{"ref":"customer-42","country":"GB"}}'The answer is 201 with the order and its demo code. Sending the same request again answers 200 with the same order and "replay": true, and charges nothing twice. Use an opaque id for end_customer.ref, never an email or a name: we keep only its SHA-256.
6. Read the order and your balance
plusmore_call GET /v1/orders/order-0001
plusmore_call GET /v1/balance7. See your events and check their signature
plusmore_call GET /v1/sandbox/events 'limit=5'Each delivery has raw_body and headers["plusmore-signature"] (t=<unix>,v1=<hex>). To check one, compute the HMAC-SHA256 of <t>.<raw body> keyed by your webhook secret, compare it with v1 in constant time, and refuse a t more than 300 seconds from your clock:
printf '%s' "$T.$RAW_BODY" | openssl dgst -sha256 -hmac "$RAAS_WEBHOOK_SECRET" -hex | sed 's/^.* //'Always check the signature over the raw bytes before you parse them, and deduplicate on plusmore-event-id. Events never carry a gift card code: read it with GET /v1/orders/{client_ref}.
8. Try a test value: a price change (Demo Books at 99.99)
After the price change this gift card costs 122.50 US dollars, more than a new key's 100 US dollar test balance, so fund your test balance first (20 test PLUS credit 59.82 US dollars):
plusmore_call POST /v1/sandbox/deposits/simulate '' '{"plus_amount":"20"}'
IDEMPOTENCY_KEY=order-0002 plusmore_call POST /v1/orders '' \
'{"client_ref":"order-0002","slug":"demo-books","currency":"GBP","face_minor":9999,"end_customer":{"ref":"customer-42","country":"GB"}}'The order answers 409 price_changed with the new cost and a fresh quote_id in details. Nothing was booked, so send the same order again with that quote:
IDEMPOTENCY_KEY=order-0002 plusmore_call POST /v1/orders '' \
'{"client_ref":"order-0002","slug":"demo-books","currency":"GBP","face_minor":9999,"quote_id":"<details.quote_id>","end_customer":{"ref":"customer-42","country":"GB"}}'The answer is 201 with the order at the new cost and its demo code.
Reference notes
- Envelope. Success:
{ "data": ..., "request_id": "req_..." }. Error:{ "error": { "code", "message", "request_id", "retry_after_sec"?, "details"? } }. Every sandbox answer carriesx-plusmore-env: sandboxandx-request-id. - Keys.
pmr_test_keys work only onraas-sandbox.plusmore.xyz; apmr_live_key there answers403 wrong_environment, and the reverse holds in production. - Limits in the sandbox. Per key, every second: 5 reads, 5 quotes, 2 orders and 2 other writes; per address, 30 requests a second. A too fast request answers
429 rate_limitedwithRetry-After. Per key, for its whole 30 days: 200 test orders, 50 simulated deposits and 50 test events; a spent limit answers429 limit_exceededwith the limit and its use (a new key starts afresh). New keys: two a day per address (one request a second) and up to 25 a day for the whole sandbox; when the day's keys are taken, key creation answers503 capacity_unavailableuntil the next UTC day. When the sandbox holds all the keys it can store, key creation answers503"The sandbox is full right now. Try again later."; keys already issued keep working. - Requests. JSON bodies of at most 8 KB; a request must reach us whole within 15 seconds; the query is RFC 3986 encoded (a space is
%20, a plus sign%2B), and a raw+or#in the request target answers400 invalid_request. - Quotes. A quote lives 60 seconds. An order that names an expired quote answers
409 price_changedwith a fresh quote indetails; order again with thatquote_id. - Statements.
GET /v1/statements?month=YYYY-MManswers the month's figures signed with Ed25519; check them against the key atGET /v1/sandbox/statement-key(fetch it once and pin it). - Not in the sandbox yet: outbound webhook delivery, and test funding on Base Sepolia with its faucet.
- Going live. Ready to sell? Go live at partners.plusmore.xyz. Live keys are created in the portal once the account is live, and activation is automatic: the plusmore RaaS Terms ticked and signed, the sanctions checks clear and the one off, non refundable 999 USDC go live fee matched. Every request and answer keeps the shape you built against here.
Authentication and signing
One contract, two hosts. The sandbox and the live API answer the same routes, the same shapes and the same errors; only the key and the host change. Every request carries your API key and a signature over the request itself.
| Environment | Base address | Keys |
|---|---|---|
| Sandbox | https://raas-sandbox.plusmore.xyz/v1 | pmr_test_ keys, self serve on this page |
| Live | https://raas.plusmore.xyz/v1 | pmr_live_ keys, created in the partner portal |
A key of one environment on the other host answers 403 wrong_environment. Each key comes with three values, shown once: the API key for the Authorization: Bearer header, a signing secret that signs every request and is never sent, and a webhook secret that checks every event. Every request carries:
| Header | Value |
|---|---|
Authorization | Bearer pmr_live_<key id>_<secret> |
x-plusmore-timestamp | Unix seconds, within 300 seconds of our clock |
x-plusmore-nonce | A new UUID for every request; a nonce used twice answers 401 nonce_reused |
x-plusmore-signature | v1= then the hex HMAC SHA 256 of the seven lines below, keyed by your signing secret |
Idempotency-Key | On POST /v1/orders only, equal to the body’s client_ref |
v1
<METHOD>
<path>
<query, sorted by name, RFC 3986 encoded, or an empty line>
<x-plusmore-timestamp: unix seconds, within 300 seconds of our clock>
<x-plusmore-nonce: a new UUID for every request>
<hex SHA-256 of the raw body; for a GET, of zero bytes>POST /v1/orders HTTP/1.1
Host: raas.plusmore.xyz
Authorization: Bearer pmr_live_<key id>_<secret>
x-plusmore-timestamp: 1793005200
x-plusmore-nonce: 3f0c9a52-6b1e-4d2a-9c77-0e5b8d41a6f3
x-plusmore-signature: v1=<hex HMAC SHA-256 of the seven lines, keyed by your signing secret>
Idempotency-Key: order-0001
content-type: application/jsonIn the query a space is %20 and a plus sign is %2B; a raw space, plus sign or # in the request target answers 400 invalid_request. The sandbox quickstart has a ready signing function in bash, and the open source starter carries one in TypeScript. The sandbox explains a failed signature in an x-plusmore-signature-debug header; the live API never explains a failure.
Scopes and keys
A key carries only the scopes you give it. A request outside them answers 403 scope_missing.
| Scope | Opens |
|---|---|
catalogue:read | the catalogue, one gift card, exchange rates and the summary |
quotes:write | quotes |
orders:write | placing orders |
orders:read | reading one order and the order list |
balance:read | your balance, holds and what is available |
funding:read | how to fund, and your deposits |
statements:read | your signed monthly statements |
events:read | the event feed |
Live keys are created and revoked in the partner portal, each step behind a code from your authenticator app. A key is shown once and never emailed; the portal shows when each key was last used, from which country and how many requests it made. To rotate, create a new key, deploy it, then revoke the old one with a grace period (24 hours by default); revoke at once after a suspected leak. A key may carry an IP allow list; a request from any other address answers 403 ip_not_allowed. Webhooks are managed in the portal, never with a key.
Money and numbers
| Suffix | Shape |
|---|---|
*_minor | An integer in the gift card’s own currency, in its smallest unit (face_minor: 2500 is 25.00) |
*_usd6 | An integer of US dollars with six decimals, the USDC unit on Base (cost_usd6: 23750000 is 23.75 US dollars) |
*_bps | An integer of basis points (rate_bps: 500 is 5.00%) |
*_at | An RFC 3339 time in UTC with a trailing Z |
Every gift card is sold at the rate our gift card supplier gives us, passed on in full: plusmore adds 0%. Your cost is the face value less the rate, cost_minor = face_minor - floor(face_minor * rate_bps / 10000), and your margin on a sale is the difference. Rates vary by brand and some are zero; read them from the catalogue rather than keeping them for long. Every answer is {"data": ..., "request_id": "req_..."}; every error is {"error": {"code", "message", "request_id", "retry_after_sec"?, "details"?}}.
any.{
"data": {
"partner_id": "pa_2k9d7f1q",
"environment": "production",
"key_id": "k3n8w2p6r4t1y7u5",
"scopes": [
"catalogue:read",
"quotes:write",
"orders:write",
"orders:read"
],
"expires_at": null,
"server_time": "2026-10-25T09:00:00Z"
},
"request_id": "req_7c1f0a2d9e4b"
}catalogue:read.| Field | Required | Description |
|---|---|---|
country | Optional | Two letters, ISO 3166 |
currency | Optional | Three letters, ISO 4217 |
q | Optional | A search term |
category | Optional | A category id from the catalogue |
cursor | Optional | The next_cursor of the page before |
limit | Optional | How many to return |
{
"data": {
"items": [
{
"slug": "demo-coffee",
"brand": "Demo Coffee",
"name": "Demo Coffee gift card",
"category": "food-and-drink",
"category_label": "Food and drink",
"country": "US",
"currency": "USD",
"rate_bps": 500,
"denominations": [
1000,
2500,
5000
],
"range": null,
"prices": [
{
"face_minor": 1000,
"cost_minor": 950,
"cost_usd6": 9500000
},
{
"face_minor": 2500,
"cost_minor": 2375,
"cost_usd6": 23750000
},
{
"face_minor": 5000,
"cost_minor": 4750,
"cost_usd6": 47500000
}
],
"availability": {
"state": "available",
"max_face_minor_today": null
},
"cash_equivalent": false,
"logo_url": "https://raas-sandbox.plusmore.xyz/v1/sandbox/art/coffee.svg",
"terms": "Demo gift card for the plusmore RaaS sandbox. It has no value and cannot be redeemed anywhere.",
"source": "supplier",
"demo": true
}
],
"total": 1,
"next_cursor": null
},
"request_id": "req_7c1f0a2d9e4b"
}source is always supplier. A gift card with availability.state limited sells amounts up to max_face_minor_today today; unavailable sells nothing today.
catalogue:read.catalogue:read.{
"data": {
"base": "USD",
"usd6_per_unit": {
"GBP": 1325236,
"EUR": 1140300,
"USD": 1000000
},
"fixed": false,
"as_of": "2026-10-25T09:00:00Z",
"source": "supplier"
},
"request_id": "req_7c1f0a2d9e4b"
}gift_cards as your one headline count and read it here; never type it. Scope catalogue:read.quotes:write.{
"slug": "demo-coffee",
"currency": "USD",
"face_minor": 2500
}{
"data": {
"quote_id": "qt_6YbN2kQx8RcW1mTz4vLp9a",
"slug": "demo-coffee",
"currency": "USD",
"face_minor": 2500,
"rate_bps": 500,
"cost_minor": 2375,
"cost_usd6": 23750000,
"sellable": true,
"code": "ok",
"expires_at": "2026-10-25T09:01:00Z"
},
"request_id": "req_7c1f0a2d9e4b"
}code is ok, insufficient_balance or restocking (and limit_exceeded in the sandbox, once a test allowance is spent); only ok is sellable. Call it right before you take your buyer’s money.
orders:write.| Field | Required | Description |
|---|---|---|
client_ref | Required | Your own id for the purchase: 1 to 128 letters, digits, _, ., : or -, equal to the Idempotency-Key header. Build it from the payment itself, never a new one on a retry. |
slug, currency, face_minor | Required | The gift card and the amount, as quoted |
end_customer.ref | Required | An opaque id for your customer, never an email or a name; only its SHA 256 is kept |
end_customer.country | Required | Two letters, the customer's country |
quote_id | Optional | A quote to honour while it lives; an expired one answers 409 price_changed with a fresh quote |
{
"client_ref": "order-0001",
"slug": "demo-coffee",
"currency": "USD",
"face_minor": 2500,
"end_customer": {
"ref": "customer-42",
"country": "GB"
}
}{
"data": {
"id": "ord_4m8q2x7c9v1b",
"client_ref": "order-0001",
"status": "issued",
"slug": "demo-coffee",
"brand": "Demo Coffee",
"currency": "USD",
"face_minor": 2500,
"rate_bps": 500,
"cost_minor": 2375,
"cost_usd6": 23750000,
"quote_id": null,
"end_customer": {
"ref_sha256": "<sha256 of your end customer ref>",
"country": "GB"
},
"voucher": {
"code": "DEMO-7K2M-Q9XA-4TBC",
"pin": null,
"redeem_url": "https://raas-sandbox.plusmore.xyz/sandbox/gift-card/DEMO-7K2M-Q9XA-4TBC",
"expires_at": null,
"demo": true,
"notice": null
},
"created_at": "2026-10-25T09:00:00Z",
"issued_at": "2026-10-25T09:00:01Z",
"replay": false,
"environment": "sandbox"
},
"request_id": "req_7c1f0a2d9e4b"
}client_ref with the same body answers 200 with the same order and replay: true, and never charges twice. The same client_ref with another body answers 409 idempotency_mismatch; one still being processed answers 409 order_in_progress. A 202 order issues later: read it with GET /v1/orders/{client_ref} or wait for order.issued. After 502 upstream_failed nothing was charged: retry with the same client_ref.orders:read.orders:read.balance:read.{
"data": {
"balance_usd6": 1250000000,
"held_usd6": 23750000,
"available_usd6": 1226250000,
"low_balance_usd6": 100000000,
"limits": {
"per_order_usd6": null,
"per_day_usd6": null,
"per_30_days_usd6": null,
"per_end_customer_per_day_usd6": null,
"max_balance_usd6": null,
"test_orders_per_day": null,
"test_orders_per_key": null
},
"as_of": "2026-10-25T09:00:00Z",
"environment": "production"
},
"request_id": "req_7c1f0a2d9e4b"
}Live, every field of limits is null. There are no order limits on your account. Your credited float pays for each order. In the sandbox the same object shows its test allowances.
funding:read.{
"data": {
"asset": "USDC",
"chain_id": 8453,
"token_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"deposit_address": "<your float address>",
"notice": "Float top ups can take up to 3 days to arrive.",
"plus_address": null,
"max_deposit_now_plus": null,
"conversion": null
},
"request_id": "req_7c1f0a2d9e4b"
}In the sandbox the same route answers asset USDC with chain_id 84532, no token or float address, and funds a test balance through POST /v1/sandbox/deposits/simulate. The PLUS conversion fields stay in the shape and are null live, and POST /v1/funding/quote answers 404 not_found live.
funding:read.{
"data": {
"deposits": [
{
"id": "dep_9h2k4m6p8r1t",
"state": "credited",
"hold_reason": null,
"source": "chain",
"asset": "USDC",
"token": "USDC",
"amount_usd6": 1000000000,
"credited_usd6": 1000000000,
"plus_amount": null,
"conversions": [],
"created_at": "2026-10-25T08:00:00Z",
"credited_at": "2026-10-25T09:00:00Z"
}
],
"next_cursor": null
},
"request_id": "req_7c1f0a2d9e4b"
}funding:read.statements:read.The answer carries the statement, the exact bytes signed in canonical (its JSON with sorted keys and no spaces) and the signature with its key_id. Check key_id against the statement key id the partner portal shows on its Statements page, then verify the signature over canonical with that key. In the sandbox the key is at GET /v1/sandbox/statement-key: fetch it once and pin it.
events:read.Float and funding
Your float is a prepaid USDC balance for this product. It pays the wholesale cost of each gift card you order. Each product has its own float and its own float address.
A live float takes USDC on Base only. GET /v1/funding names the asset, the chain (chain_id 8453), the USDC contract 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 and your float address. Send USDC on Base to that address and nothing else: another token or another network may be lost for good. Every deposit shows in GET /v1/deposits in one of three states, and orders spend only what is credited.
| State | Meaning |
|---|---|
detected | the transfer is on chain and recorded, not yet in your available float |
credited | the amount is in your available float and orders can spend it |
held | the deposit is held, with a hold_reason code; nothing of it can be spent until the hold ends |
Below your low balance level you get balance.low and a banner in the portal; with nothing available every order answers 402 insufficient_balance and books nothing.
Webhooks
Add an https endpoint in the partner portal and every event is sent to it, signed with the endpoint’s own secret, shown once.
| Events |
|---|
order.issued, order.failed, order.pending, deposit.detected, deposit.credited, deposit.held, balance.low, key.created, key.revoked, statement.ready |
Each delivery is a POST with the event as its body and a plusmore-signature header, t=<unix seconds>,v1=<hex>: the hex HMAC SHA 256 of <t>.<raw body>, keyed by your webhook secret. Check it over the raw bytes before you parse them, compare in constant time, refuse a t more than 300 seconds from your clock, and deduplicate on plusmore-event-id. Events never carry a gift card code.
import { createHmac, timingSafeEqual } from "node:crypto";
// header: the plusmore-signature header, "t=<unix seconds>,v1=<hex>"; rawBody: the bytes as received, before parsing
export function verifyEvent(rawBody: string, header: string, webhookSecret: string, nowSec = Math.floor(Date.now() / 1000)): boolean {
const parts = new Map(header.split(",").map((p) => p.split("=", 2) as [string, string]));
const t = Number(parts.get("t"));
const v1 = parts.get("v1") ?? "";
if (!Number.isInteger(t) || Math.abs(nowSec - t) > 300 || !/^[0-9a-f]{64}$/.test(v1)) return false;
const want = createHmac("sha256", webhookSecret).update(`${t}.${rawBody}`, "utf8").digest();
return timingSafeEqual(want, Buffer.from(v1, "hex"));
}The endpoint must answer on https at port 443 within 10 seconds; redirects are not followed and only public addresses are called. A failed delivery is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, then once a day for 3 days, then the endpoint is switched off and you are told. GET /v1/events always has the full feed.
Limits
How fast a key may call. There are no order limits on your account. Your credited float pays for each order.
| Requests, per key | Rate |
|---|---|
| Reads | 20 a second, bursts of 60 |
| Quotes | 10 a second |
| Orders | 5 a second, bursts of 10 |
A request too fast answers 429 rate_limited with Retry-After. The sandbox has its own lower rates and test allowances, in the reference notes above; a spent allowance answers 429 limit_exceeded there.
Errors
One code, one HTTP status and one next step each, the same in the sandbox and live, except a code marked sandbox only, which the live API never sends. A message never quotes what you sent; the field it is about is in details.
| HTTP | Code | Meaning | Retry |
|---|---|---|---|
| 400 | invalid_request | The request is not valid. | No |
| 400 | field_not_allowed | The request carries a field that is not allowed. | No |
| 400 | idempotency_key_required | Send an Idempotency-Key header equal to the client_ref in the body. | No |
| 401 | unauthorized | Send a valid API key in the Authorization header. | After you fix the request |
| 401 | signature_invalid | The request signature is missing or does not match. | After you fix the request |
| 401 | timestamp_out_of_window | The request timestamp is more than 300 seconds away from our clock. | After you fix the request |
| 401 | nonce_reused | That nonce was already used. Send a new nonce with every request. | After you fix the request |
| 402 | insufficient_balance | Your available balance does not cover this gift card. Nothing was booked. | After you fund your float |
| 403 | scope_missing | This key does not have the scope this request needs. | No |
| 403 | ip_not_allowed | This key does not accept requests from your address. | No |
| 403 | wrong_environment | This key belongs to the other environment. | No |
| 403 | partner_not_live | This account is not live yet. | No |
| 403 | partner_suspended | This account is suspended. | No |
| 403 | origin | Call the API through its public address. | No |
| 404 | not_found | Not found. | No |
| 404 | not_sold | This gift card cannot be sold. | No |
| 409 | denomination_unavailable | This amount is not available for this gift card. | As the message says |
| 409 | price_changed | The price changed. The new cost and a fresh quote are in the details. | As the message says |
| 409 | idempotency_mismatch | That client_ref was already used for a different order. | No |
| 409 | order_in_progress | An order with that client_ref is being processed. Try again in a few seconds. | As the message says |
| 422 | cash_equivalent_excluded | This gift card is not available to partners. | No |
| 429 | rate_limited | Too many requests. Try again after the Retry-After time. | After the Retry-After time |
| 429 | limit_exceeded Sandbox only | A limit on your account was reached. Sent by the sandbox only, when a test allowance of a sandbox key is spent. The live API has no order limits and never sends it. | After the Retry-After time |
| 451 | region_blocked | This service is not available in that region. | No |
| 502 | upstream_failed | The gift card could not be issued and nothing was charged. Retry with the same client_ref. | Yes, with the same client_ref |
| 503 | restocking | This gift card is being restocked. Try again in about an hour. | After the Retry-After time |
| 503 | capacity_unavailable | We cannot take this request right now. Try again shortly. | Yes, shortly |
| 503 | fx_unavailable | This currency cannot be converted right now. Try again shortly. | Yes, shortly |
| 503 | maintenance | The service is under maintenance. Try again shortly. | Yes, shortly |
Go live and the fee
Going live happens in the partner portal at partners.plusmore.xyz, one product at a time.
- Sign in with your wallet and confirm your email address.
- Set up an authenticator app.
- Tell us about your company, its directors and its owners.
- Read the plusmore RaaS Terms, tick to accept them for your company and sign the acceptance with your wallet.
- Sanctions checks run on the company, its people, your wallet and your place; you run your own compliance for your customers.
- Pay the go live fee in USDC on Base to the address made for your invoice.
- Once the fee is matched and the checks are clear, the account goes live: create live keys and a webhook, then fund your float.
OpenAPI document
The whole v1 contract as an OpenAPI 3.1 document: every route, request, answer and error code above, for a client generator or an AI agent.
Build your own gift card shop
Run your own gift card shop on the plusmore RaaS API and sell every gift card brand in the live catalogue, at rates averaging about 2%. Start from the build prompt, the open source starter or the live demo: the sandbox, the starter and the demo are free; going live happens in the partner portal and is a one off 999 USDC fee per product, the only required fee (paid plans are optional).
The prompt
Paste it into an AI coding agent. It builds the shop on the sandbox, then proves it with its checks.
The starter
The finished shop, MIT licensed: catalogue, brand pages, a USDC checkout, an admin page.
The live demo
The starter on the live catalogue in DEMO mode, with selling switched off. No key needed at all.
Built for AI agents
An AI coding agent builds the shop from one open source prompt, against the sandbox first, and the prompt ends with acceptance checks, so the agent proves its own work before it calls the shop done.
An API an agent can run
Plain JSON over REST with one signed key that stays on your server, the same contract in the sandbox and live, and answers an agent can act on: it can price, order, retry safely, watch its float and reconcile.
| The agent needs to | What the API gives it |
|---|---|
| Price a gift card before it takes the buyer’s money | POST /v1/quotes books nothing and answers the cost, checked against the balance |
| Order without ever charging twice | client_ref and Idempotency-Key: the same reference always resolves to the same gift card |
| Know what to do when an order cannot go through | Stable codes with a next step: insufficient_balance (fund the float), restocking (retry after the time given) |
| Watch its money and reconcile | GET /v1/balance, GET /v1/deposits and the signed monthly statements |
| Read the catalogue and its prices | GET /v1/catalogue, GET /v1/summary and GET /v1/fx |
A centralised shop your agent keeps running
The starter is a centralised shop. Your server holds the key, buyers pay USDC on Base straight to your wallet, and your server checks each payment on chain before it orders through the API. Your agent can keep working on it from the same repository: the branding, a catalogue refresh, float alerts and order lookups.
Run the starter
Download the starter, or paste the prompt into an AI coding agent. Either way the shop opens in DEMO mode: it browses the live catalogue with selling switched off, and needs no key. Add a sandbox key to sell demo gift cards against the sandbox.
Loading the prompt. If it does not load, use Download instead.
npm install cp .env.example .env.local npm run dev # then open http://localhost:3000
You need Node.js 20 or later. The starter’s README.md walks the three calls (catalogue, quote, order) and its webhook receiver, against the sandbox with PLUSMORE_ENV=sandbox and a sandbox key.
Make it your brand
The starter ships unbranded. Four settings make it yours, and the live demo lists the same steps in a panel for as long as it runs in DEMO mode.
- Name. Set
NEXT_PUBLIC_SHOP_NAMEto your shop’s name. It shows in the header and in every page title. - Logo. Set
NEXT_PUBLIC_SHOP_LOGO_URLto an https image, or put your file inpublic/and set it to its path, such as/logo.svg. Leave it empty and the header shows the name. - Colours. Change
--accent(your brand colour) and--accent-text(the text on it) inapp/globals.css, once in:rootfor light mode and once in the dark mode block. - Domain. Point your own domain at the shop and set
NEXT_PUBLIC_SHOP_DOMAINto it, so the message buyers sign names your shop. - Restart or redeploy. The shop reads these settings from its environment when it serves a page.
Go live
Selling needs live keys from the partner portal: sign in, accept the plusmore RaaS Terms, pay the go live fee and create your keys once the account is live. Going live on the plusmore RaaS API is a one off fee of 999 USDC per product. It is the only required fee and includes the free Solo dev plan; paid plans are optional. Then these settings switch the shop from the sandbox to live mode.
- Live keys from the partner portal, once your account is live
- A wallet on Base that receives your buyers’ payments
- USDC on Base to fund your float
| Set this | What it is |
|---|---|
PLUSMORE_ENV | live, to call the live API; sandbox while you test against the sandbox. |
PLUSMORE_API_KEYPLUSMORE_SIGNING_SECRET | Your live key and its signing secret from the partner portal. Server only, never in a page. |
PLUSMORE_WEBHOOK_SECRET | The secret of your webhook endpoint, to check every event the shop receives. |
SHOP_WALLETNEXT_PUBLIC_SHOP_WALLET | Your wallet on Base that receives buyer payments, the same address in both. |
BASE_RPC_URL | A Base JSON RPC endpoint, used to check each payment on chain. |
ADMIN_PASSWORD | The password for your shop’s own admin page and float statement. |
Going live on the plusmore RaaS API is a one off, non refundable 999 USDC setup and API activation fee per product. It guarantees no uptime, supply, margin or continued service.
Fund the float before your first sale. Float top ups can take up to 3 days to arrive. Float and funding explains deposits, Go live and the fee the portal’s steps, and Errors lists every code your shop can meet.
A DeFi store
plusmore’s own gift card shop settles on Base through a checkout contract and pays cashback. An on chain store like it, for your brand, is available on request: plusmore sets it up with you, it is not self serve.
Q1 2026 design exploration
Everything from here down was designed in Q1 2026, before the plusmore RaaS API above. It is kept for history and is not served; every endpoint on this part of the page is marked Not live.
Rewards as a Service developer docs
Integrate tokenised loyalty rewards into any fintech product. Issue on Base, let users redeem it for gift cards, stake in the USDC pool and settle everything on chain, all through one REST API. This is the design reference from Q1 2026.
Rewards on spend
Partners fund a reward pool and their users earn on qualifying spend, automatically.
Gift card redemption
Redeem for a gift card from gift card brands worldwide across many regions, delivered by email.
USDC pool
Stakers fund the shop and share its real margin. History, not a promise.
Built on Base
Low cost, fast finality, an Ethereum Layer 2. Every movement settles on Base.
Open banking insights
Transaction enrichment and spending insights feed the rewards engine. Design stage.
White label rewards
Embed a branded rewards experience in your app. See the gift card RaaS page.
How RaaS works end to end
funds
spends
or stake
on Base
Authentication
Authorization header. Keys are scoped to your partner account.POST /v2/rewards/issue HTTP/1.1 Authorization: Bearer <your API key> Content-Type: application/json X-Partner-ID: partner_abc123
Base URL and versioning
Every endpoint is versioned; this reference describes v2. Base URLs are issued with partner keys, none is public today.
| Environment | Base URL | Key prefix |
|---|---|---|
| Production | Issued with your partner keys | pm_live_ |
| Sandbox | Issued with your partner keys | pm_test_ |
Sandbox environment
Error handling
Every error returns one JSON envelope with error, code and message fields.
{
"error": true,
"code": "INVALID_WALLET",
"message": "The provided wallet address is not a valid Base address.",
"request_id": "req_8f3a..."
}Rate limits
Requests are rate limited per API key. Past the limit the API answers 429 RATE_LIMITED. The reference table lists the limit per endpoint.
How issuance works
is issued from your partner reward pool. When a user completes a qualifying transaction, your backend calls the issuance endpoint to credit to their wallet. The transfer is confirmed on Base within seconds.
Key concepts
| Concept | Description |
|---|---|
| partner_pool | Your funded reward pool. Issuance debits from this pool. |
| wallet_address | The user’s Base wallet that receives . |
| reward_rate | The conversion rate from dollar spend to (set at partner level). |
| transaction_id | Your unique ID for the qualifying transaction. Used for idempotency. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| wallet_address | string | Required | The user’s Base wallet address (0x...) |
| amount_usd | number | Required | Transaction amount in dollars |
| transaction_id | string | Required | Your unique transaction ID for idempotency |
| merchant_id | string | Optional | Merchant identifier for category based rewards |
| metadata | object | Optional | Arbitrary key value metadata (10 keys at most) |
{
"wallet_address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
"amount_usd": 42.50,
"transaction_id": "txn_abc123",
"merchant_id": "mch_coffeeshop_01",
"metadata": {
"category": "dining",
"channel": "app"
}
}{
"issuance_id": "iss_7f8a9b0c",
"wallet_address": "0x1a2b3c...ef12",
"plus_amount": 8.50,
"amount_usd": 42.50,
"reward_rate": 0.20,
"status": "pending",
"tx_hash": "0xabc123...def",
"created_at": "2026-03-01T12:00:00Z"
}{
"error": true,
"code": "INVALID_WALLET",
"message": "The provided wallet address is not a valid Base address."
}{
"error": true,
"code": "DUPLICATE_TRANSACTION",
"message": "A reward has already been issued for transaction_id txn_abc123.",
"existing_issuance_id": "iss_7f8a9b0c"
}{
"issuances": [
{
"wallet_address": "0x1a2b...ef12",
"amount_usd": 42.50,
"transaction_id": "txn_001"
},
{
"wallet_address": "0x9f8e...cd34",
"amount_usd": 18.00,
"transaction_id": "txn_002"
}
]
}Status values
| Status | Description |
|---|---|
| pending | Transaction submitted to Base, awaiting confirmation. |
| confirmed | delivered to the user’s wallet. |
| failed | Issuance failed. failure_reason carries the detail. |
How redemption works
Users redeem for gift cards from a catalogue of gift card brands worldwide and for partner perks. Redemptions settle on chain and the gift card arrives by email.
Query parameters
| Param | Type | Required | Description |
|---|---|---|---|
| category | string | Optional | Filter by category (gift_card, cashback, partner_perk) |
| brand | string | Optional | Filter by brand name (partial match) |
| min_plus | number | Optional | Minimum cost to include |
| page | integer | Optional | Page number (default 1) |
{
"items": [
{
"brand": "Amazon",
"category": "gift_card",
"plus_cost": 50.00,
"usd_value": 50.00,
"kyc_required": false,
"in_stock": true
}
],
"total": 1,
"page": 1,
"per_page": 25
}Request body
| Field | Type | Required | Description |
|---|---|---|---|
| wallet_address | string | Required | The user’s Base wallet address |
| catalogue_item_id | string | Required | ID of the catalogue item to redeem |
| quantity | integer | Optional | Number of items (default 1) |
Staking overview
This section describes the Q1 design: locked in tiers. The live protocol replaced it with the USDC pool. Stakers fund the shop and share 60 percent of the net margin on every gift card sold, paid from real sales, variable, never promised.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| wallet_address | string | Required | The user’s Base wallet address |
| plus_amount | number | Required | Amount of to stake |
| tier | string | Required | Staking tier: flex, 3m, 6m, 12m |
{
"wallet_address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
"plus_amount": 1000.00,
"tier": "6m"
}{
"stake_id": "stk_4a5b6c7d",
"wallet_address": "0x1a2b3c...ef12",
"plus_amount": 1000.00,
"tier": "6m",
"status": "active",
"matures_at": "2026-09-01T12:00:00Z",
"created_at": "2026-03-01T12:00:00Z"
}User and wallet
Register users, query wallet balances and read transaction histories. Each user is identified by their Base wallet address.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| wallet_address | string | Required | The user’s Base wallet address |
| string | Optional | User email for notifications | |
| external_id | string | Optional | Your internal user ID for mapping |
{
"wallet_address": "0x1a2b3c...ef12",
"total_plus": 2450.75,
"available_plus": 1450.75,
"staked_plus": 1000.00,
"pending_rewards": 12.30,
"lifetime_earned": 5200.00,
"lifetime_redeemed": 2749.25
}Webhooks
Receive real time notifications when events occur in the plusmore system. Register an HTTPS endpoint and the platform POSTs event payloads as they happen.
Events reference
{
"url": "https://example.com/webhooks/plusmore",
"events": [
"reward.issued",
"redemption.completed",
"staking.matured",
"pool.low_balance"
],
"secret": "whsec_your_signing_secret"
}Data objects
Common structures returned across several endpoints. Every timestamp is ISO 8601 UTC. Every monetary amount is a decimal number with at most 2 decimal places, in dollars unless the field says .
Error codes
Rate limits
| Endpoint | Limit |
|---|---|
| /v2/rewards/issue | 1,000 a minute |
| /v2/rewards/issue/batch | 50 a minute |
| /v2/redemption/* | 500 a minute |
| /v2/staking/* | 300 a minute |
| /v2/users/* | 500 a minute |
| All other | 1,000 a minute |
Changelog
| Version | Date | Changes |
|---|---|---|
| Reference | 25 Sep 2026 | Republished on the plusmore site as the design reference. No endpoint is live; the staking section carries the live split instead of the Q1 tiers. |
| v2.1.0 | 13 Mar 2026 | Batch issuance endpoint, webhook test delivery and expanded error codes. |
| v2.0.0 | Q1 2026 | Staking tiers, the redemption catalogue API and the Base mainnet design. |