Pentagon Payment Processor

• Overview
• Payment Rails (Standard & Options)
• What This Is NOT
• Smart Contracts
• Payment Flow
• SKU Configuration
• Authentication
• API Endpoints
• Payment Explorer
• Integration Guide
• Referral & Revenue
• Campaign Rewards & Offers
• Spend Capture for Custom Integrations
• User AI Agent Access (mydata)

Beyond "how to take a payment," this stack exists so that every dollar (or PC) a user spends anywhere in the Pentagon ecosystem lands in one place they can see, query, and prove. Think of it as a block explorer scoped to a single user's spending across all of Pentagon Games: NFT mints, mining fees, NPC credits, Stripe purchases, campaign claims, cross-chain bridges, everything.

That single source of truth powers two distinct audiences, each addressed by its own section below:

• Project / service builders (and their agents) — if you run a contract or service that takes money from users, you need to feed payment events into this stack so the user's spending history is complete. See Spend Capture for Custom Integrations. The NFT mining contract is the canonical example: it has its own fee logic and pools, doesn't use Stripe or the standard payment processor, yet its spend events still need to be captured so the user has one place to track and prove what they paid.
• The user's own AI agent — a Pentagon AI agent acting on behalf of a logged-in user can read that user's full payment history (alongside profile, NFTs, and internal wallet) to answer questions like "I made this spend, what happened?" See User AI Agent Access (mydata).

The long-term goal: monitor all of a user's on-chain contract spending on Pentagon Chain and recognize what each spend was for. Anything we can't recognize is a signal: it's a service that hasn't been wired into the payment stack yet. When that happens, point the owning team (or their session agent) at the Spend Capture section and ask them to describe their payment design pattern so the tracker can incorporate it.

Going forward, the standard way to charge for anything in the Pentagon ecosystem is the multichain Payment Processor (purchaseWithNative / purchaseWithToken). Its defining benefit is multichain: the same SKU can be sold for native PC on Pentagon Chain or USDC / PC-ERC-20 on Ethereum, through one contract and one settlement ledger (cross_chain_purchase_log in pg_payments_db). New products should default to it.

Other rails exist for specific cases — direct P2P pay with earn-back (CardSpendSplitter), in-game action spend (PayHub), fiat (Stripe), and custodial Points spend — and are documented below so every spend lands in the same ledger. But a SKU sale is the processor.

RULE Resolve the canonical wallet from identity — never derive it. Every Points-consuming service MUST resolve the user's AA wallet from Pentagon Identity (user_wallet.address today, PGBalanceAccount post-AA2). Identity wallets are random per-user (keystore under WALLET_PASSWORD, no HD seed), so any independent or deterministic derivation yields a different address and spends the wrong balance. Cautionary example: NFT Mining derived wallets from its own NPC_MASTER_SEED and diverged from users' real Points wallets (now migrating to resolve-not-derive). Payments is aligned — resolve_aa_wallet returns identity's user_wallet.address, so SKU-17 Points credit the canonical wallet.

This is the one piece not yet built, and the reason "pay with Points" is blocked on storefronts today. It lets a logged-in user pay a processor SKU from their PG Points balance without signing: the backend derives the user's AA wallet key and calls purchaseWithNative(skuId) server-side. It is a sibling of the existing /user/npc/spend_ar — same custodial-signing infra, pointed at the processor instead of PayHub. Build it as a Django endpoint on the accounts backend.

Reference implementation: user/airdrop_confirm_view.py in pentagon-login-backend ran this exact sequence for the $CT airdrop (6,786 allocations, zero double-pays, zero nonce collisions). Copy its ordering — the order IS the point.

The KEEPS card packs (tcg.etherfantasy.com) are live SKUs on the processor, sold for native PC:

Added via /admin/payments (register config row → owner signs setPrice on-chain → activate). A buyer purchases at payments.pentagon.games/pay?project=prj_tcg (PG login → "credited to @username" → pay PC). The processor records + settles it (digital_item = no on-chain drop); EtherFantasy delivers the packs off-chain and reports the pack/card allocation back via the delivery endpoint (TO BUILD). Points payment for these packs lights up when spend_purchase ships.

The payment processor handles payments and fulfillment. It does not own or gatekeep NFT metadata, images, or ownership data. Understanding the boundary helps you integrate correctly.

Pentagon Chain (3344)

Ethereum Mainnet (1)

Mode 1: Centralized Fulfillment (default)

The payment processor backend mints the NFT directly using a shared minter wallet. Project grants MINTER_ROLE to the payment processor's moderator address. No project backend needed.

User pays → Scanner captures event → Fulfillment service mints NFT → Done

Requirements:
  1. Deploy your NFT contract with a mintTo(address) or mintNextToken(address) function
  2. Grant minter role to: 0x9A7c1e986e49C2Ace0e85Ccc6eeeb262D46b7521
  3. Register SKU with contract address + mint ABI in cross_chain_payment_config
  4. Set price on PaymentProcessor contract

Used by: Tamago, Vaelion, No5, Muskl, all Chain Heroes, NPC Credits
        

Mode 2: Project-Managed Fulfillment

The payment processor captures the payment event for revenue tracking and referral commissions, but the project's own backend handles delivery. Use this when fulfillment requires game-specific logic (character assignment, inventory, etc.) that the centralized processor can't handle.

User pays → Scanner captures event → Record stored in pg_payments_db
                                      (revenue tracked, referrals calculated)
         → Project's own scanner also picks up event
         → Project backend handles mint/delivery from its own DB

Requirements:
  1. Project runs its own scanner watching the PaymentProcessor contract
  2. Project handles minting/delivery independently
  3. SKU is NOT added to cross_chain_payment_config (prevents centralized fulfillment)
  4. Payment data still flows through pg_payments_db for referral/revenue tracking

Used by: EtherFantasy (SKU 9)
        

Example: EtherFantasy (Project-Managed, SKU 9)

EtherFantasy runs its own Node.js/TypeScript backend with:

• ef-scanner-pc — Watches Pentagon Chain PaymentProcessor for SKU 9 events (every 15s)
• ef-scanner-eth — Watches ETH mainnet PaymentProcessor for SKU 9 events
• processMint() — Assigns next available character, mints to buyer, tracks in local MySQL DB

The centralized scanner also captures SKU 9 events into pg_payments_db for revenue reporting and referral commission calculation. But it does not attempt to fulfill — SKU 9 has no entry in cross_chain_payment_config, so the centralized fulfillment service skips it.

This pattern works for any project with complex delivery logic. The centralized stack handles money, the project handles product.

App Key Header

curl -H "X-PG-App-Key: pk_live_your_key" \
  "https://api.account.pentagon.games/api/v1/payments?sku_id=9&status=completed"
        

HEADS UP Built vs. documented: the /api/v1/payments/* read endpoints below are a design target, not yet built (calling /api/v1/payments/by-buyer/… returns 404 today). What actually exists on api.account.pentagon.games: POST /payment/register, POST /payment/status, /stripe/webhook, /stripe/payment_status, and GET /admin/payments/query (the canonical read, auth via a dedicated PAYMENTS_READ_KEY, not the god key). All read the live pg_payments_db via the PAYMENTS_DB alias. Build new integrations against those; treat /api/v1/* as roadmap until marked LIVE.

Infrastructure Note

Payment API endpoints currently live on api.account.pentagon.games, which is the Pentagon Identity API (login, user profiles, wallets, social auth, VIP). The "account" in the domain name covers both meanings: user accounts (identity) and financial accounting (payments).

This is intentional for now. The payment endpoints (/stripe/webhook, /stripe/payment_status) share the same nginx, SSL, and server infrastructure as the identity API on pg-identity (13.212.154.41). The payment processing workers (on-chain scanner + NFT fulfillment + minter key) run on a separate internal-only server pg-payment-workers (18.143.93.137) with no public HTTP ports.

When payment volume warrants its own domain, the API endpoints will move to api.payment.pentagon.games on a dedicated server. The workers server with the minter key stays isolated either way.

Base URL: https://api.account.pentagon.games (shared with Identity API)

Future Base URL: https://api.payment.pentagon.games (when split)

All /api/v1/payments/* endpoints require a valid X-PG-App-Key header. Same keys as the NFT Data API.

List payments with optional filters. Admin keys return all records. User keys return only payments matching their bound wallet.

Monthly revenue summary grouped by chain, token, and SKU.

{
  "total_revenue_usd": 12450.00,
  "months": [
    {
      "month": "2026-03",
      "payments": 6283,
      "revenue": {
        "pc_pentagon": { "amount": 1570.75, "count": 6275 },
        "usdc_eth": { "amount": 64.00, "count": 8 }
      }
    }
  ],
  "withdrawable": {
    "pentagon": { "pc": 614.925 },
    "ethereum": { "usdc": 183.17, "pc_erc20": 0 }
  }
}
        

Get full detail for a single payment including buyer identity, on-chain proof, and delivery status. The buyer_identity block is resolved from the Pentagon Identity system (admin keys only; user keys see their own identity only).

{
  "payment": {
    "id": 8412,
    "tx_hash": "0x7fa2cf58a278b2df6d74...",
    "chain_id": 3344,
    "block_number": 3350142,
    "buyer": "0xcfb0aee8f7445140d49b...",
    "sku_id": 9,
    "sku_name": "EtherFantasy Character",
    "payment_method": "native",
    "payment_token": "PC",
    "amount": "250000000000000000",
    "amount_usd": 0.25,
    "purchase_status": "confirmed",
    "created_at": "2026-03-30T14:22:11+00:00"
  },
  "buyer_identity": {
    "pg_user_id": 41892,
    "username": "cryptoking",
    "pns_name": "king",
    "email": "king@example.com",
    "wallets": [
      "0xcfb0aee8f7445140d49bf589e30db43fd2ac05e9",
      "0xab12...7890"
    ],
    "social": {
      "discord": { "id": "123456789", "username": "cryptoking#1234" },
      "twitter": { "handle": "@cryptoking" },
      "telegram": { "id": "987654321", "username": "cryptoking" }
    },
    "vip_tier": "VIP2",
    "registered_at": "2025-06-12T08:30:00+00:00",
    "last_login": "2026-05-20T14:15:22+00:00",
    "resolution": "mm_address"
  },
  "delivery": {
    "status": "completed",
    "reward_tx_hash": "0x99d815d2af3e7b82...",
    "reward_chain_id": 3344,
    "token_id": 4201,
    "contract": "0x8F83c6122Dd4d275B53a...",
    "delivered_at": "2026-03-30T14:27:45+00:00"
  },
  "on_chain_proof": {
    "payment_event_found": true,
    "payment_block": 3350142,
    "delivery_verified": true,
    "current_nft_owner": "0xcfb0aee8f7445140d49b..."
  }
}
        

Buyer Identity Resolution

The buyer_identity block triangulates the on-chain wallet address against the Pentagon Identity database to resolve the full user profile. Resolution checks three sources in order:

The resolution field indicates which source matched: mm_address (primary), user_wallet (secondary), or external_wallet. If the wallet is not linked to any PG account, buyer_identity returns null with resolution: "unregistered".

Social Contact Fields (Admin Only)

The social block includes all connected accounts from the Pentagon Identity system. Use these to contact buyers for support:

Social fields are only populated if the user connected that platform to their PG account. Admin keys see all fields. User keys see only their own profile (no other buyers' contact info).

Delivery Status Values

All payments for a specific wallet with delivery status for each, plus the resolved Pentagon user identity. User keys can only query their own bound wallet. Admin keys can query any address.

{
  "buyer": "0xcfb0aee8f7445140d49bf589e30db43fd2ac05e9",
  "buyer_identity": {
    "pg_user_id": 41892,
    "username": "cryptoking",
    "pns_name": "king",
    "email": "king@example.com",
    "social": {
      "discord": { "id": "123456789", "username": "cryptoking#1234" },
      "twitter": { "handle": "@cryptoking" },
      "telegram": { "id": "987654321", "username": "cryptoking" }
    },
    "vip_tier": "VIP2"
  },
  "total": 50,
  "delivered": 44,
  "pending": 0,
  "failed": 6,
  "page": 1,
  "payments": [
    {
      "id": 8412,
      "sku_id": 9,
      "tx_hash": "0x7fa2cf58...",
      "chain_id": 3344,
      "amount_usd": 0.25,
      "delivery_status": "completed",
      "token_id": 4201,
      "created_at": "2026-03-30T14:22:11+00:00"
    }
  ]
}
        

All payments for a specific NFT collection (by contract address). Returns payment + delivery records for every purchase targeting this collection. Admin keys only.

Aggregate payment and delivery statistics. Admin keys only.

{
  "total_payments": 12228,
  "by_status": {
    "completed": 6440,
    "failed": 2571,
    "stuck": 424,
    "pending": 4
  },
  "by_sku": {
    "9": { "total": 12204, "completed": 6440, "failed": 2571, "stuck": 424 },
    "2": { "total": 1, "completed": 1 }
  },
  "on_chain_audit": {
    "last_run": "2026-05-24T23:50:00Z",
    "payments_on_chain": 12228,
    "nfts_minted_on_chain": 6536,
    "deficit": 5682,
    "discrepancies": 12
  }
}
        

Bulk resolve wallet addresses to Pentagon user identities. Admin keys only. Max 200 addresses per request. Used by the Payment Explorer for batch identity resolution.

// Request
POST /api/v1/payments/resolve-buyers
X-PG-App-Key: pk_live_admin_key

{
  "addresses": [
    "0xcfb0aee8f7445140d49bf589e30db43fd2ac05e9",
    "0x5133657725225202a8817b8cab14aa77fd7758ef",
    "0xea3339a9aac6e3c7efecd9e9c9993f3a0163d7be"
  ]
}

// Response
{
  "resolved": 2,
  "unregistered": 1,
  "results": {
    "0xcfb0aee8f7445140d49bf589e30db43fd2ac05e9": {
      "pg_user_id": 41892,
      "username": "cryptoking",
      "pns_name": "king",
      "email": "king@example.com",
      "social": {
        "discord": { "id": "123456789", "username": "cryptoking#1234" },
        "telegram": { "username": "cryptoking" }
      },
      "resolution": "mm_address"
    },
    "0xea3339a9aac6e3c7efecd9e9c9993f3a0163d7be": {
      "pg_user_id": 55210,
      "username": "germax",
      "pns_name": null,
      "email": "germax@proton.me",
      "social": {},
      "resolution": "user_wallet"
    },
    "0x5133657725225202a8817b8cab14aa77fd7758ef": null
  }
}
        

Addresses that don't match any PG account return null. The Explorer uses this to populate identity columns in the admin table and flag unregistered wallets for follow-up.

Subscribe to payment events. Receive callbacks when payments are confirmed.

{
  "url": "https://vip.pentagon.games/api/payment-callback",
  "events": ["payment.confirmed", "payment.completed"],
  "sku_ids": [9, 17]
}
        

Centralized Stripe webhook endpoint. Receives checkout.session.completed events from multiple Stripe accounts.

Endpoint: https://api.account.pentagon.games/stripe/webhook

Supports multiple Stripe accounts (e.g., NPC Collections + BCSH Collections). The backend verifies the webhook signature against each configured secret until one matches. All payments write to pg_payments_db regardless of which Stripe account processed them.

Stripe Checkout Metadata (required)

When creating a Stripe Checkout Session, include these fields in metadata:

Webhook Response

// Success
{"status": true, "message": "payment_completed"}

// Missing metadata
{"status": false, "message": "missing_metadata"}  // 400

// Invalid signature (doesn't match any configured account)
{"status": false, "message": "Invalid signature"}  // 400
        

Adding a New Stripe Account

To onboard a new project's Stripe account to the centralized webhook:

1. Get the project's Stripe webhook secret (whsec_...)
2. Add it to the backend .env as STRIPE_WEBHOOK_SECRET_<PROJECT>
3. Add it to the STRIPE_WEBHOOK_SECRETS list in settings.py
4. Restart pentagon-login-backend
5. Project updates their Stripe dashboard webhook URL to https://api.account.pentagon.games/stripe/webhook

Current Stripe Accounts

Check payment status for a Stripe purchase. Reads from pg_payments_db. Works for any SKU regardless of which Stripe account processed it.

Response

// Found
{
  "success": true,
  "result": {
    "id": 12257,
    "tx_hash": "cs_live_a1ccPzX7...",
    "chain_id": 8888,
    "block_number": 0,
    "buyer": "0x1fdf1637...",
    "sku_id": 3,
    "reward_status": "completed",       // pending | processing | completed | failed
    "payment_method": "stripe",
    "purchase_status": "confirmed",
    "created_at": "2026-05-18T08:04:47.561900+00:00",
    "updated_at": "2026-05-20T03:22:11.291272+00:00",
    "reward_tx_hash": "0x99d815d2...",  // mint transaction hash (null if not yet fulfilled)
    "reward_chain_id": 3344             // chain where NFT was minted
  }
}

// Not found
{"status": false, "message": "Data Not found"}
        

Reward Status Values

URL

https://payments.pentagon.games LIVE

My Payments

Admin Payment Explorer

Current Balances (Withdrawable)

Last updated: 2026-05-02

Key Concept: NPC = PC

NPC PG Points are PC tokens held in the user's AA (Account Abstraction) internal wallet. 1000 NPC = 1 PC. When a user purchases NPC credits via Stripe on pentagon.games/account, they're buying PC into their platform wallet.

CampaignReward.sol

List active campaigns. No auth required. Powers the Offers tab on payments.pentagon.games.

[
  {
    "slug": "npc-1000-pc-bonus-june2026",
    "title": "Earn 1000 NPC Points → Get PC on Ethereum",
    "description": "Purchase 1000 NPC PG Points and receive...",
    "image_url": "https://pentagon.games/assets/campaigns/npc-pc-bonus.png",
    "starts_at": "2026-06-01T00:00:00Z",
    "ends_at": "2026-06-30T23:59:59Z",
    "is_featured": true,
    "rewards": [
      { "label": "1 PC on Pentagon Chain", "chain_id": 3344, "amount": 1.0, "is_bonus": false },
      { "label": "1 PC on Ethereum", "chain_id": 1, "amount": 1.0, "is_bonus": true }
    ],
    "trigger": { "type": "npc_credit", "threshold": 1000 },
    "total_claims": 42
  }
]
        

Check a user's eligibility and reward status for a specific campaign.

{
  "eligible": true,
  "claimed": true,
  "claim": {
    "status": "completed",
    "qualified_at": "2026-06-05T14:30:00Z",
    "rewards": [
      {
        "label": "1 PC on Pentagon Chain",
        "chain_id": 3344,
        "amount": 1.0,
        "status": "success",
        "tx_hash": "0xabc...",
        "explorer_url": "https://explorer.pentagon.games/tx/0xabc..."
      },
      {
        "label": "1 PC on Ethereum",
        "chain_id": 1,
        "amount": 1.0,
        "status": "success",
        "tx_hash": "0xdef...",
        "explorer_url": "https://etherscan.io/tx/0xdef..."
      }
    ]
  }
}
        

Called when a user meets a campaign threshold. Creates a claim entry. Returns 409 if already claimed.

// Request
{
  "campaign_slug": "npc-1000-pc-bonus-june2026",
  "user_id": "user179298482",
  "wallet_address": "0x1234...",
  "proof": { "npc_points": 1000, "stripe_pi": "pi_xxx" }
}

// Success: 201 Created
{ "claim_id": 42, "status": "qualified" }

// Already claimed: 409 Conflict
{ "error": "already_claimed", "claimed_at": "2026-06-05T14:30:00Z" }
        

Why your payment data needs to be provided. Pentagon is building a single per-user spending ledger — effectively a block explorer of a user's spending across the whole ecosystem. If your service collects fees and we don't capture them, the user sees a gap: they paid, but their history doesn't show it, and their agent can't explain it. Every spend that isn't recognized is treated as an unconnected service. Connecting yours closes the gap.

Design-pattern guidance: emit a clean, attributable event

The cheapest way to be trackable is to emit one explicit event per paid action, carrying the payer, the amount actually kept, and a tier/type. Computing on the amount kept (after any refund of excess) keeps the ledger consistent with on-chain reality.

// Recommended: distinct, attributable spend event
event FeePaid(
    address indexed payer,   // (3) user address -> resolves to PG identity
    uint256 amount,          // (4) amount KEPT, in token's smallest unit
    uint8   tier             // (6) e.g. 0 = 24h, 1 = 7-day
);

// Emit AFTER refunding excess, so amount == what the user actually paid:
// uint256 kept = boostFee;
// if (msg.value > kept) payable(msg.sender).transfer(msg.value - kept);
// emit FeePaid(msg.sender, kept, tier);
        

If retrofitting an existing contract isn't possible, you can instead provide a backend feed (a webhook or a list of tx hashes + payer + amount + type) and we'll ingest that. On-chain events are preferred because they're self-proving.

Endpoint: https://vip.pentagon.games/mydata
Scope: one authenticated user's own data only — profile, NFTs, internal (AA) wallet, and payment/spend history. The agent never sees other users' data through this path.

Security boundary: mydata is always scoped to the authenticated user. The agent inherits the user's own visibility — it can see that user's contact fields and full spend history, but never another buyer's. Admin-wide queries (payments:read:all) are a separate, non-user path covered in Section 5.