Docs | SolKnife Gateway

Register your business wallet, accepted payment token, callback URL, Telegram chat id, and app domain.
Store the API key and callback secret on your backend. Never expose them in a browser.
Ask the customer to add @solknife_bot, then create an intent with the chat id they provide.
Send the customer through a Solana payment that includes your business payment and SolKnife's fixed SOL fee.
Confirm the signature through Gateway, then verify the signed callback before updating app records.

Subscription status

Gateway now stores Solana subscription plans, customer subscription records, and an unsigned transaction flow for publishing plans, preparing a customer wallet, subscribing, collecting each due payment, canceling, resuming, and updating on-chain plan status. Confirm the signed Solana customer transactions through Gateway so the plan status, customer subscription status, and next billing date stay in sync with the blockchain.

POST /api/merchants/register

{
  "displayName": "Acme SaaS",
  "ownerWallet": "business payout wallet",
  "indexTokenMint": "accepted token address",
  "callbackUrl": "https://app.example/callback",
  "telegramChatId": "123456789"
}

Create hosted checkout

POST /api/payments
x-gateway-key: sk_live_...

{
  "checkoutReference": "order-1001",
  "customerTelegramChatId": "123456789",
  "merchantAmountRaw": "250000000",
  "merchantTokenMint": "accepted token address"
}

Response:
{
  "merchantAmountRaw": "250000000",
  "gatewayFeeLamports": "1200000",
  "checkoutUrl": "https://gateway.solknife.xyz/checkout/..."
}

Create subscription plan

POST /api/subscription-plans
x-gateway-key: sk_live_...

{
  "planReference": "starter-monthly",
  "displayName": "Starter monthly",
  "amountRaw": "49000000",
  "periodSeconds": 2592000,
  "tokenMint": "accepted token address",
  "pullerWallet": "optional recurring collection wallet",
  "metadataUri": "https://app.example/plan.json"
}

Publish subscription plan transaction

POST /api/subscription-plans/{planId}/transactions/create-plan
x-gateway-key: sk_live_...

{
  "account": "business payout wallet"
}

Returns an unsigned base64 transaction for the business wallet to publish the Solana subscription plan.

Confirm subscription plan

POST /api/subscription-plans/{planId}/confirm
x-gateway-key: sk_live_...

{
  "signature": "solana transaction signature"
}

Verifies the create-plan transaction, marks the plan ACTIVE, and sends a signed subscription_plan.confirmed callback.

Update on-chain plan transaction

POST /api/subscription-plans/{planId}/transactions/update-plan
x-gateway-key: sk_live_...

{
  "account": "business payout wallet",
  "onchainStatus": "sunset",
  "endTs": "1782000000"
}

Returns an unsigned base64 transaction for the business wallet to restore an on-chain plan or sunset it from new subscribers. Use "active" without endTs to restore the on-chain plan.
Use Gateway pause, resume, and archive endpoints to control whether the SaaS app offers the plan to new customers.

Confirm on-chain plan update

POST /api/subscription-plans/{planId}/confirm
x-gateway-key: sk_live_...

{
  "action": "update-plan",
  "signature": "solana transaction signature",
  "onchainStatus": "sunset",
  "endTs": "1782000000"
}

Verifies the update-plan transaction, records the signature, and sends a signed subscription_plan.updated_onchain callback. Use active without endTs to confirm an on-chain restore.
The Gateway plan status is still controlled by pause, resume, and archive endpoints.

Pause subscription plan

POST /api/subscription-plans/{planId}/pause
x-gateway-key: sk_live_...

Pauses an ACTIVE subscription plan. New customer subscriptions and collection workers should stop using a paused plan until it is resumed. Existing customer records remain stored in Gateway.

Resume subscription plan

POST /api/subscription-plans/{planId}/resume
x-gateway-key: sk_live_...

Resumes a paused subscription plan so new customer subscriptions and due collection workers can use it again.

Archive subscription plan

POST /api/subscription-plans/{planId}/archive
x-gateway-key: sk_live_...

Archives a subscription plan when the offer should no longer be sold. Archived plans stay available in records and reports, but new customer subscriptions and collection workers should stop using them.

Create customer subscription

POST /api/subscriptions
x-gateway-key: sk_live_...

{
  "planId": "subscription plan id",
  "customerReference": "cus_1001",
  "customerTelegramChatId": "123456789",
  "subscriberWallet": "customer Solana wallet"
}

Requires an ACTIVE subscription plan. Publish and confirm the plan before opening customer subscriptions.
customerReference is idempotent per plan, so the same SaaS customer can hold separate subscriptions for different plans or add-ons.
The customer wallet is required because Gateway derives the on-chain subscription account before activation.

Hosted subscription checkout

Response:
{
  "checkoutUrl": "https://gateway.solknife.xyz/subscription-checkout/..."
}

Hosted wallet setup transaction

POST /api/subscription-checkout/{subscriptionId}/transactions/init-authority?reference=cus_1001

{
  "account": "customer Solana wallet"
}

Hosted checkout route. Returns an unsigned base64 wallet setup transaction without requiring the merchant Gateway API key.

Hosted subscribe transaction

POST /api/subscription-checkout/{subscriptionId}/transactions/subscribe?reference=cus_1001

{
  "account": "customer Solana wallet",
  "expectedSubscriptionAuthorityInitId": "1"
}

Hosted checkout route. Returns an unsigned base64 subscribe transaction scoped to the customer reference on the checkout URL.

Hosted cancel transaction

POST /api/subscription-checkout/{subscriptionId}/transactions/cancel?reference=cus_1001

{
  "account": "customer Solana wallet"
}

Hosted checkout route. Returns an unsigned base64 cancel transaction for the customer wallet without requiring the merchant Gateway API key.

Hosted resume transaction

POST /api/subscription-checkout/{subscriptionId}/transactions/resume?reference=cus_1001

{
  "account": "customer Solana wallet"
}

Hosted checkout route. Returns an unsigned base64 resume transaction for a canceled subscription before the current billing period ends.

Hosted subscription confirmation

POST /api/subscription-checkout/{subscriptionId}/confirm?reference=cus_1001

{
  "action": "subscribe | cancel | resume",
  "signature": "solana transaction signature"
}

Verifies the customer subscribe, cancel, or resume signature, updates the subscription, sends the signed callback, and notifies the customer chat in Telegram.

Prepare customer wallet transaction

POST /api/subscriptions/{subscriptionId}/transactions/init-authority
x-gateway-key: sk_live_...

{
  "account": "customer Solana wallet"
}

Returns an unsigned base64 transaction that prepares the customer's wallet for recurring Solana payments.

Create customer subscribe transaction

POST /api/subscriptions/{subscriptionId}/transactions/subscribe
x-gateway-key: sk_live_...

{
  "account": "customer Solana wallet",
  "expectedSubscriptionAuthorityInitId": "1"
}

Returns an unsigned base64 transaction for the customer wallet to subscribe to the plan.
expectedSubscriptionAuthorityInitId is optional. Leave it out to let Gateway read the customer's SubscriptionAuthority from Solana.

List due subscriptions

GET /api/subscriptions/due
x-gateway-key: sk_live_...

Returns active or past due customer subscriptions whose active plan is ready for collection. Use each id to build a collect transaction from your backend worker.

Collection worker queue

GET /api/subscriptions/due/queue
x-gateway-key: sk_live_...

Returns due collection worker items with subscription, plan, pullerWallet, collectTransactionPath, confirmPath, and pastDuePath. For each item, build the collect transaction with the returned pullerWallet, send it on Solana, then confirm the signature through confirmPath. Use pastDuePath when your worker cannot collect after the billing date.

Collect subscription payment transaction

POST /api/subscriptions/{subscriptionId}/transactions/collect
x-gateway-key: sk_live_...

{
  "account": "subscription puller wallet"
}

Returns an unsigned base64 transaction that collects the next due subscription payment: the merchant receives the full subscription token amount, and SolKnife receives 1,200,000 lamports. The signer must be the plan's puller wallet.
Past due customer subscriptions use the same collect action. After the collect signature is confirmed, Gateway marks the customer subscription ACTIVE again and advances the next billing date.

Mark subscription past due

POST /api/subscriptions/{subscriptionId}/past-due
x-gateway-key: sk_live_...

Marks an active customer subscription PAST_DUE after the next billing date when your backend worker could not collect the payment. Use this only for subscriptions on active plans. This sends a subscription.past_due callback and Telegram notification, but does not build a Solana transaction or charge a gateway fee. Retries for an already PAST_DUE subscription return the stored subscription without sending another callback or Telegram message.

Cancel customer subscription transaction

POST /api/subscriptions/{subscriptionId}/transactions/cancel
x-gateway-key: sk_live_...

{
  "account": "customer Solana wallet"
}

Returns an unsigned base64 transaction that lets the customer cancel the subscription on Solana.
Customers can still cancel subscriptions on paused or archived plans, so businesses can retire offers without trapping existing customers.

Resume customer subscription transaction

POST /api/subscriptions/{subscriptionId}/transactions/resume
x-gateway-key: sk_live_...

{
  "account": "customer Solana wallet"
}

Returns an unsigned base64 transaction that lets the customer resume a canceled subscription on Solana before the current period ends. Gateway keeps the existing billing window instead of restarting billing.

Confirm subscription action

POST /api/subscriptions/{subscriptionId}/confirm
x-gateway-key: sk_live_...

{
  "action": "subscribe | collect | cancel | resume",
  "signature": "solana transaction signature"
}

Verifies the matching subscription transaction, updates the customer subscription status or next billing date, sends a signed subscription callback, and notifies the customer chat in Telegram.

Expire canceled subscription

POST /api/subscriptions/{subscriptionId}/expire
x-gateway-key: sk_live_...

Expires a canceled customer subscription after the current period ends. This sends a subscription.expired callback and Telegram notification, but does not build a Solana transaction or charge a gateway fee. Retries for an already EXPIRED subscription return the stored subscription without sending another subscription.expired callback or Telegram message.

Confirm payment

POST /api/payments/{paymentId}/confirm
x-gateway-key: sk_live_...

{
  "signature": "solana transaction signature"
}

Callback verification

x-solknife-event: payment.confirmed | subscription_plan.confirmed | subscription_plan.updated_onchain | subscription.subscribe | subscription.collect | subscription.cancel | subscription.resume | subscription.past_due | subscription.expired
x-solknife-signature: hmac_sha256(body, webhook_secret)

{
  "eventType": "payment.confirmed",
  "customerTelegramChatId": "123456789",
  "merchantAmountRaw": "250000000",
  "gatewayFeeLamports": "1200000",
  "gatewayFeeChargedLamports": "1200000",
  "status": "CONFIRMED"
}

Subscription callbacks use eventType subscription_plan.confirmed, subscription_plan.updated_onchain, subscription.subscribe, subscription.collect, subscription.cancel, subscription.resume, subscription.past_due, or subscription.expired and include the customer reference, plan id, billing period, status, configured gateway fee, and gateway fee charged for that action.

Payment analytics summary

GET /api/analytics/summary
x-gateway-key: sk_live_...

Returns payment counts, confirmed gateway fee lamports including subscription collect fees, callback health, and indexed token count.

Callback delivery history

GET /api/webhooks
x-gateway-key: sk_live_...

Returns the latest callback attempts with event type, status, HTTP code, and target URL.

Retry callback delivery

POST /api/webhooks/{deliveryId}/retry
x-gateway-key: sk_live_...

Creates a fresh callback delivery attempt for payment.confirmed and stored subscription callback events.

Add crypto checkout to your SaaS backend

Subscription status