hyperspend

Developers

Distributor API

Sell Hyperspend vouchers on your platform: issue a voucher when your customer pays, and hand them the PIN instantly.

Sell Hyperspend vouchers on your platform. When your customer pays you, your server asks Hyperspend for a voucher and receives its PIN instantly, which you show or send to your customer. Each voucher is paid from your prepaid balance with Hyperspend, at your agreed discount.

  • Base URL: https://hyperspend.io/api/v1/distributor
  • Format: JSON request and response bodies, UTF-8
  • Authentication: Authorization: Bearer <your API key>

API keys and sandbox

Key Starts with What it does
Test hd_test_ Issues sandbox vouchers: nothing is charged, nothing is stored, and the PINs (starting 4999) can't be spent anywhere.
Live hd_live_ Issues real vouchers, paid from your balance. Issued once your integration is approved.

Keep keys on your server only. If a key may have leaked, tell us and we'll revoke it immediately.

Your balance

Hyperspend vouchers are prepaid. You top up your balance by bank transfer; we record it, and each voucher you issue deducts its cost (face value minus your discount). For example, with a 3% discount, a EUR 25.00 voucher costs you EUR 24.25. If your agreement includes a credit limit, your balance may go below zero down to that limit.

When there isn't enough balance, issuing fails with 402 insufficient_balance. Nothing is charged and no voucher is created.

1. Issue a voucher

Call this when your customer has paid you. The Idempotency-Key header is required: use a value that's unique per voucher you sell, such as your order line id.

POST /api/v1/distributor/vouchers
Authorization: Bearer hd_test_xxx
Content-Type: application/json
Idempotency-Key: order-58213-line-1

{ "amount": "25.00", "currency": "EUR", "reference": "order-58213" }

201 Created:

{
  "id": "3f0c1b8e-2a4d-4c7e-9f61-0d2e8b7a5c31",
  "pin": "4821 0937 5512 6640",
  "amount": "25.00",
  "currency": "EUR",
  "cost": "24.25",
  "status": "active",
  "reference": "order-58213",
  "expires_at": "2027-04-20T09:30:00.000Z",
  "created_at": "2026-10-20T09:30:00.000Z",
  "test": false
}
  • amount: whole amounts from 10 to 5000 (e.g. "25", "25.00" or 25).
  • currency: optional; your account's currency (EUR).
  • reference (optional): your own order id, up to 100 characters.
  • Show the customer the PIN, amount and expiry date (vouchers are valid for 6 months). Also tell them where to spend it: https://hyperspend.io/check-merchant.
  • Store the id: you need it to look up or cancel the voucher.

Retries are safe

If the request times out or you get a 500, retry with the same Idempotency-Key. You'll get the same voucher and the same PIN back (200 OK), and you're never charged twice. Never reuse a key for a different voucher: the same key with a different amount returns 409 idempotency_conflict.

2. Look up a voucher

GET /api/v1/distributor/vouchers/{id}
Authorization: Bearer hd_live_xxx

Returns the same object as above, with the current status: active, redeemed, expired, blocked or refunded. Use it for customer support, e.g. a customer who lost their PIN.

3. Cancel a voucher

POST /api/v1/distributor/vouchers/{id}/cancel
Authorization: Bearer hd_live_xxx

Cancels an unused voucher within 24 hours of issue, for example when your customer's payment is reversed. The PIN stops working immediately and the cost is credited back to your balance. The response is the voucher with "status": "refunded". Calling it again is harmless.

After 24 hours, or once the voucher has been redeemed, cancelling isn't possible through the API. Contact us.

4. Check your balance

GET /api/v1/distributor/balance
Authorization: Bearer hd_live_xxx

{ "balance": "4825.50", "credit_limit": "0.00", "available": "4825.50", "currency": "EUR", "discount_percent": "3.00", "test": false }

Errors

{ "error": { "code": "insufficient_balance", "message": "Your balance is too low for this voucher. Top up your account with Hyperspend." } }
HTTP code Meaning
400 idempotency_key_required Send an Idempotency-Key header
400 invalid_amount Not a whole amount from 10 to 5000
400 unsupported_currency Not your account's currency
401 unauthorized Missing, invalid or revoked key, or your account isn't live yet (live keys)
402 insufficient_balance Top up your balance
404 voucher_not_found No voucher with this id from your account (sandbox vouchers can't be looked up or cancelled)
409 idempotency_conflict Key already used for a different amount
409 cancel_window_passed More than 24 hours since issue
409 voucher_not_cancellable Already redeemed, blocked or expired
429 rate_limited More than 120 requests per minute
500 server_error Our side. Retry with the same Idempotency-Key.

Your responsibilities

As set out in the distribution agreement:

  • Only sell to customers aged 18 or over, and apply your own fraud and identity checks.
  • Show customers the safety message: Hyperspend never asks for a PIN by phone, email or message, and anyone asking them to buy a voucher and send the PIN is a scammer.
  • Describe Hyperspend as a voucher for the Hyperspend partner network, never as usable anywhere or as cash.

Example (curl)

curl -X POST https://hyperspend.io/api/v1/distributor/vouchers \
  -H "Authorization: Bearer hd_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-58213-line-1" \
  -d '{"amount":"25.00","currency":"EUR","reference":"order-58213"}'

Going live

  1. Integrate with your test key, including retries and error handling.
  2. Run a test together with the Hyperspend team.
  3. We set your account live, record your first top-up, and issue your live key.

Questions: support@bigedirect.com