Vendors & Integrations

Octopus talks to the outside world through vendor adapters under services/external_vendors/. There are three outbound product lines — voucher, direct-topup, eSIM — each with its own interface, factory, and adapters. Plus two inbound sales channels (Shopify, G2A) where Octopus is the server, and a payouts family.

The two vendor concepts

"Grasshopper" is not separate from topup vendors — it's simply one voucher vendor (code='GH'). The real axis is product line + vendor.code.

The vendors table (database/models/vendor.go) carries:

• code *string — the routing key every factory switches on.
• vendor_type: VOUCHER | DIRECT_TOPUP | BOTH | ESIM.
• Orchestration flags: is_async, has_webhook, has_reference_id_support, pre_fetch_enabled, has_api, is_bulk, is_active, max_quantity, p_limit, currency_code, balance.

Adapter inventory

Each factory switches on vendor.code. Codes are types.VendorCode constants in services/external_vendors/types/common.go.

Shared infra: vendorhttp/ (common HTTP client + config), octopuscommon/ (self-loop guard.go + login-token token_manager.go for the OCTO family), webhooks/ (Svix + HMAC verifiers), types/failure_codes.go (normalized failure taxonomy). payouts/ (Ledig, Merit) is a separate outbound-money family, not product vendors.

Order orchestration

Three paths, one shape: create → (poll / webhook) → complete, with state on the order/recharge/esim_order row's sub_status.

Vouchers — two sub-flows

Prefetch (async vendors, pre_fetch_enabled) — the platform pre-orders voucher stock ahead of demand and caches it. Driven by a formal state machine in jobs/prefetch_state_machine.go:

validTransitions is the authoritative graph. Retries use exponential backoff (2^n min, capped at 16); isRetryableError matches VENDOR_TIMEOUT/RATE_LIMIT strings. Terminal stage PUMPING pushes inventory to Valkey.

Live orders (not pre-stocked) — jobs/pending_order_retry_job.go → handler.ProcessOrderRetry(...) creates order items, assigns inventory, calls the vendor, updates delivery. Vendor calls go through services/external_vendors/manager.go (VendorManager), which resolves and caches the adapter.

State lives on order_items.status + order_items.sub_status. There's a recreate protocol: types.ErrShouldReCreate / FormattedOrderResponse.ShouldReCreate — when a vendor loses record of an order (terminal/404), the orchestrator clears vendor_order_id and re-CREATEs on the next retry while the Octopus order stays PENDING.

Topups

services/topup_order.go CreateTopupOrder: pick best vendor variant → debit client wallet (or burn a redeemed voucher via redeem_resource_id) → create recharge atomically → call the vendor. Completion polled by jobs/topup_order_retry_job.go (batch 50, max 10 retries).

eSIM

services/esim_order.go (~1220 lines). Completion driven by jobs/esim_order_retry_job.go (poll), jobs/esim_installation_poll_job.go (activation), jobs/esim_expiry_job.go.

Inbound webhooks

services/vendor_webhook_service.go ProcessWebhook(vendorID, req) routes by resource_type (order/recharge/payment). Each adapter normalises its native payload to types.NormalizedWebhookPayload. Signatures verified via webhooks/ (Svix or HMAC). Events persisted (idempotency via IdempotencyKey).

Inbound sales channels

These run the opposite direction — external systems buy from Octopus. Not in external_vendors/.

Shopify — services/shopify/

Octopus is a client polling Shopify. ClientFactory builds one Shopify GraphQL client per tenant using per-client creds on the clients table (ShopifyShopName, encrypted ShopifyAccessToken, ShopifyAPIVersion, ShopifyEnabled/SyncEnabled). Cron jobs pull and fulfil orders (fetch-shopify-orders, process-pending-shopify-orders, detect-shopify-cancellations), fulfilling through the internal voucher pipeline. There's a locked upgrade plan to Shopify API 2026-04 — see the Memory Appendix.

G2A — http/handler/g2a*.go

Octopus is the HTTP server and OAuth2 token issuer; the G2A marketplace calls in. GET /g2a/oauth/token issues bearer tokens (client_credentials; creds in g2a_credentials). Flow: reserve → order → pull codes. Reservations hold no codes — Octopus Cards (GH) are minted on confirm, not drawn from a finite pool; the g2a-reservation-expiry cron expires stale holds (30m TTL). Product mapping via g2a_product_mapping. See the Memory Appendix.

OCTO federation (self-vendor)

Octopus can consume another Octopus instance's public /api/v1 as if it were a third-party supplier, across all three lines: OCTO (vouchers → /api/v1/orders), OCTO_TOPUP (/api/v1/topups), OCTO_ESIM (/api/v1/esim). Auth is a login flow (not a static key): POST /auth/login → short-lived tokens, managed by octopuscommon/token_manager.go. octopuscommon.SelfLoopGuard errors if a federated vendor's host resolves to this instance's own base URL, preventing an order recursing into itself. Full contract gotchas (bare-array lists, write-only client_reference, composite productID:variantID VendorVariantID, eSIM webhook omitting activation_code) are in the Memory Appendix.

Catalog sync & balances

• Catalog sync — services/vendor_catalog_service.go; vendors stream products via GetCatalogBatched. Crons: vendor-catalog-sync (daily 2 AM), vendor-catalog-cleanup (Sun 3 AM), vendor-catalog-retry (every min).
• Balance sync — vendor-balance-sync (every 15 min) pulls GetBalance into vendors.balance / vendor_wallet.
• Inventory pump — inventory-pump (every 6h) or go run main.go pump-inventory pushes stored voucher inventory into Valkey.