{"components":{"schemas":{"ErrorEnvelope":{"properties":{"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"ok":{"const":false,"type":"boolean"}},"required":["ok","error"],"type":"object"}},"securitySchemes":{"gatewayKey":{"description":"The Gateway API key returned by POST /api/merchants/register.","in":"header","name":"x-gateway-key","type":"apiKey"}}},"externalDocs":{"description":"Integration docs","url":"https://sandbox.gate.solknife.xyz/docs"},"info":{"description":"Merchant API for SolKnife Gateway: Solana payment intents, subscription plans, customer subscriptions, and signed callbacks. Every response is a JSON envelope: { ok: true, data } on success, { ok: false, error: { code, message } } on failure.","title":"SolKnife Gateway API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/merchants/register":{"post":{"description":"Creates a business account and returns the Gateway API key and webhook secret. Both are shown only once. Limited to 5 registrations per hour per client IP.","operationId":"post /api/merchants/register","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"apiKey":{"type":"string","description":"Gateway API key. Shown once; send it as x-gateway-key."},"merchant":{"type":"object","properties":{"callbackUrl":{"type":"string"},"createdAt":{"type":"string"},"displayName":{"type":"string"},"id":{"type":"string"},"ownerWallet":{"type":"string"},"telegramChatId":{"type":"string"}},"required":["callbackUrl","createdAt","displayName","id","ownerWallet","telegramChatId"]},"primaryToken":{"type":"object","properties":{"createdAt":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"merchantId":{"type":"string"},"mint":{"type":"string"}},"required":["createdAt","id","merchantId","mint"]},"webhookSecret":{"type":"string","description":"HMAC-SHA256 secret for callback signatures. Shown once."}},"required":["apiKey","merchant","primaryToken","webhookSecret"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"REGISTRATION_RATE_LIMITED: retry later."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[],"summary":"Register business account","tags":["Get started"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"callbackUrl":{"type":"string","format":"uri"},"displayName":{"type":"string","minLength":2,"maxLength":80},"indexTokenMint":{"type":"string"},"ownerWallet":{"type":"string"},"telegramChatId":{"type":"string","pattern":"^-?[0-9]{3,32}$"}},"required":["callbackUrl","displayName","indexTokenMint","ownerWallet","telegramChatId"]}}},"required":true}}},"/api/payments":{"post":{"description":"Creates a payment intent and returns the merchant SPL transfer details, the fixed gateway fee, and a hosted checkout URL. Gateway confirms a payment made through the hosted checkout on its own and sends the signed payment.confirmed callback.","operationId":"post /api/payments","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"checkoutReference":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"},"confirmedAt":{"type":"string"},"createdAt":{"type":"string"},"customerTelegramChatId":{"type":"string"},"expiresAt":{"type":"string"},"gatewayFeeLamports":{"type":"string"},"gatewayFeeWallet":{"type":"string"},"id":{"type":"string"},"merchantAmountRaw":{"type":"string"},"merchantTokenMint":{"type":"string"},"merchantWallet":{"type":"string"},"payerWallet":{"type":"string"},"reference":{"type":"string"},"signature":{"type":"string"},"solanaMemo":{"type":"string"},"solanaPayTransactionUrl":{"type":"string"},"status":{"type":"string","enum":["CONFIRMED","EXPIRED","FAILED","PENDING"]}},"required":["checkoutReference","checkoutUrl","createdAt","customerTelegramChatId","expiresAt","gatewayFeeLamports","gatewayFeeWallet","id","merchantAmountRaw","merchantTokenMint","merchantWallet","reference","solanaMemo","solanaPayTransactionUrl","status"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Create hosted checkout","tags":["One-off payments"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"checkoutReference":{"type":"string","minLength":3,"maxLength":120},"customerTelegramChatId":{"type":"string","pattern":"^-?[0-9]{3,32}$"},"merchantAmountRaw":{"type":"string","pattern":"^[1-9][0-9]*$"},"merchantTokenMint":{"type":"string"},"payerWallet":{"type":"string"}},"required":["checkoutReference","customerTelegramChatId","merchantAmountRaw"]}}},"required":true}}},"/api/checkout/{paymentId}":{"get":{"description":"Public checkout status used by the hosted checkout page. status moves from PENDING to CONFIRMED once Gateway finds and verifies the payment by its reference.","operationId":"get /api/checkout/{paymentId}","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The checkout payment with its current status.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[],"summary":"Checkout status","tags":["One-off payments"],"parameters":[{"in":"path","name":"paymentId","required":true,"schema":{"type":"string"}},{"description":"The customer reference from the hosted checkout URL.","in":"query","name":"reference","required":true,"schema":{"maxLength":120,"minLength":3,"type":"string"}}]}},"/api/payments/{paymentId}/confirm":{"post":{"description":"Verifies the Solana transaction on-chain, marks the payment CONFIRMED, sends the signed payment.confirmed callback, and notifies the customer and the merchant Telegram chats. Gateway confirms hosted checkout payments on its own by their reference, so this call is only needed when your app sends the transaction itself. Gateway reads the transaction at finalized commitment, about 13 seconds after it is sent; before that the request fails with a not-found error and should be retried.","operationId":"post /api/payments/{paymentId}/confirm","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"merchantTelegramNotification":{"type":"object"},"payment":{"type":"object","properties":{"checkoutReference":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"},"confirmedAt":{"type":"string"},"createdAt":{"type":"string"},"customerTelegramChatId":{"type":"string"},"expiresAt":{"type":"string"},"gatewayFeeLamports":{"type":"string"},"gatewayFeeWallet":{"type":"string"},"id":{"type":"string"},"merchantAmountRaw":{"type":"string"},"merchantTokenMint":{"type":"string"},"merchantWallet":{"type":"string"},"payerWallet":{"type":"string"},"reference":{"type":"string"},"signature":{"type":"string"},"solanaMemo":{"type":"string"},"solanaPayTransactionUrl":{"type":"string"},"status":{"type":"string","enum":["CONFIRMED","EXPIRED","FAILED","PENDING"]}},"required":["checkoutReference","checkoutUrl","createdAt","customerTelegramChatId","expiresAt","gatewayFeeLamports","gatewayFeeWallet","id","merchantAmountRaw","merchantTokenMint","merchantWallet","reference","solanaMemo","solanaPayTransactionUrl","status"]},"telegramNotification":{"type":"object"},"webhook":{"type":"object"}},"required":["merchantTelegramNotification","payment","telegramNotification","webhook"],"type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Confirm payment","tags":["One-off payments"],"parameters":[{"in":"path","name":"paymentId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string"}},"required":["signature"]}}},"required":true}}},"/api/analytics/summary":{"get":{"description":"Returns payment counts, confirmed gateway fee lamports including subscription collect fees, callback health, and indexed token count.","operationId":"get /api/analytics/summary","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"Payment analytics summary.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Payment analytics summary","tags":["Callbacks and reporting"]}},"/api/webhooks":{"get":{"description":"Returns the latest callback attempts with event type, status, HTTP code, and target URL.","operationId":"get /api/webhooks","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"Callback delivery attempts.","items":{"type":"object"},"type":"array"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Callback delivery history","tags":["Callbacks and reporting"]}},"/api/webhooks/{deliveryId}/retry":{"post":{"description":"Creates a fresh callback delivery attempt for payment.confirmed and stored subscription callback events. Retries and test callbacks share a limit of 10 per minute per merchant.","operationId":"post /api/webhooks/{deliveryId}/retry","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The new callback delivery attempt.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"WEBHOOK_RATE_LIMITED: retry later."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Retry callback delivery","tags":["Callbacks and reporting"],"parameters":[{"in":"path","name":"deliveryId","required":true,"schema":{"type":"string"}}]}},"/api/subscription-plans":{"post":{"description":"Creates a subscription plan. Publish and confirm it on Solana before use.","operationId":"post /api/subscription-plans","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The stored subscription plan.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Create subscription plan","tags":["Subscription plans"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amountRaw":{"type":"string","pattern":"^[1-9][0-9]*$"},"displayName":{"type":"string","minLength":2,"maxLength":80},"metadataUri":{"type":"string","maxLength":128,"format":"uri"},"periodSeconds":{"type":"integer","minimum":3600,"maximum":31536000},"planReference":{"type":"string","minLength":3,"maxLength":120},"pullerWallet":{"type":"string"},"tokenMint":{"type":"string"}},"required":["amountRaw","displayName","periodSeconds","planReference","tokenMint"]}}},"required":true}}},"/api/subscription-plans/{planId}/transactions/create-plan":{"post":{"description":"Returns an unsigned base64 transaction for the business wallet to publish the Solana subscription plan.","operationId":"post /api/subscription-plans/{planId}/transactions/create-plan","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Publish subscription plan transaction","tags":["Subscription plans"],"parameters":[{"in":"path","name":"planId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"]}}},"required":true}}},"/api/subscription-plans/{planId}/transactions/update-plan":{"post":{"description":"Returns an unsigned base64 transaction for the business wallet to restore an on-chain plan or sunset it from new subscribers.","operationId":"post /api/subscription-plans/{planId}/transactions/update-plan","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Update on-chain plan transaction","tags":["Subscription plans"],"parameters":[{"in":"path","name":"planId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"account":{"type":"string"},"endTs":{"default":"0","type":"string","const":"0"},"onchainStatus":{"type":"string","const":"active"}},"required":["account","onchainStatus"]},{"type":"object","properties":{"account":{"type":"string"},"endTs":{"type":"string","pattern":"^[0-9]+$"},"onchainStatus":{"type":"string","const":"sunset"}},"required":["account","endTs","onchainStatus"]}]}}},"required":true}}},"/api/subscription-plans/{planId}/confirm":{"post":{"description":"Verifies a create-plan or update-plan transaction. A create-plan confirmation marks the plan ACTIVE and sends subscription_plan.confirmed; an update-plan confirmation sends subscription_plan.updated_onchain. Gateway reads the transaction at finalized commitment, about 13 seconds after it is sent; before that the request fails with a not-found error and should be retried.","operationId":"post /api/subscription-plans/{planId}/confirm","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The confirmed subscription plan and its callback delivery.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Confirm subscription plan or on-chain plan update","tags":["Subscription plans"],"parameters":[{"in":"path","name":"planId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"oneOf":[{"type":"object","properties":{"action":{"type":"string","const":"update-plan"},"signature":{"type":"string"},"endTs":{"default":"0","type":"string","const":"0"},"onchainStatus":{"type":"string","const":"active"}},"required":["action","signature","onchainStatus"]},{"type":"object","properties":{"action":{"type":"string","const":"update-plan"},"signature":{"type":"string"},"endTs":{"type":"string","pattern":"^[0-9]+$"},"onchainStatus":{"type":"string","const":"sunset"}},"required":["action","signature","endTs","onchainStatus"]}]},{"type":"object","properties":{"action":{"default":"create-plan","type":"string","const":"create-plan"},"signature":{"type":"string"}},"required":["signature"]}]}}},"required":true}}},"/api/subscription-plans/{planId}/pause":{"post":{"description":"Pauses an ACTIVE subscription plan.","operationId":"post /api/subscription-plans/{planId}/pause","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The paused subscription plan.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Pause subscription plan","tags":["Subscription plans"],"parameters":[{"in":"path","name":"planId","required":true,"schema":{"type":"string"}}]}},"/api/subscription-plans/{planId}/resume":{"post":{"description":"Resumes a paused subscription plan.","operationId":"post /api/subscription-plans/{planId}/resume","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The resumed subscription plan.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Resume subscription plan","tags":["Subscription plans"],"parameters":[{"in":"path","name":"planId","required":true,"schema":{"type":"string"}}]}},"/api/subscription-plans/{planId}/archive":{"post":{"description":"Archives a subscription plan when the offer should no longer be sold.","operationId":"post /api/subscription-plans/{planId}/archive","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The archived subscription plan.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Archive subscription plan","tags":["Subscription plans"],"parameters":[{"in":"path","name":"planId","required":true,"schema":{"type":"string"}}]}},"/api/subscriptions":{"post":{"description":"Creates a customer subscription on an ACTIVE plan and returns a hosted subscription checkout URL. customerReference is idempotent per plan.","operationId":"post /api/subscriptions","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The customer subscription with its checkoutUrl.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Create customer subscription","tags":["Customer subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customerReference":{"type":"string","minLength":3,"maxLength":120},"customerTelegramChatId":{"type":"string","pattern":"^-?[0-9]{3,32}$"},"planId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"subscriberWallet":{"type":"string"}},"required":["customerReference","customerTelegramChatId","planId","subscriberWallet"]}}},"required":true}}},"/api/subscription-checkout/{subscriptionId}/transactions/init-authority":{"post":{"description":"Hosted checkout route. Returns an unsigned base64 wallet setup transaction without the merchant Gateway API key.","operationId":"post /api/subscription-checkout/{subscriptionId}/transactions/init-authority","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[],"summary":"Hosted wallet setup transaction","tags":["Hosted subscription checkout"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}},{"description":"The customer reference from the hosted checkout URL.","in":"query","name":"reference","required":true,"schema":{"maxLength":120,"minLength":3,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"]}}},"required":true}}},"/api/subscription-checkout/{subscriptionId}/transactions/subscribe":{"post":{"description":"Hosted checkout route. Returns an unsigned base64 subscribe transaction.","operationId":"post /api/subscription-checkout/{subscriptionId}/transactions/subscribe","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[],"summary":"Hosted subscribe transaction","tags":["Hosted subscription checkout"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}},{"description":"The customer reference from the hosted checkout URL.","in":"query","name":"reference","required":true,"schema":{"maxLength":120,"minLength":3,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"},"expectedSubscriptionAuthorityInitId":{"type":"string","pattern":"^[0-9]+$"}},"required":["account"]}}},"required":true}}},"/api/subscription-checkout/{subscriptionId}/transactions/cancel":{"post":{"description":"Hosted checkout route. Returns an unsigned base64 cancel transaction.","operationId":"post /api/subscription-checkout/{subscriptionId}/transactions/cancel","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[],"summary":"Hosted cancel transaction","tags":["Hosted subscription checkout"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}},{"description":"The customer reference from the hosted checkout URL.","in":"query","name":"reference","required":true,"schema":{"maxLength":120,"minLength":3,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"]}}},"required":true}}},"/api/subscription-checkout/{subscriptionId}/transactions/resume":{"post":{"description":"Hosted checkout route. Returns an unsigned base64 resume transaction for a canceled subscription before the current billing period ends.","operationId":"post /api/subscription-checkout/{subscriptionId}/transactions/resume","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[],"summary":"Hosted resume transaction","tags":["Hosted subscription checkout"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}},{"description":"The customer reference from the hosted checkout URL.","in":"query","name":"reference","required":true,"schema":{"maxLength":120,"minLength":3,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"]}}},"required":true}}},"/api/subscription-checkout/{subscriptionId}/confirm":{"post":{"description":"Verifies the customer subscribe, cancel, or resume signature, updates the subscription, sends the signed callback, and notifies the customer in Telegram. Gateway reads the transaction at finalized commitment, about 13 seconds after it is sent; before that the request fails with a not-found error and should be retried.","operationId":"post /api/subscription-checkout/{subscriptionId}/confirm","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The updated customer subscription.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[],"summary":"Hosted subscription confirmation","tags":["Hosted subscription checkout"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}},{"description":"The customer reference from the hosted checkout URL.","in":"query","name":"reference","required":true,"schema":{"maxLength":120,"minLength":3,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"default":"subscribe","type":"string","enum":["subscribe","cancel","resume"]},"signature":{"type":"string"}},"required":["signature"]}}},"required":true}}},"/api/subscriptions/{subscriptionId}/transactions/init-authority":{"post":{"description":"Returns an unsigned base64 transaction that prepares the customer's wallet for recurring Solana payments.","operationId":"post /api/subscriptions/{subscriptionId}/transactions/init-authority","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Prepare customer wallet transaction","tags":["Customer subscriptions"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"]}}},"required":true}}},"/api/subscriptions/{subscriptionId}/transactions/subscribe":{"post":{"description":"Returns an unsigned base64 transaction for the customer wallet to subscribe.","operationId":"post /api/subscriptions/{subscriptionId}/transactions/subscribe","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Create customer subscribe transaction","tags":["Customer subscriptions"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"},"expectedSubscriptionAuthorityInitId":{"type":"string","pattern":"^[0-9]+$"}},"required":["account"]}}},"required":true}}},"/api/subscriptions/{subscriptionId}/transactions/cancel":{"post":{"description":"Returns an unsigned base64 transaction that lets the customer cancel the subscription on Solana.","operationId":"post /api/subscriptions/{subscriptionId}/transactions/cancel","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Cancel customer subscription transaction","tags":["Customer subscriptions"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"]}}},"required":true}}},"/api/subscriptions/{subscriptionId}/transactions/resume":{"post":{"description":"Returns an unsigned base64 transaction that lets the customer resume a canceled subscription before the current period ends.","operationId":"post /api/subscriptions/{subscriptionId}/transactions/resume","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Resume customer subscription transaction","tags":["Customer subscriptions"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"]}}},"required":true}}},"/api/subscriptions/{subscriptionId}/confirm":{"post":{"description":"Verifies the matching subscription transaction, updates the subscription status or next billing date, sends a signed subscription callback, and notifies the customer in Telegram. Gateway reads the transaction at finalized commitment, about 13 seconds after it is sent; before that the request fails with a not-found error and should be retried.","operationId":"post /api/subscriptions/{subscriptionId}/confirm","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The updated customer subscription.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Confirm subscription action","tags":["Customer subscriptions"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["subscribe","collect","cancel","resume"]},"signature":{"type":"string"}},"required":["action","signature"]}}},"required":true}}},"/api/subscriptions/{subscriptionId}/expire":{"post":{"description":"Expires a canceled customer subscription after the current period ends and sends a subscription.expired callback.","operationId":"post /api/subscriptions/{subscriptionId}/expire","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The expired customer subscription.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Expire canceled subscription","tags":["Customer subscriptions"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}}]}},"/api/subscriptions/due":{"get":{"description":"Returns active or past due customer subscriptions whose active plan is ready for collection.","operationId":"get /api/subscriptions/due","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"Due customer subscriptions.","items":{"type":"object"},"type":"array"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"List due subscriptions","tags":["Collecting subscription payments"]}},"/api/subscriptions/due/queue":{"get":{"description":"Returns due collection worker items with subscription, plan, pullerWallet, collectTransactionPath, confirmPath, and pastDuePath.","operationId":"get /api/subscriptions/due/queue","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"Collection worker items.","items":{"type":"object"},"type":"array"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Collection worker queue","tags":["Collecting subscription payments"]}},"/api/subscriptions/{subscriptionId}/transactions/collect":{"post":{"description":"Returns an unsigned base64 transaction that collects the next due subscription payment. The signer must be the plan's puller wallet.","operationId":"post /api/subscriptions/{subscriptionId}/transactions/collect","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"transaction":{"type":"string","description":"Unsigned base64 Solana transaction for the wallet to sign."}},"required":["message","transaction"]},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Collect subscription payment transaction","tags":["Collecting subscription payments"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"]}}},"required":true}}},"/api/subscriptions/{subscriptionId}/past-due":{"post":{"description":"Marks an active customer subscription PAST_DUE after the next billing date when the worker could not collect, and sends a subscription.past_due callback.","operationId":"post /api/subscriptions/{subscriptionId}/past-due","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"The past due customer subscription.","type":"object"},"ok":{"const":true,"type":"boolean"}},"required":["ok","data"],"type":"object"}}},"description":"Success."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"VALIDATION_ERROR or another request error."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"UNAUTHENTICATED: missing or invalid x-gateway-key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The resource does not exist for this merchant."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"CONFLICT: the request conflicts with an existing record. SUBSCRIPTION_STATE_CHANGED: another request changed the subscription first; read it again and retry."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"INTERNAL_ERROR: unexpected server error."}},"security":[{"gatewayKey":[]}],"summary":"Mark subscription past due","tags":["Collecting subscription payments"],"parameters":[{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string"}}]}}},"servers":[{"url":"https://sandbox.gate.solknife.xyz"}],"webhooks":{"gatewayCallback":{"post":{"description":"Gateway posts a signed callback to the merchant callbackUrl for payment.confirmed, subscription_plan.confirmed, subscription_plan.updated_onchain, subscription.subscribe, subscription.collect, subscription.cancel, subscription.resume, subscription.past_due, subscription.expired, and gateway.test (sent by the test callback endpoint). Verify x-solknife-signature as the hex HMAC-SHA256 of \"<x-solknife-timestamp>.<raw body>\" with the webhook secret, reject a timestamp more than 300 seconds from your clock, and drop any x-solknife-delivery-id you already processed.","parameters":[{"description":"The callback event type.","in":"header","name":"x-solknife-event","required":true,"schema":{"type":"string"}},{"description":"Unique id of this delivery. Drop a callback whose delivery id you already processed.","in":"header","name":"x-solknife-delivery-id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Hex HMAC-SHA256 of \"<x-solknife-timestamp>.<raw body>\", keyed with the webhook secret.","in":"header","name":"x-solknife-signature","required":true,"schema":{"type":"string"}},{"description":"Unix time in seconds when Gateway signed the delivery. Reject it when it is more than 300 seconds from your clock.","in":"header","name":"x-solknife-timestamp","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"eventType":{"type":"string"}},"required":["eventType"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Return any 2xx status to acknowledge."}},"summary":"Callback verification"}}}}