{ "openapi": "3.1.0", "info": { "title": "Bit Mario Sandbox Checkout API", "version": "0.1.0", "description": "Isolated, durable payment-link integration simulator. No real funds, invoices, card charges, provider enrollment or asset settlement. This specification documents two backend checkout operations plus three outgoing webhook receiver contracts. Webhooks are POSTed to your separately configured staging receiver, not to additional paths on the sandbox API; they use raw-body HMAC rather than API Bearer authentication. Sandbox dashboard/control routes are documented separately in README.md and do not implement the production merchant-session API. Payout sandbox routes and events are not implemented. The server URL is proposed until an isolated deployment and DNS/TLS are provisioned; use the exact URL supplied by your sandbox operator. Keep test API keys on the integrator backend and use a separate test ledger and webhook receiver." }, "servers": [ { "url": "https://sandbox.pay.bit-mario.com", "description": "Proposed sandbox origin; not proof of public deployment. Replace with the operator-provided sandbox origin." } ], "security": [ { "GameCredential": [] } ], "paths": { "/checkout-api/v1/payment-links": { "post": { "summary": "Generate a simulated payment link with the sandbox plan", "operationId": "createGamePaymentLink", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Identical retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CreatedPaymentLink" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "201": { "description": "New link", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CreatedPaymentLink" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Invalid or inactive credential/session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Scope or browser-origin denial", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Order, credential or deployment unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Idempotency conflict or sandbox resource capacity reached", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "500": { "description": "Unexpected sandbox service failure", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Sandbox SQLite storage capacity reached (SANDBOX_CAPACITY). Contact the sandbox operator; preserve the order ID and idempotency key when retrying.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "description": "Sandbox-only server-to-server operation. Rejects live bm_live credentials and requests carrying an Origin header. JSON requests are limited to 8 KB. Generated links open a simulated checkout and cannot charge real funds. Normalized request fields and response shapes follow the pinned production checkout contract; provider operations, hierarchy readiness, and real settlement are not performed." } }, "/checkout-api/v1/payment-links/{orderId}": { "get": { "summary": "Read payment state for this credential and game order", "operationId": "getGamePaymentLink", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$" } } ], "responses": { "200": { "description": "Recorded payment state", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PaymentLink" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Invalid or inactive credential/session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Scope or browser-origin denial", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Order, credential or deployment unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Idempotency conflict or sandbox resource capacity reached", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "500": { "description": "Unexpected sandbox service failure", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Sandbox SQLite storage capacity reached (SANDBOX_CAPACITY). Contact the sandbox operator; preserve the order ID and idempotency key when retrying.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "description": "Sandbox-only server-to-server operation. Rejects live bm_live credentials and requests carrying an Origin header. JSON requests are limited to 8 KB. Generated links open a simulated checkout and cannot charge real funds. Normalized request fields and response shapes follow the pinned production checkout contract; provider operations, hierarchy readiness, and real settlement are not performed." } } }, "webhooks": { "endpointVerification": { "post": { "operationId": "receiveEndpointVerification", "tags": [ "Outbound webhook receiver" ], "summary": "Sandbox: Prove possession of the endpoint signing secret", "description": "Sandbox endpoint possession proof. Verify the original raw-body HMAC, timestamp, credentialId, body.id and endpointId. Return 2xx with exactly {\"challengeResponse\":\"<64 lowercase hex characters>\"}, computed using the CURRENT decoded secret over UTF-8(\"verify.\" + the UNDECODED challenge). A generic 200/204 or extra JSON keys fail. No API Bearer token is sent or required. This event never fulfills an order.", "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical body.id. Stable across retries/replays. Payment eventID differs from management deliveryID." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{10,12}$" }, "description": "Unix seconds generated for this attempt. Recommended receiver tolerance±300seconds, independent of event.createdAt; synchronize clocks." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^v1,[A-Za-z0-9+/]{43}=(?: v1,[A-Za-z0-9+/]{43}=)?$" }, "description": "One signature, or current then previous signature separated by one SPACE while rotation overlap is active. HMAC-SHA256 digest is STANDARD base64, prefixed v1,; see x-signature-protocol." }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Bit-mario-Checkout-Webhooks/1" }, "description": "Informational; never authenticate by User-Agent alone." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationEvent" }, "examples": { "sandboxSynthetic": { "summary": "Synthetic sandbox event — no real payment", "description": "Fixed illustrative IDs and timestamp for documentation only. This is not an authentic signed request, a live delivery or evidence of funds received. The sandbox sends its own generated IDs and attempt signatures.", "value": { "id": "00000000-0000-4000-8000-000000000001", "version": 1, "createdAt": "2026-01-01T12:00:00.000Z", "credentialId": "00000000-0000-4000-8000-000000000002", "type": "webhook.verification", "endpointId": "00000000-0000-4000-8000-000000000003", "challenge": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } } } } }, "responses": { "2XX": { "description": "Requires a correct strict proof JSONbody as well as2xx. HTTP success alone fails. Content-Type application/json is recommended; sender parses response body as JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationProof" } } } }, "default": { "description": "Non2xx, connection/TLS/DNS/timeout/bodylimit failure causes bounded retry; redirects are not followed." } } } }, "endpointTest": { "post": { "operationId": "receiveEndpointTest", "tags": [ "Outbound webhook receiver" ], "summary": "Sandbox: Harmless delivery test", "description": "Sandbox delivery test. Verify the raw-body signature and configured credential/endpoint identity, then return 2xx. No challengeResponse is required. Inspect the sandbox delivery history for success. This event never fulfills an order.", "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical body.id. Stable across retries/replays. Payment eventID differs from management deliveryID." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{10,12}$" }, "description": "Unix seconds generated for this attempt. Recommended receiver tolerance±300seconds, independent of event.createdAt; synchronize clocks." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^v1,[A-Za-z0-9+/]{43}=(?: v1,[A-Za-z0-9+/]{43}=)?$" }, "description": "One signature, or current then previous signature separated by one SPACE while rotation overlap is active. HMAC-SHA256 digest is STANDARD base64, prefixed v1,; see x-signature-protocol." }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Bit-mario-Checkout-Webhooks/1" }, "description": "Informational; never authenticate by User-Agent alone." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEvent" }, "examples": { "sandboxSynthetic": { "summary": "Synthetic sandbox event — no real payment", "description": "Fixed illustrative IDs and timestamp for documentation only. This is not an authentic signed request, a live delivery or evidence of funds received. The sandbox sends its own generated IDs and attempt signatures.", "value": { "id": "00000000-0000-4000-8000-000000000001", "version": 1, "createdAt": "2026-01-01T12:00:00.000Z", "credentialId": "00000000-0000-4000-8000-000000000002", "type": "webhook.test", "endpointId": "00000000-0000-4000-8000-000000000003", "data": { "test": true } } } } } } }, "responses": { "2XX": { "description": "Receiver accepted the verified event; response body is ignored for this event." }, "default": { "description": "Non2xx, connection/TLS/DNS/timeout/bodylimit failure causes bounded retry; redirects are not followed." } } } }, "paymentCompleted": { "post": { "operationId": "receivePaymentCompleted", "tags": [ "Outbound webhook receiver" ], "summary": "Sandbox: An API checkout order became paid", "description": "A sandbox API order was marked paid by an explicit simulation. This is not a real financial event. Verify original bytes and identities, durably deduplicate before 2xx, and update only your test ledger through the same idempotent operation used for status polling. Match the expected deployment, credential, paymentRequestId, orderId, planId/version, amount, USD currency and method. distributionStatus is a snapshot; reconcile later simulated settlement through GET status. Duplicate and out-of-order delivery are possible. No API Bearer token or receiver-supplied Retry-After contract is used.", "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical body.id. Stable across retries/replays. Payment eventID differs from management deliveryID." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{10,12}$" }, "description": "Unix seconds generated for this attempt. Recommended receiver tolerance±300seconds, independent of event.createdAt; synchronize clocks." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^v1,[A-Za-z0-9+/]{43}=(?: v1,[A-Za-z0-9+/]{43}=)?$" }, "description": "One signature, or current then previous signature separated by one SPACE while rotation overlap is active. HMAC-SHA256 digest is STANDARD base64, prefixed v1,; see x-signature-protocol." }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Bit-mario-Checkout-Webhooks/1" }, "description": "Informational; never authenticate by User-Agent alone." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCompletedEvent" }, "examples": { "sandboxSynthetic": { "summary": "Synthetic sandbox event — no real payment", "description": "Fixed illustrative IDs and timestamp for documentation only. This is not an authentic signed request, a live delivery or evidence of funds received. The sandbox sends its own generated IDs and attempt signatures.", "value": { "id": "00000000-0000-4000-8000-000000000001", "version": 1, "createdAt": "2026-01-01T12:00:00.000Z", "credentialId": "00000000-0000-4000-8000-000000000002", "type": "payment.completed", "deploymentId": "00000000-0000-4000-8000-000000000004", "data": { "paymentRequestId": "00000000-0000-4000-8000-000000000005", "orderId": "sandbox-order-000001", "planId": "00000000-0000-4000-8000-000000000006", "planVersion": 1, "amount": "25.00", "currency": "USD", "paymentMethod": "cashapp", "status": "paid", "paid": true, "paidAt": "2026-01-01T12:00:00.000Z", "distributionStatus": "pending" } } } } } } }, "responses": { "2XX": { "description": "Receiver accepted the verified event; response body is ignored for this event." }, "default": { "description": "Non2xx, connection/TLS/DNS/timeout/bodylimit failure causes bounded retry; redirects are not followed." } } } } }, "components": { "schemas": { "CreatePaymentLink": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$" }, "externalUserId": { "type": "string", "minLength": 1, "maxLength": 128 }, "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,5})(?:\\.[0-9]{1,2})?$", "description": "Positive USD decimal, at most 100000.00. Simulated only; real provider constraints are not evaluated." }, "currency": { "type": "string", "enum": [ "USD" ], "default": "USD" }, "expiresInSeconds": { "type": "integer", "minimum": 300, "maximum": 604800, "default": 86400 }, "paymentMethod": { "type": "string", "enum": [ "base_usdc", "cashapp", "stripe" ], "description": "Required for plan keys. Older fixed-method keys may omit it or repeat their fixed method. Retries must retain the same method." } }, "required": [ "orderId", "externalUserId", "amount" ], "additionalProperties": false }, "CreatedPaymentLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$" }, "checkoutUrl": { "type": "string", "format": "uri" }, "planId": { "type": "string", "format": "uuid" }, "planVersion": { "type": "integer", "minimum": 1 }, "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,5})(?:\\.[0-9]{1,2})?$", "description": "Positive USD decimal, at most 100000.00. Simulated only; real provider constraints are not evaluated." }, "currency": { "type": "string", "enum": [ "USD" ] }, "paymentMethod": { "type": "string", "enum": [ "base_usdc", "cashapp", "stripe" ] }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "distributionStatus": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "replayed": { "type": "boolean" } }, "required": [ "id", "orderId", "checkoutUrl", "planId", "planVersion", "amount", "currency", "paymentMethod", "status", "paid", "distributionStatus", "expiresAt", "paidAt", "replayed" ], "additionalProperties": false }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$" }, "checkoutUrl": { "type": "string", "format": "uri" }, "planId": { "type": "string", "format": "uuid" }, "planVersion": { "type": "integer", "minimum": 1 }, "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,5})(?:\\.[0-9]{1,2})?$", "description": "Positive USD decimal, at most 100000.00. Simulated only; real provider constraints are not evaluated." }, "currency": { "type": "string", "enum": [ "USD" ] }, "paymentMethod": { "type": "string", "enum": [ "base_usdc", "cashapp", "stripe" ] }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "distributionStatus": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "orderId", "checkoutUrl", "planId", "planVersion", "amount", "currency", "paymentMethod", "status", "paid", "distributionStatus", "expiresAt", "paidAt" ], "additionalProperties": false }, "VerificationEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "webhook.verification" }, "version": { "type": "integer", "const": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "credentialId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Opaque base64url-looking text. For proof HMAC, append this STRING to verify.; do not decode the challenge." } }, "required": [ "id", "type", "version", "createdAt", "credentialId", "endpointId", "challenge" ], "additionalProperties": false }, "VerificationProof": { "type": "object", "properties": { "challengeResponse": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Lowercase HEX HMAC-SHA256 using the CURRENT decoded webhook secret over UTF-8(\"verify.\" + challenge). Exactly this one JSON property; extra properties, uppercase hex, base64, echoing challenge, or wrapping in data/success fail verification." } }, "required": [ "challengeResponse" ], "additionalProperties": false }, "TestEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "webhook.test" }, "version": { "type": "integer", "const": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "credentialId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "data": { "type": "object", "properties": { "test": { "type": "boolean", "const": true } }, "required": [ "test" ], "additionalProperties": false } }, "required": [ "id", "type", "version", "createdAt", "credentialId", "endpointId", "data" ], "additionalProperties": false }, "PaymentCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "payment.completed" }, "version": { "type": "integer", "const": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "credentialId": { "type": "string", "format": "uuid" }, "deploymentId": { "type": "string", "format": "uuid" }, "data": { "type": "object", "properties": { "paymentRequestId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$" }, "planId": { "type": "string", "format": "uuid" }, "planVersion": { "type": "integer", "minimum": 1 }, "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)\\.[0-9]{2}$" }, "currency": { "type": "string", "const": "USD" }, "paymentMethod": { "type": "string", "description": "Persisted payment method; currently supported checkout API methods are base_usdc, cashapp and stripe. Do not infer recipient settlement completion from the method.", "x-known-values": [ "base_usdc", "cashapp", "stripe" ] }, "status": { "type": "string", "const": "paid" }, "paid": { "type": "boolean", "const": true }, "paidAt": { "type": "string", "format": "date-time" }, "distributionStatus": { "type": "string", "description": "Snapshot of existing recipient distribution state; paid does not mean distribution is finished. Treat unfamiliar states as requiring status reconciliation." } }, "required": [ "paymentRequestId", "orderId", "planId", "planVersion", "amount", "currency", "paymentMethod", "status", "paid", "paidAt", "distributionStatus" ], "additionalProperties": false } }, "required": [ "id", "type", "version", "createdAt", "credentialId", "deploymentId", "data" ], "additionalProperties": false, "description": "Emitted only when an enrolled sandbox API order is marked paid by simulation. createdAt equals paidAt. This carries no evidence of real funds or recipient settlement. No buyer email, wallet, player identity or checkout capability URL is sent. Match the immutable test order and fulfill the test ledger once." } }, "securitySchemes": { "GameCredential": { "type": "http", "scheme": "bearer", "bearerFormat": "bm_test__", "description": "Sandbox-only backend API key; never a production key, setup invitation code, session cookie or webhook signing secret." } } }, "x-contract-source": { "path": "docs/bit-mario-checkout/openapi.json", "sha256": "37f0c4e4f0d7fd2ff460a7c27d3269a86726217350b3b471968a77a69c5d4c8a" }, "x-webhook-contract-source": { "path": "docs/bit-mario-checkout/webhooks.openapi.json", "sha256": "f478b98d62eee281604e54759caef75887fa86c078f3e3c85f11c823a122e37d" }, "x-signature-protocol": { "name": "Standard Webhooks v1 HMAC-SHA256", "secret": "whsec_ followed by standard base64 of 32 random bytes. Remove the prefix and base64-decode exactly once. Do not use the literal encoded secret as the HMAC key.", "signedBytes": "UTF-8(webhook-id + \".\" + webhook-timestamp + \".\") concatenated with the ORIGINAL raw HTTP request body bytes. Do not normalize, pretty-print, reserialize JSON or add a newline.", "requestDigestEncoding": "Standard base64, not hex or base64url. Each header token is v1,. Compare decoded 32-byte MAC values in constant time. During overlap, current and previous tokens are separated by a space; at least one valid signature authenticates the request.", "timestamp": "Recommended receiver tolerance: +/-300 seconds relative to its clock. The timestamp is authenticated as part of the MAC. A fresh Unix-seconds timestamp is generated per attempt; an old event.createdAt can still be valid on replay. This tolerance is receiver policy, not a sender-enforced rule.", "afterAuthentication": "Check body.id equals webhook-id, version=1, configured credentialId and the relevant endpoint, order and deployment identities. Never fulfill an arbitrary unknown order.", "verificationProofBytes": "UTF-8(\"verify.\" + challengeString), using the CURRENT decoded webhook secret. Do not decode the challenge string.", "verificationProofEncoding": "Lowercase hexadecimal, exactly 64 characters.", "verificationResponse": "HTTP 2xx with exactly {\"challengeResponse\":\"\"}. No extra properties or wrapper. Generic HTTP 200, an echo, HTML or HTTP 204 fail. The sender checks proof against the CURRENT secret only.", "rawBodyAdvice": "Register receiver raw-body middleware before global JSON parsing. The example adapter limit of 16 KiB is defensive receiver policy, not an advertised maximum event size. Keep secrets and raw payloads out of logs." }, "x-sandbox-scope": { "simulatedMethods": [ "cashapp", "base_usdc", "stripe" ], "events": [ "webhook.verification", "webhook.test", "payment.completed" ], "notImplemented": [ "Payout API", "real payment-provider calls", "production merchant authentication and hierarchy", "real recipient settlement", "live referral enrollment" ], "controlDocumentation": "README.md" } }