Verify payments.
The chain determines settlement. Your backend determines whether the payment fulfills the intended purchase.
Payment lifecycle#
| Status | What it means |
|---|---|
| created | An intent exists. No settlement is proven. |
| pending | Settlement is in progress. Wait and verify the same ID. |
| confirmed | The service reports a confirmed payment. Inspect verification provenance. |
| failed | The attempt failed. Diagnose before creating a new purchase. |
Verification provenance#
verifiedVia: 'chain' means the status was derived from chain verification. 'cache' is cached/offline information; 'degraded' means fresh chain verification is unavailable. Do not treat a degraded cached result as a fresh financial receipt.
IAP verification matches the payment’s on-chain event. Round admission checks the exact pool, round key and entrant identity. A transaction hash alone is not proof that the expected payment succeeded.
Grant once on your backend#
Keep sk_ keys server-side. Verify the ID under your studio, match player/SKU/amount and atomically deduplicate fulfillment. Webhooks use the same fulfillment record so a webhook and a manual verification cannot grant twice.
Recover from an interrupted request#
Persist the purchase key before sending. Retry the same purchase with the same key. After you know the payment ID, retry verify(id). A timeout or wallet cancellation is not a confirmed purchase.
Payment inputs#
| Field | Contract |
|---|---|
| amount | Decimal string, positive and at most two decimal places. Public sandbox cap: 1.00 per request. |
| sku / playerId | Required product and opaque player IDs. Match both during fulfillment. |
| gameId | Use game_sandbox_iap with the public sandbox key; your own key resolves studio-owned resources. |
| studio | Optional recipient wallet; otherwise the service uses the key’s configured studio wallet. |
| idempotencyKey | Persist once per purchase; reuse on retry. Omitting it creates a new SDK-generated key per call. |
| metadata | Up to 20 string key/value pairs. No secrets or authorization claims. |
Payment and verification fields#
Payment includes ID, kind, status, amount/fee/net, chain and creation time. txHash is optional until there is a transaction. Entry-only split and roundKey are not part of the narrower VerifyResult. Verification may include identity, chainAmount and integer chainAmountMicro; splitBps is not a typed field on either result.
IAP charges 1% to Playmos. Read the receipt’s exact decimal fee/net; do not derive a ledger from rounded UI cents. Own-pool contests use their immutable series split. The legacy/shared-sandbox entry split is not your studio’s published take.