The plusmore RaaS API

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:

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.

What is in the sandbox

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:

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. 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: up to 10,000 test PLUS a deposit and 50 deposits a key. On chain test funding with test PLUS on Base Sepolia comes next.

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/ping

3. 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/balance

7. 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 carries x-plusmore-env: sandbox and x-request-id.
• Keys. pmr_test_ keys work only on raas-sandbox.plusmore.xyz; a pmr_live_ key there answers 403 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_limited with Retry-After. Per key, for its whole 30 days: 200 test orders, 50 simulated deposits and 50 test events; a spent limit answers 429 limit_exceeded with 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 answers 503 capacity_unavailable until the next UTC day. When the sandbox holds all the keys it can store, key creation answers 503 "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 answers 400 invalid_request.
• Quotes. A quote lives 60 seconds. An order that names an expired quote answers 409 price_changed with a fresh quote in details; order again with that quote_id.
• Statements. GET /v1/statements?month=YYYY-MM answers the month's figures signed with Ed25519; check them against the key at GET /v1/sandbox/statement-key (fetch it once and pin it).
• Not in the sandbox yet: outbound webhook delivery, test PLUS on Base Sepolia and its faucet, the partner portal.
• Production keys come after the go live review: the company checks, the one off access fee and the board's approval.