# AUTO-GENERATED FROM CODE — DO NOT HAND-EDIT
# Run: node backend/scripts/b2b-generate-openapi.js
openapi: 3.1.0
info:
  title: MSGC Shop Partner B2B API
  version: 1.0.0
  description: "Invite-only prepaid NGN Partner API for automated digital top-ups and gift cards across Call of Duty: Mobile, Blood Strike, PUBG Mobile, Free Fire, and digital gift cards.\n\nEach partner's enabled catalog and integer-kobo prices are returned dynamically by `GET /v1/products`.\n\nRate Limits:\n- `POST /v1/orders`: 40 requests/minute per API key\n- All other `/v1` routes: 120 requests/minute per API key (client overrides possible)\n- Global per-IP ceiling: 180 requests/minute per IP\n- Failed authentication throttle: locks for 60s after 10 failed attempts (`429 auth_throttled`)\n\nWebhook Signing & Retries:\n- Headers: `X-MSGC-Event`, `X-MSGC-Event-Id`, `X-MSGC-Timestamp`, `X-MSGC-Signature`\n- Signature scheme: `X-MSGC-Signature: t=<unix_sec>,v1=<hex_hmac>` where HMAC-SHA256 is computed over `${timestamp}.${rawBody}` (5-minute tolerance)\n- Retry schedule: [30, 120, 600, 1800, 7200] seconds across up to 5 attempts\n\nPublic Error Codes:\n- `invalid_json` (HTTP 400): Request body is malformed JSON.\n- `missing_idempotency_key` (HTTP 400): Idempotency-Key header is required on POST /v1/orders.\n- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 16..64 characters matching [A-Za-z0-9_.:-] without leading/trailing whitespace.\n- `missing_api_key` (HTTP 401): Missing Authorization: Bearer <key> or X-Api-Key header.\n- `invalid_api_key` (HTTP 401): API key format is invalid or credentials could not be verified.\n- `api_key_revoked` (HTTP 401): This API key has been revoked.\n- `api_key_inactive` (HTTP 401): This API key is currently inactive.\n- `api_key_expired` (HTTP 401): This API key has passed its expiration timestamp.\n- `insufficient_wallet_balance` (HTTP 402): Available prepaid NGN wallet balance is below total_price_kobo. Fund the wallet and retry.\n- `ip_not_whitelisted` (HTTP 403): Caller IP address is not included in this API key CIDR allowlist.\n- `insufficient_scope` (HTTP 403): This API key does not have the required scope for the endpoint.\n- `client_suspended` (HTTP 403): Partner organization is suspended or not active for live API requests.\n- `client_not_found` (HTTP 403): Partner organization record could not be located.\n- `product_not_enabled` (HTTP 403): Requested product_id is not enabled on this partner catalog allowlist.\n- `not_found` (HTTP 404): Requested /v1 endpoint does not exist.\n- `order_not_found` (HTTP 404): No order with the specified id or client_reference exists for this partner and key mode.\n- `wallet_not_found` (HTTP 404): Prepaid wallet record not found for this partner organization.\n- `client_reference_conflict` (HTTP 409): client_reference was already committed with a different product_id, account_id, zone_id, or quantity.\n- `payload_too_large` (HTTP 413): Request body exceeds the 16 KB limit.\n- `unsupported_media_type` (HTTP 415): POST requests must send Content-Type: application/json.\n- `validation_error` (HTTP 422): One or more request parameters failed schema validation (see details).\n- `idempotency_key_payload_mismatch` (HTTP 422): Idempotency-Key was already used for a different HTTP method, route, or request body.\n- `idempotency_in_recovery` (HTTP 422, retryable): An earlier attempt with this Idempotency-Key left an incomplete idempotency state; retry shortly or inspect the order by client_reference.\n- `idempotency_key_already_used` (HTTP 422): Idempotency-Key was already consumed by a committed order.\n- `product_not_b2b_eligible` (HTTP 422): Requested product_id is not available for automated API ordering.\n- `invalid_recipient` (HTTP 422): account_id or zone_id does not satisfy recipient rules for the selected product.\n- `order_exceeds_max_value` (HTTP 422): Calculated total_price_kobo exceeds the organization per-order limit.\n- `missing_player_id` (HTTP 422): player_id is required when calling POST /v1/players/verify.\n- `invalid_cursor` (HTTP 422): Pagination cursor is malformed or tampered.\n- `webhook_not_configured` (HTTP 422): No webhook_url is configured for this partner organization.\n- `invalid_webhook_url` (HTTP 422): Configured webhook_url failed HTTPS or SSRF destination validation.\n- `invalid_kobo_amount` (HTTP 422): Monetary amount failed integer-kobo validation.\n- `kobo_overflow` (HTTP 422): Calculated monetary amount exceeded safe integer kobo bounds.\n- `rate_limit_exceeded` (HTTP 429, retryable): API key or caller IP exceeded its token-bucket request quota. Honor the Retry-After header.\n- `auth_throttled` (HTTP 429, retryable): Too many failed authentication attempts from this IP/key prefix within 60 seconds. Honor Retry-After.\n- `daily_spend_limit_exceeded` (HTTP 429): Order would exceed the partner organization net daily spend limit (resets at 00:00 WAT).\n- `product_unavailable` (HTTP 503, retryable): Requested product is temporarily unavailable for API ordering. Honor the Retry-After header (300s).\n- `provider_unavailable` (HTTP 503, retryable): Upstream fulfillment capacity is temporarily unavailable. Safe to retry with backoff.\n- `catalog_unavailable` (HTTP 503, retryable): Product metadata service is temporarily unavailable and no cached entry exists.\n- `verification_unavailable` (HTTP 503, retryable): Player verification upstream service or circuit breaker is temporarily unavailable.\n- `system_maintenance` (HTTP 503, retryable): B2B order creation is temporarily paused for scheduled maintenance.\n- `codm_routing_disabled` (HTTP 503, retryable): Automated delivery for this Call of Duty: Mobile SKU is temporarily paused.\n- `b2b_unavailable` (HTTP 503, retryable): B2B runtime is unconfigured or failing readiness checks on this instance.\n- `server_draining` (HTTP 503, retryable): Instance is shutting down and not accepting new orders. Safe to retry with the same Idempotency-Key.\n- `service_unavailable` (HTTP 503, retryable): Service is temporarily unavailable.\n- `db_timeout` (HTTP 503, retryable): Database statement timed out. Safe to retry idempotently.\n- `db_tx_timeout` (HTTP 503, retryable): Database transaction timed out. Safe to retry idempotently.\n- `db_lock_timeout` (HTTP 503, retryable): Wallet lock contention timeout. Safe to retry idempotently after a short delay.\n- `db_busy` (HTTP 503, retryable): Database connection pool or transient serialization retry busy.\n- `db_unavailable` (HTTP 503, retryable): Database connection was interrupted or unavailable.\n- `internal_error` (HTTP 500): An unexpected internal error occurred. Contact partner support with request_id."
servers:
  - url: "https://api.msgc.shop"
    description: Production API Gateway
security:
  - BearerAuth: []
  - ApiKeyHeader: []
paths:
  "/v1/products":
    get:
      operationId: listProducts
      summary: List enabled products and fixed NGN kobo pricing
      description: "Returns this partner organization's enabled product catalog and contracted prices in integer kobo across Call of Duty: Mobile, Blood Strike, PUBG Mobile, Free Fire, and digital gift cards."
      tags: [Catalog]
      x-required-scope: "products:read"
      responses:
        200:
          description: Enabled partner catalog items with integer kobo pricing.
          content:
            "application/json":
              schema:
                type: object
                required: [data, count]
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Product"
                  count:
                    type: integer
                    minimum: 0
        401:
          description: "Missing, malformed, revoked, inactive, or expired API key."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_api_key
                  message: Invalid API key.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        403:
          description: "Source IP not in CIDR allowlist, missing scope, or inactive partner organization."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: ip_not_whitelisted
                  message: Request source IP is not permitted by this API key IP allowlist.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        429:
          description: Rate limit or auth-failure throttle exceeded. Honor Retry-After header.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: rate_limit_exceeded
                  message: API key rate limit exceeded.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
        503:
          description: Product or upstream service temporarily unavailable. Safe to retry after backoff.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: product_unavailable
                  message: This product is temporarily unavailable. Please try again later.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Suggested retry delay in seconds.
  "/v1/wallet":
    get:
      operationId: getWallet
      summary: "Get prepaid NGN wallet balance, limits, and deposit account"
      description: "Returns integer-kobo prepaid wallet balance, today net spend (reset at 00:00 WAT), remaining daily headroom, and the dedicated bank transfer deposit account."
      tags: [Wallet]
      x-required-scope: "wallet:read"
      responses:
        200:
          description: Current wallet summary and deposit account.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/WalletSummary"
        401:
          description: "Missing, malformed, revoked, inactive, or expired API key."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_api_key
                  message: Invalid API key.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        403:
          description: "Source IP not in CIDR allowlist, missing scope, or inactive partner organization."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: ip_not_whitelisted
                  message: Request source IP is not permitted by this API key IP allowlist.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        404:
          description: Wallet record not found for partner organization.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: wallet_not_found
                  message: B2B wallet not found for client.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        429:
          description: Rate limit or auth-failure throttle exceeded. Honor Retry-After header.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: rate_limit_exceeded
                  message: API key rate limit exceeded.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
        503:
          description: Product or upstream service temporarily unavailable. Safe to retry after backoff.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: product_unavailable
                  message: This product is temporarily unavailable. Please try again later.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Suggested retry delay in seconds.
  "/v1/wallet/transactions":
    get:
      operationId: listWalletTransactions
      summary: List append-only wallet ledger entries
      description: Cursor-paginated ledger entries in reverse chronological order. All amounts are signed integers in kobo.
      tags: [Wallet]
      x-required-scope: "wallet:read"
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
          description: Opaque cursor from previous pagination.next_cursor.
      responses:
        200:
          description: Paginated ledger transactions.
          content:
            "application/json":
              schema:
                type: object
                required: [data, pagination]
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/LedgerEntry"
                  pagination:
                    "$ref": "#/components/schemas/CursorPagination"
        401:
          description: "Missing, malformed, revoked, inactive, or expired API key."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_api_key
                  message: Invalid API key.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        403:
          description: "Source IP not in CIDR allowlist, missing scope, or inactive partner organization."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: ip_not_whitelisted
                  message: Request source IP is not permitted by this API key IP allowlist.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        422:
          description: Malformed pagination cursor or query limit.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_cursor
                  message: Pagination cursor is invalid.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        429:
          description: Rate limit or auth-failure throttle exceeded. Honor Retry-After header.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: rate_limit_exceeded
                  message: API key rate limit exceeded.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
        503:
          description: Product or upstream service temporarily unavailable. Safe to retry after backoff.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: product_unavailable
                  message: This product is temporarily unavailable. Please try again later.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Suggested retry delay in seconds.
  "/v1/players/verify":
    post:
      operationId: verifyPlayer
      summary: Verify a player account ID prior to ordering
      description: "Validates player account existence and region before order submission. Returns HTTP 200 with valid: false on definitive invalid/mismatch IDs, and HTTP 503 verification_unavailable when upstream verification is unreachable (never reports invalid on upstream outages)."
      tags: [Verification]
      x-required-scope: "players:verify"
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/VerifyPlayerRequest"
      responses:
        200:
          description: Player account verification outcome.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/VerifyPlayerResponse"
        401:
          description: "Missing, malformed, revoked, inactive, or expired API key."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_api_key
                  message: Invalid API key.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        403:
          description: "Source IP not in CIDR allowlist, missing scope, or inactive partner organization."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: ip_not_whitelisted
                  message: Request source IP is not permitted by this API key IP allowlist.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        413:
          description: Request body exceeds 16 KB.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: payload_too_large
                  message: Request body exceeds maximum size limit (16kb).
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        415:
          description: Content-Type must be application/json.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: unsupported_media_type
                  message: Content-Type must be application/json.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        422:
          description: Missing or invalid player_id.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: missing_player_id
                  message: player_id is required.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        429:
          description: Rate limit or auth-failure throttle exceeded. Honor Retry-After header.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: rate_limit_exceeded
                  message: API key rate limit exceeded.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
        503:
          description: Product or upstream service temporarily unavailable. Safe to retry after backoff.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: product_unavailable
                  message: This product is temporarily unavailable. Please try again later.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Suggested retry delay in seconds.
  "/v1/orders":
    post:
      operationId: createOrder
      summary: Create a top-up or digital gift card order (idempotent)
      description: "Atomically debits the prepaid wallet in integer kobo and queues fulfillment. Rate-limited at 40/min per API key.\n\nIdempotency & client_reference behavior:\n- Same Idempotency-Key (16..64 chars, 72h TTL) + same payload returns 202 with Idempotent-Replayed: true.\n- Same Idempotency-Key + different payload returns 422 idempotency_key_payload_mismatch.\n- New/expired Idempotency-Key + same client_reference + same tuple returns 200 with the existing order.\n- Same client_reference + different product_id, account_id, zone_id, or quantity returns 409 client_reference_conflict."
      tags: [Orders]
      x-required-scope: "orders:create"
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 16
            maxLength: 64
            pattern: "^[A-Za-z0-9_.:-]{16,64}$"
          description: Unique caller-generated key protecting retries against double debit (16..64 chars).
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/CreateOrderRequest"
      responses:
        200:
          description: Existing order returned for an identical permanent client_reference tuple.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Order"
        202:
          description: "Order accepted and queued (or replayed via matching Idempotency-Key with Idempotent-Replayed: true header)."
          headers:
            Idempotent-Replayed:
              schema:
                type: string
                enum: ["true"]
              description: Present when returning a stored 72-hour idempotency snapshot.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Order"
        400:
          description: Missing/malformed Idempotency-Key header or invalid JSON.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: missing_idempotency_key
                  message: Idempotency-Key header is required.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        401:
          description: "Missing, malformed, revoked, inactive, or expired API key."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_api_key
                  message: Invalid API key.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        402:
          description: Prepaid NGN wallet balance insufficient.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: insufficient_wallet_balance
                  message: Insufficient prepaid wallet balance to fulfill this order.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        403:
          description: "Source IP not in CIDR allowlist, missing scope, or inactive partner organization."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: ip_not_whitelisted
                  message: Request source IP is not permitted by this API key IP allowlist.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        409:
          description: "client_reference was previously used with a different product_id, account_id, zone_id, or quantity."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: client_reference_conflict
                  message: client_reference was already used for a different order payload.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        413:
          description: Request body exceeds 16 KB.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: payload_too_large
                  message: Request body exceeds maximum size limit (16kb).
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        415:
          description: Content-Type must be application/json.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: unsupported_media_type
                  message: Content-Type must be application/json.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        422:
          description: "Schema error, Idempotency-Key payload mismatch, invalid recipient, or max order value exceeded."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: idempotency_key_payload_mismatch
                  message: Idempotency-Key was already used with a different request payload.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        429:
          description: Rate limit or auth-failure throttle exceeded. Honor Retry-After header.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: rate_limit_exceeded
                  message: API key rate limit exceeded.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
        503:
          description: Product or upstream service temporarily unavailable. Safe to retry after backoff.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: product_unavailable
                  message: This product is temporarily unavailable. Please try again later.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Suggested retry delay in seconds.
    get:
      operationId: listOrLookupOrders
      summary: List orders or look up an order by client_reference
      description: "When `client_reference` query param is present, returns a single Order object (or 404). Otherwise returns cursor-paginated orders scoped to the API key mode (live or sandbox)."
      tags: [Orders]
      x-required-scope: "orders:read"
      parameters:
        - name: client_reference
          in: query
          schema:
            type: string
            maxLength: 150
          description: Exact permanent client_reference lookup (returns single Order).
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, processing, completed, failed, needs_review]
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        200:
          description: Single Order (if client_reference supplied) or paginated Order list.
          content:
            "application/json":
              schema:
                oneOf:
                  - "$ref": "#/components/schemas/Order"
                  - type: object
                    required: [data, pagination]
                    properties:
                      data:
                        type: array
                        items:
                          "$ref": "#/components/schemas/Order"
                      pagination:
                        "$ref": "#/components/schemas/CursorPagination"
        401:
          description: "Missing, malformed, revoked, inactive, or expired API key."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_api_key
                  message: Invalid API key.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        403:
          description: "Source IP not in CIDR allowlist, missing scope, or inactive partner organization."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: ip_not_whitelisted
                  message: Request source IP is not permitted by this API key IP allowlist.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        404:
          description: Order not found for client_reference.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: order_not_found
                  message: Order not found for client_reference.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        422:
          description: Invalid status filter or pagination cursor.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: validation_error
                  message: Invalid filter parameter.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        429:
          description: Rate limit or auth-failure throttle exceeded. Honor Retry-After header.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: rate_limit_exceeded
                  message: API key rate limit exceeded.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
        503:
          description: Product or upstream service temporarily unavailable. Safe to retry after backoff.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: product_unavailable
                  message: This product is temporarily unavailable. Please try again later.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Suggested retry delay in seconds.
  "/v1/orders/{id}":
    get:
      operationId: getOrderById
      summary: Retrieve an order by MSGC order ID
      tags: [Orders]
      x-required-scope: "orders:read"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            maxLength: 36
      responses:
        200:
          description: Order status and fulfillment details.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Order"
        401:
          description: "Missing, malformed, revoked, inactive, or expired API key."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_api_key
                  message: Invalid API key.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        403:
          description: "Source IP not in CIDR allowlist, missing scope, or inactive partner organization."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: ip_not_whitelisted
                  message: Request source IP is not permitted by this API key IP allowlist.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        404:
          description: Order not found for this partner and key mode.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: order_not_found
                  message: Order not found.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        429:
          description: Rate limit or auth-failure throttle exceeded. Honor Retry-After header.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: rate_limit_exceeded
                  message: API key rate limit exceeded.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
        503:
          description: Product or upstream service temporarily unavailable. Safe to retry after backoff.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: product_unavailable
                  message: This product is temporarily unavailable. Please try again later.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Suggested retry delay in seconds.
  "/v1/webhooks/test":
    post:
      operationId: sendTestWebhook
      summary: Dispatch a signed webhook.test event to your configured webhook URL
      description: "Enqueues and immediately delivers a signed `webhook.test` payload using your active `webhook_url` and encrypted signing secret so you can verify signature validation end-to-end."
      tags: [Webhooks]
      x-required-scope: "orders:read"
      responses:
        200:
          description: Attempted webhook delivery record.
          content:
            "application/json":
              schema:
                type: object
                required: [delivery]
                properties:
                  delivery:
                    "$ref": "#/components/schemas/WebhookDeliveryResult"
        401:
          description: "Missing, malformed, revoked, inactive, or expired API key."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: invalid_api_key
                  message: Invalid API key.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        403:
          description: "Source IP not in CIDR allowlist, missing scope, or inactive partner organization."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: ip_not_whitelisted
                  message: Request source IP is not permitted by this API key IP allowlist.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        415:
          description: "If sending a body, Content-Type must be application/json."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: unsupported_media_type
                  message: Content-Type must be application/json.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        422:
          description: No webhook_url configured for this organization.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: webhook_not_configured
                  message: Configure a webhook_url before sending a test event.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
        429:
          description: Rate limit or auth-failure throttle exceeded. Honor Retry-After header.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: rate_limit_exceeded
                  message: API key rate limit exceeded.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
        503:
          description: Product or upstream service temporarily unavailable. Safe to retry after backoff.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorEnvelope"
              example:
                error:
                  code: product_unavailable
                  message: This product is temporarily unavailable. Please try again later.
                  request_id: b2b_req_7f3c8e91a2b4c5d6
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Suggested retry delay in seconds.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "API key passed as `Authorization: Bearer msgc_live_...` or `msgc_test_...`"
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: "Alternative header carrying the `msgc_live_...` or `msgc_test_...` API key"
  schemas:
    PublicErrorCode:
      type: string
      enum:
        - invalid_json
        - missing_idempotency_key
        - invalid_idempotency_key
        - missing_api_key
        - invalid_api_key
        - api_key_revoked
        - api_key_inactive
        - api_key_expired
        - insufficient_wallet_balance
        - ip_not_whitelisted
        - insufficient_scope
        - client_suspended
        - client_not_found
        - product_not_enabled
        - not_found
        - order_not_found
        - wallet_not_found
        - client_reference_conflict
        - payload_too_large
        - unsupported_media_type
        - validation_error
        - idempotency_key_payload_mismatch
        - idempotency_in_recovery
        - idempotency_key_already_used
        - product_not_b2b_eligible
        - invalid_recipient
        - order_exceeds_max_value
        - missing_player_id
        - invalid_cursor
        - webhook_not_configured
        - invalid_webhook_url
        - invalid_kobo_amount
        - kobo_overflow
        - rate_limit_exceeded
        - auth_throttled
        - daily_spend_limit_exceeded
        - product_unavailable
        - provider_unavailable
        - catalog_unavailable
        - verification_unavailable
        - system_maintenance
        - codm_routing_disabled
        - b2b_unavailable
        - server_draining
        - service_unavailable
        - db_timeout
        - db_tx_timeout
        - db_lock_timeout
        - db_busy
        - db_unavailable
        - internal_error
    ErrorEnvelope:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, request_id]
          properties:
            code:
              "$ref": "#/components/schemas/PublicErrorCode"
            message:
              type: string
            request_id:
              type: string
            details:
              type: object
              additionalProperties: true
    Product:
      type: object
      required:
        - product_id
        - name
        - category
        - unit_price_kobo
        - currency
        - requires_input
        - requires_zone
        - input_label
      properties:
        product_id:
          type: string
        name:
          type: string
        category:
          type: [string, "null"]
        unit_price_kobo:
          type: integer
          minimum: 1
        currency:
          type: string
          enum: [NGN]
        requires_input:
          type: boolean
        requires_zone:
          type: boolean
        input_label:
          type: [string, "null"]
    DepositAccount:
      type: [object, "null"]
      required: [account_number, bank_name, account_name]
      properties:
        account_number:
          type: string
        bank_name:
          type: string
        account_name:
          type: string
    WalletSummary:
      type: object
      required:
        - currency
        - balance_kobo
        - daily_spend_limit_kobo
        - today_net_spend_kobo
        - remaining_daily_limit_kobo
        - max_order_value_kobo
        - low_balance_alert_kobo
        - status
        - deposit_account
        - updated_at
      properties:
        currency:
          type: string
          enum: [NGN]
        balance_kobo:
          type: integer
          minimum: 0
        daily_spend_limit_kobo:
          type: integer
          minimum: 0
        today_net_spend_kobo:
          type: integer
          minimum: 0
        remaining_daily_limit_kobo:
          type: integer
          minimum: 0
        max_order_value_kobo:
          type: integer
          minimum: 0
        low_balance_alert_kobo:
          type: integer
          minimum: 0
        status:
          type: string
          enum: [pending_review, active, suspended, deactivated]
        deposit_account:
          "$ref": "#/components/schemas/DepositAccount"
        updated_at:
          type: [string, "null"]
          format: date-time
    LedgerEntry:
      type: object
      required:
        - id
        - entry_type
        - amount_kobo
        - balance_before_kobo
        - balance_after_kobo
        - ref_type
        - ref_id
        - description
        - created_at
      properties:
        id:
          type: string
        entry_type:
          type: string
          enum: [TOPUP_CREDIT, ORDER_DEBIT, ORDER_REFUND, MANUAL_ADJUSTMENT]
        amount_kobo:
          type: integer
        balance_before_kobo:
          type: integer
          minimum: 0
        balance_after_kobo:
          type: integer
          minimum: 0
        ref_type:
          type: string
        ref_id:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
    CursorPagination:
      type: object
      required: [limit, has_more, next_cursor]
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 100
        has_more:
          type: boolean
        next_cursor:
          type: [string, "null"]
    CreateOrderRequest:
      type: object
      additionalProperties: false
      required: [client_reference, product_id]
      properties:
        client_reference:
          type: string
          minLength: 1
          maxLength: 150
          pattern: "^[A-Za-z0-9._:@/-]{1,150}$"
        product_id:
          type: string
          minLength: 1
          maxLength: 100
        account_id:
          type: string
          maxLength: 100
        zone_id:
          type: string
          maxLength: 50
        quantity:
          type: integer
          minimum: 1
          maximum: 50
          default: 1
    VoucherCode:
      type: object
      properties:
        code:
          type: [string, "null"]
        pin:
          type: [string, "null"]
        serial:
          type: [string, "null"]
      additionalProperties: true
    Order:
      type: object
      required:
        - id
        - mode
        - client_reference
        - product_id
        - product_name
        - unit_price_kobo
        - quantity
        - total_price_kobo
        - currency
        - account_id
        - zone_id
        - status
        - failure_reason
        - fulfillment_ref
        - voucher_codes
        - created_at
        - updated_at
      properties:
        id:
          type: string
        mode:
          type: string
          enum: [live, sandbox]
        client_reference:
          type: string
        product_id:
          type: string
        product_name:
          type: string
        unit_price_kobo:
          type: integer
          minimum: 1
        quantity:
          type: integer
          minimum: 1
          maximum: 50
        total_price_kobo:
          type: integer
          minimum: 1
        currency:
          type: string
          enum: [NGN]
        account_id:
          type: string
        zone_id:
          type: [string, "null"]
        status:
          type: string
          enum: [pending, processing, completed, failed, needs_review]
        failure_reason:
          type: [string, "null"]
        fulfillment_ref:
          type: [string, "null"]
        voucher_codes:
          type: [array, "null"]
          items:
            "$ref": "#/components/schemas/VoucherCode"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    VerifyPlayerRequest:
      type: object
      required: [player_id]
      properties:
        game:
          type: string
          default: codm
          description: "Game identifier (e.g. `codm`, `codm_ng`, `codm_in`, `pubg`, `free_fire`)."
        player_id:
          type: string
        region:
          type: string
          description: "Optional country/region code such as `NG`, `IN`, or `US`."
        zone_id:
          type: string
    VerifyPlayerResponse:
      type: object
      required: [valid, player_id, game]
      properties:
        valid:
          type: boolean
        player_id:
          type: string
        player_name:
          type: string
        game:
          type: string
        region:
          type: string
        cached:
          type: boolean
        error_reason:
          type: string
          enum: [player_not_found, player_region_mismatch]
    WebhookDeliveryResult:
      type: object
      required: [id, event_id, event_type, destination_url, status]
      properties:
        id:
          type: string
        event_id:
          type: string
          format: uuid
        event_type:
          type: string
        destination_url:
          type: string
          format: uri
        status:
          type: string
          enum: [pending, delivered, failed]
        status_code:
          type: [integer, "null"]
        error_message:
          type: [string, "null"]
        created_at:
          type: [string, "null"]
          format: date-time
        delivered_at:
          type: [string, "null"]
          format: date-time
    WebhookEnvelope:
      type: object
      required: [id, type, created_at, data]
      properties:
        id:
          type: string
          format: uuid
          description: Unique event UUID matching X-MSGC-Event-Id for deduplication.
        type:
          type: string
          enum:
            - order.completed
            - order.failed
            - order.needs_review
            - wallet.credited
            - webhook.test
        created_at:
          type: string
          format: date-time
        data:
          type: object
          additionalProperties: true
