Gift card Aggregator API reference

#Introduction

The BSV Business Aggregator API lets bulk and business buyers procure digital gift cards across 2,000+ brands through a single integration — instead of wiring dozens of vendor APIs.

Two paths share the same catalogue and balance:

• API — automate catalogue sync, orders, and inventory from your platform or ops stack
• Customer portal — dashboard buying, funding, and API key / IP whitelist management

Orders use best-price routing across connected vendors, with automatic retry when a selected vendor fails.

#Quick start

Follow these steps to validate your integration in sandbox before switching to production keys.

1. Request access and complete business onboarding.
2. Create sandbox API keys and set an IP whitelist in the portal.
3. Top up your prepaid USD balance (sandbox uses test credits).
4. List products, place a test order, then poll order / inventory status.
5. Switch to production keys when validation is complete.

curl -X POST https://sandbox.api.business.bsvmarket.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-001" \
  -d '{
  "product_id": "steam-wallet-50-usd",
  "quantity": 100,
  "currency": "USD",
  "route": "best_price",
  "client_reference": "po-77821"
}'

#Authentication

All requests require HTTPS. Authenticated endpoints use a bearer token issued per account:

Authorization: Bearer <api_key>

Create, rotate, and revoke keys in the customer portal. Restrict production traffic with the portal IP whitelist.

#Conventions

#Versioning

Public endpoints use URI versioning under /v1/.... Breaking changes ship under a new major version with a migration window.

#Required headers

#Money & IDs

Amounts are decimal strings or numbers in USD unless otherwise noted. Product and order IDs are opaque strings. Timestamps are ISO-8601 UTC.

#Order lifecycle

From catalogue discovery to delivered redeem codes — five stages your integration should handle.

#Catalogue

Retrieve products available to your commercial terms — including brand, denomination, region, images, and redeem guidance where supplied.

GET /v1/products?brand=steam&region=US&limit=50
Authorization: Bearer YOUR_API_KEY

#Orders

Create bulk orders and poll status. Use route: "best_price" for automatic vendor selection.

{
  "product_id": "steam-wallet-50-usd",
  "quantity": 100,
  "currency": "USD",
  "route": "best_price",
  "client_reference": "po-77821"
}

#Inventory

List purchased stock, filter by order or date, and retrieve redeem payloads for fulfilled units. Inventory history supports ops and finance reconciliation.

#Balance

Read available prepaid USD balance and recent ledger activity. Top-ups are completed in the portal via crypto or bank transfer — the API does not initiate bank wires.

#Errors & idempotency

Errors return JSON with a machine-readable code, human message, and optional request_id. Retry safe GETs; for POSTs reuse the same Idempotency-Key to avoid duplicate orders.

#Sandbox

Sandbox mirrors production behaviour for catalogue, orders, and inventory with test credits. Use sandbox keys only against the sandbox host.

#All endpoints

Exact field schemas and additional filters are provided with your integration pack after access approval.