Jump to documentation section+
API Reference · v1
openapi.yaml

MSGC Partner API.

Integrate game top-ups and digital gift cards over REST JSON settled from your prepaid NGN wallet. Base URL for both live and sandbox keys:

Production & Sandbox Base URLhttps://api.msgc.shop
Supported categoriesCall of Duty: Mobile · Blood Strike · PUBG Mobile · Free Fire · Digital gift cards

Every partner receives an explicit catalog allowlist and NGN wholesale pricing table queried dynamically from GET /v1/products.

Authentication.

Send your secret key in Authorization: Bearer <key> or X-Api-Key over HTTPS. Every key may bind an optional IPv4/IPv6 CIDR allowlist evaluated from socket remote IP.

msgc_test_••••••••sandbox

Available while your partner status is pending_review. Writes only to isolated sandbox tables and never touches your NGN wallet.

msgc_live_••••••••live

Enabled in the partner portal once organization status is active. Requires Owner role.

Sandbox Test IDs.

With a msgc_test_ key, pass these account_id or player_id values to test every order outcome deterministically:

EndpointInput IDSimulated Outcome
POST /v1/orders11111111 / PLAYER_VALIDSimulates completed delivery immediately with receipt metadata.
POST /v1/orders99999999 / PLAYER_INVALIDSimulates definite failure (failed status).
POST /v1/orders77777777 / PENDING_REVIEWSimulates uncertain outcome held as needs_review.
POST /v1/players/verifytest_valid_123HTTP 200 valid: true, ign: "Sandbox Player".
POST /v1/players/verifytest_invalid_404HTTP 200 valid: false (player_not_found).
POST /v1/players/verifytest_down_500HTTP 503 verification_unavailable (simulate temporary outage).

Order Lifecycle.

Orders transition asynchronously through five canonical states. client_reference uniqueness is enforced permanently per partner: resending the identical payload returns HTTP 200 with the existing order; changing payload parameters with an already-used reference returns HTTP 409.

pending

Accepted, idempotency recorded, NGN wallet debited once, queued for delivery.

Processing

Dispatched downstream for fulfillment. Wallet remains debited.

Delivered

Delivered cleanly. Encrypted digital voucher codes (where applicable) are returned via GET /v1/orders/{id} and signed order.completed webhook.

Failed · refunded

Definite failure before or during fulfillment. Full order total is atomically refunded via ORDER_REFUND ledger credit and order.failed webhook fires.

Needs review

Uncertain downstream timeout or gateway ambiguity. Held for operator verification. Never automatically refunded and must never be re-submitted.

Retry & Safety Rules.

Safe timeout recovery

On any HTTP 5xx or network timeout from POST /v1/orders, retry with the exact same Idempotency-Key and exact same JSON body, or look up the transaction via GET /v1/orders?client_reference=....

Never do this
  • Never resubmit or generate a new reference for a needs_review order.
  • Never treat HTTP 503 verification_unavailable as an invalid player ID.
  • Never convert integer kobo amounts into floats before math or storage.

API Endpoints.

Switching language on any example updates every endpoint below.

GET

/v1/products

scope: catalog:read

Returns the SKUs enabled for your partner organization along with integer kobo prices, supported categories, and player verification requirements.

Query parameters: category, cursor, limit.

curl https://api.msgc.shop/v1/products \
  -H "Authorization: Bearer $MSGC_API_KEY"
200 OK
{
  "data": [
    {
      "id": "codm_80_cp",
      "name": "Call of Duty: Mobile 80 CP",
      "category": "Call of Duty: Mobile",
      "unit_price_kobo": 142500,
      "currency": "NGN",
      "requires_player_verification": true,
      "available": true
    }
  ],
  "next_cursor": null
}
POST

/v1/players/verify

scope: players:verify

Checks whether a player account ID is valid for the selected game and region before submitting a chargeable order.

Definitive rejections return HTTP 200 with valid: false. Upstream timeouts return HTTP 503 verification_unavailable so you never falsely tell a customer their ID does not exist.

curl -X POST https://api.msgc.shop/v1/players/verify \
  -H "Authorization: Bearer $MSGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "game": "codm",
    "player_id": "6829104821",
    "region": "NG"
  }'
200 OK
{
  "valid": true,
  "game": "codm",
  "region": "NG",
  "player_id": "6829104821",
  "ign": "Ghost_NG",
  "cached": false
}
POST

/v1/orders

scope: orders:write

Creates a top-up or digital voucher order, atomically debits your prepaid wallet once, and enqueues delivery.

Requires Idempotency-Key (16..64 chars). client_reference is permanently unique per partner.

curl -X POST https://api.msgc.shop/v1/orders \
  -H "Authorization: Bearer $MSGC_API_KEY" \
  -H "Idempotency-Key: inv_20931_attempt_01" \
  -H "Content-Type: application/json" \
  -d '{
    "client_reference": "inv-20931",
    "product_id": "codm_80_cp",
    "account_id": "6829104821",
    "quantity": 1
  }'
202 Accepted
{
  "id": "b2b_ord_01j9k7x2ab12cd34",
  "mode": "live",
  "client_reference": "inv-20931",
  "product_id": "codm_80_cp",
  "account_id": "6829104821",
  "quantity": 1,
  "unit_price_kobo": 142500,
  "total_price_kobo": 142500,
  "status": "pending",
  "created_at": "2026-11-21T13:02:11.000Z"
}
GET

/v1/orders

scope: orders:read

Lists partner orders in reverse chronological order with optional filtering by status or client_reference.

Query parameters: status, client_reference, mode (live|sandbox), limit, cursor.

curl "https://api.msgc.shop/v1/orders?status=needs_review&limit=20" \
  -H "Authorization: Bearer $MSGC_API_KEY"
200 OK
{
  "data": [
    {
      "id": "b2b_ord_01j9k7x2ab12cd34",
      "client_reference": "inv-20931",
      "product_id": "codm_80_cp",
      "total_price_kobo": 142500,
      "status": "needs_review",
      "created_at": "2026-11-21T13:02:11.000Z"
    }
  ],
  "next_cursor": null
}
GET

/v1/orders/{id}

scope: orders:read

Fetches a single order record by ID, including decrypted voucher_codes when a digital gift card order completes.

curl https://api.msgc.shop/v1/orders/b2b_ord_01j9k7x2ab12cd34 \
  -H "Authorization: Bearer $MSGC_API_KEY"
200 OK
{
  "id": "b2b_ord_01j9k7x2ab12cd34",
  "client_reference": "inv-20931",
  "product_id": "gc_amazon_us_25",
  "status": "completed",
  "total_price_kobo": 4125000,
  "voucher_codes": [
    { "code": "AMZN-XXXX-YYYY", "serial": "990184" }
  ],
  "created_at": "2026-11-21T13:02:11.000Z"
}
GET

/v1/wallet

scope: wallet:read

Returns your current prepaid NGN wallet balance, daily net spend limit headroom, and assigned top-up bank transfer details.

curl https://api.msgc.shop/v1/wallet \
  -H "Authorization: Bearer $MSGC_API_KEY"
200 OK
{
  "currency": "NGN",
  "balance_kobo": 124050000,
  "daily_spend_limit_kobo": 250000000,
  "today_net_spend_kobo": 31200000,
  "remaining_daily_limit_kobo": 218800000,
  "deposit_account": {
    "account_number": "0123456789",
    "bank_name": "Partner Settlement Bank",
    "account_name": "MSGC / Acme Digital Ltd"
  }
}
GET

/v1/wallet/transactions

scope: wallet:read

Returns immutable append-only kobo ledger entries (TOPUP, ORDER_DEBIT, ORDER_REFUND, ADJUSTMENT).

curl "https://api.msgc.shop/v1/wallet/transactions?limit=25" \
  -H "Authorization: Bearer $MSGC_API_KEY"
200 OK
{
  "data": [
    {
      "id": "4920",
      "entry_type": "ORDER_DEBIT",
      "amount_kobo": -142500,
      "balance_after_kobo": 124050000,
      "reference": "b2b_ord_01j9k7x2ab12cd34",
      "created_at": "2026-11-21T13:02:11.000Z"
    }
  ],
  "next_cursor": null
}
POST

/v1/webhooks/test

scope: orders:read

Triggers a signed webhook.test delivery to your saved HTTPS webhook URL using the exact same signing path as production order webhooks.

curl -X POST https://api.msgc.shop/v1/webhooks/test \
  -H "Authorization: Bearer $MSGC_API_KEY"
200 OK
{
  "delivery": {
    "id": "9102",
    "event_id": "evt_test_01j9k801",
    "event_type": "webhook.test",
    "status": "delivered",
    "status_code": 200
  }
}

Webhooks & Signatures.

Every webhook HTTP POST is signed with your organization webhook secret using HMAC-SHA256 over the raw unparsed bytes: timestamp + "." + rawBody. Reject timestamps older than 300 seconds (5 minutes) and deduplicate on X-MSGC-Event-Id.

HeaderMeaning
X-MSGC-EventEvent type identifier.
X-MSGC-Event-IdUnique event UUID; persist to deduplicate deliveries.
X-MSGC-TimestampUnix epoch timestamp in seconds when signed.
X-MSGC-SignatureHMAC-SHA256 signature formatted as t=<unix_sec>,v1=<hex_hmac> over ${timestamp}.${rawBody}.
Subscribed events
order.completed · order.failed · order.needs_review · wallet.credited · webhook.test
Retry schedule (5 attempts)
30s → 2m → 10m → 30m → 120m

Outbound webhook egress IPs are provided in your partner onboarding sheet; verify signatures cryptographically even when firewall allowlisting is enabled. Test delivery anytime with POST /v1/webhooks/test.

const crypto = require('crypto');

// Pass raw unparsed Buffer from express.raw({ type: 'application/json' })
function verifyMsgcWebhook(rawBody, signatureHeader, timestampHeader, secret) {
  const ts = Number(timestampHeader);
  const nowSec = Math.floor(Date.now() / 1000);
  if (!Number.isFinite(ts) || Math.abs(nowSec - ts) > 300) {
    throw new Error('Stale or invalid webhook timestamp');
  }

  const parts = Object.fromEntries(
    String(signatureHeader || '').split(',').map((kv) => kv.split('='))
  );
  if (parts.t !== String(timestampHeader) || !parts.v1) {
    throw new Error('Malformed X-MSGC-Signature header');
  }

  const payloadToSign = Buffer.concat([
    Buffer.from(`${timestampHeader}.`, 'utf8'),
    Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8'),
  ]);
  const expectedHex = crypto.createHmac('sha256', secret).update(payloadToSign).digest('hex');

  const sigBuf = Buffer.from(parts.v1, 'utf8');
  const expBuf = Buffer.from(expectedHex, 'utf8');
  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    throw new Error('Invalid webhook HMAC signature');
  }
}

Rate Limits.

Rate limits operate across organization credentials and source IPs. Exceeding limits returns HTTP 429 with Retry-After.

BucketWindow Limit
POST /v1/orders (per API key)40 req / min
Other /v1 endpoints (per API key)120 req / min
Aggregate per source IP180 req / min
Authentication failure throttle10 failures / 60s

Error Reference.

Generated from the server public error registry. Every error response carries error.code, error.message, and error.request_id.

CodeHTTPRetryMeaning
invalid_json400NoRequest body is malformed JSON.
missing_idempotency_key400NoIdempotency-Key header is required on POST /v1/orders.
invalid_idempotency_key400NoIdempotency-Key must be 16..64 characters matching [A-Za-z0-9_.:-] without leading/trailing whitespace.
missing_api_key401NoMissing Authorization: Bearer <key> or X-Api-Key header.
invalid_api_key401NoAPI key format is invalid or credentials could not be verified.
api_key_revoked401NoThis API key has been revoked.
api_key_inactive401NoThis API key is currently inactive.
api_key_expired401NoThis API key has passed its expiration timestamp.
insufficient_wallet_balance402NoAvailable prepaid NGN wallet balance is below total_price_kobo. Fund the wallet and retry.
ip_not_whitelisted403NoCaller IP address is not included in this API key CIDR allowlist.
insufficient_scope403NoThis API key does not have the required scope for the endpoint.
client_suspended403NoPartner organization is suspended or not active for live API requests.
client_not_found403NoPartner organization record could not be located.
product_not_enabled403NoRequested product_id is not enabled on this partner catalog allowlist.
not_found404NoRequested /v1 endpoint does not exist.
order_not_found404NoNo order with the specified id or client_reference exists for this partner and key mode.
wallet_not_found404NoPrepaid wallet record not found for this partner organization.
client_reference_conflict409Noclient_reference was already committed with a different product_id, account_id, zone_id, or quantity.
payload_too_large413NoRequest body exceeds the 16 KB limit.
unsupported_media_type415NoPOST requests must send Content-Type: application/json.
validation_error422NoOne or more request parameters failed schema validation (see details).
idempotency_key_payload_mismatch422NoIdempotency-Key was already used for a different HTTP method, route, or request body.
idempotency_in_recovery422YesAn earlier attempt with this Idempotency-Key left an incomplete idempotency state; retry shortly or inspect the order by client_reference.
idempotency_key_already_used422NoIdempotency-Key was already consumed by a committed order.
product_not_b2b_eligible422NoRequested product_id is not available for automated API ordering.
invalid_recipient422Noaccount_id or zone_id does not satisfy recipient rules for the selected product.
order_exceeds_max_value422NoCalculated total_price_kobo exceeds the organization per-order limit.
missing_player_id422Noplayer_id is required when calling POST /v1/players/verify.
invalid_cursor422NoPagination cursor is malformed or tampered.
webhook_not_configured422NoNo webhook_url is configured for this partner organization.
invalid_webhook_url422NoConfigured webhook_url failed HTTPS or SSRF destination validation.
invalid_kobo_amount422NoMonetary amount failed integer-kobo validation.
kobo_overflow422NoCalculated monetary amount exceeded safe integer kobo bounds.
rate_limit_exceeded429YesAPI key or caller IP exceeded its token-bucket request quota. Honor the Retry-After header.
auth_throttled429YesToo many failed authentication attempts from this IP/key prefix within 60 seconds. Honor Retry-After.
daily_spend_limit_exceeded429NoOrder would exceed the partner organization net daily spend limit (resets at 00:00 WAT).
product_unavailable503YesRequested product is temporarily unavailable for API ordering. Honor the Retry-After header (300s).
provider_unavailable503YesUpstream fulfillment capacity is temporarily unavailable. Safe to retry with backoff.
catalog_unavailable503YesProduct metadata service is temporarily unavailable and no cached entry exists.
verification_unavailable503YesPlayer verification upstream service or circuit breaker is temporarily unavailable.
system_maintenance503YesB2B order creation is temporarily paused for scheduled maintenance.
codm_routing_disabled503YesAutomated delivery for this Call of Duty: Mobile SKU is temporarily paused.
b2b_unavailable503YesB2B runtime is unconfigured or failing readiness checks on this instance.
server_draining503YesInstance is shutting down and not accepting new orders. Safe to retry with the same Idempotency-Key.
service_unavailable503YesService is temporarily unavailable.
db_timeout503YesDatabase statement timed out. Safe to retry idempotently.
db_tx_timeout503YesDatabase transaction timed out. Safe to retry idempotently.
db_lock_timeout503YesWallet lock contention timeout. Safe to retry idempotently after a short delay.
db_busy503YesDatabase connection pool or transient serialization retry busy.
db_unavailable503YesDatabase connection was interrupted or unavailable.
internal_error500NoAn unexpected internal error occurred. Contact partner support with request_id.
Showing 51 of 51 documented response codes.

Go-Live Checklist & Key Rotation.

  1. Exercise PLAYER_VALID, PLAYER_INVALID, and PENDING_REVIEW in sandbox.
  2. Verify webhook HMAC signatures over raw request bytes with a 300-second timestamp tolerance and X-MSGC-Event-Id deduplication.
  3. Configure per-key IP CIDR allowlists once organization status switches to active.
  4. Zero-downtime key rotation: create or rotate your msgc_live_ key in Developers, deploy it across your servers, verify traffic shifts, then revoke older keys.

Changelog.

2026-11-21 · v1.0Initial partner release

Mounted all 8 v1 API routes, code-generated OpenAPI 3.1 schema, AES-GCM encrypted voucher delivery, mandatory authenticator MFA on partner portal logins, and real-path POST /v1/webhooks/test.