api.botsubscription.com

GET/v1/endpoint

AuthenticationBearer

Token

Stays in this tab. Required for this endpoint — the value below is what gets sent.

Path parameters0

Query parameters0

BodyJSON

Mock

curl --request GET \
  --url https://api.botsubscription.com/v1/endpoint \
  --header 'Authorization: Bearer sk_live_•••'

Create a Subscription Bot Payment Request

Create a hosted checkout for a subscription bot for Telegram and Discord. A website integration should call this endpoint from its backend with a project API key, then send the returned data.payment_url to the browser.

Keep the project API key on your server. Do not expose it in browser code.

POST/v2/projects/{project_id}/payment-requests

Authorization

Bearer TokenRequired

Website-first checkout flow

Customer website
  -> backend creates a Payment Request with the project API key
  -> backend returns data.payment_url
  -> browser opens Stripe Checkout
  -> Stripe returns the browser to success_url or cancel_url
  -> webhook or Payment Request status confirms payment

The browser redirect is a navigation step, not proof of payment. Treat a verified payment-request.completed webhook or the status returned by Get Payment Request as authoritative.

Use a custom return hostname when needed

You do not need to configure custom_hostname to create a Payment Request. No custom hostname setup is required when you omit success_url and cancel_url or use the default return hostname provided by BotSubscription.

Configure custom_hostname only when a supplied return URL should use your own hostname. See Configure Custom Hostname for the request, required scope, value format, and possible conflicts.

Return URL contract

success_url and cancel_url are checked independently. For each field you provide:

The complete JSON value must be an http:// or https:// URL.
Its hostname must exactly match a return hostname trusted for the project: either the default hostname provided by BotSubscription or the configured custom_hostname. For example, a configured value of example.com does not authorize www.example.com or subdomain.example.com.
Its path and query string may vary because authorization is based on the configured hostname.
Validation uses the success_url and cancel_url JSON fields. HTTP Origin and Referer headers do not authorize a return URL.

If either supplied URL is malformed or uses an unauthorized hostname, the API rejects the request with 422. It does not treat the current Origin, Referer, CORS configuration, or caller location as a substitute.

Request

Path Parameters

project_idstringrequired

The unique identifier of the project.

Request Headers

Idempotency-Keystring

Recommended unique key for this checkout attempt. Reuse the same key when retrying the same request to avoid creating duplicate Payment Requests.

Request Body

user_idstring

Platform user ID for the customer. For Discord, this may be a snowflake. Supply it when creating a website checkout with a project API key; a previously unknown user is accepted and can be materialized locally.

plan_idstringrequired

Plan UUID to purchase. If amount is omitted, the plan's configured price and duration are authoritative.

merchant_account_idstring

Merchant account UUID that selects the payment gateway. It is required unless a supported account-balance flow is used.

amountstring

Optional charged amount as a decimal string. If omitted, use the plan's configured price and duration. With coupon_id, this is the gross amount; do not pre-discount it.

coupon_idstring

Optional coupon UUID. The gateway charges the discounted net amount; do not pre-discount amount.

providerstring

Not required for project-key creation. merchant_account_id selects the gateway; provider: 'stripe' is ignored. Use 'internal' only for a supported account-balance flow.

success_urlstring

Optional complete HTTP(S) URL for a successful return. This field is validated independently: its hostname must exactly match the project's default trusted hostname or custom_hostname, while its path and query may vary. Validation uses this JSON field, not Origin or Referer.

cancel_urlstring

Optional complete HTTP(S) URL for a cancelled return. This field is validated independently: its hostname must exactly match the project's default trusted hostname or custom_hostname, while its path and query may vary. Validation uses this JSON field, not Origin or Referer.

For project-key creation, omit "provider": "stripe". The selected merchant_account_id determines that Stripe is the payment gateway.

curl -X POST "https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/payment-requests" \
  -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-order-8472" \
  -d '{
    "user_id": "123456789012345678",
    "plan_id": "11111111-1111-1111-1111-111111111111",
    "merchant_account_id": "22222222-2222-2222-2222-222222222222",
    "success_url": "https://example.com/checkout/success?order=8472",
    "cancel_url": "https://example.com/checkout/cancel?order=8472"
  }'

const projectId = 'YOUR_PROJECT_ID';
const response = await fetch(`https://api.botsubscription.com/v2/projects/${projectId}/payment-requests`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_PROJECT_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'checkout-order-8472'
  },
  body: JSON.stringify({
    user_id: '123456789012345678',
    plan_id: '11111111-1111-1111-1111-111111111111',
    merchant_account_id: '22222222-2222-2222-2222-222222222222',
    success_url: 'https://example.com/checkout/success?order=8472',
    cancel_url: 'https://example.com/checkout/cancel?order=8472'
  })
});
const result = await response.json();
 
// Return this URL to your frontend; do not expose the API key.
const paymentUrl = result.data.payment_url;

import requests
 
project_id = 'YOUR_PROJECT_ID'
response = requests.post(
    f'https://api.botsubscription.com/v2/projects/{project_id}/payment-requests',
    headers={
        'Authorization': 'Bearer YOUR_PROJECT_API_KEY',
        'Content-Type': 'application/json',
        'Idempotency-Key': 'checkout-order-8472'
    },
    json={
        'user_id': '123456789012345678',
        'plan_id': '11111111-1111-1111-1111-111111111111',
        'merchant_account_id': '22222222-2222-2222-2222-222222222222',
        'success_url': 'https://example.com/checkout/success?order=8472',
        'cancel_url': 'https://example.com/checkout/cancel?order=8472'
    }
)
result = response.json()
payment_url = result['data']['payment_url']

$project_id = 'YOUR_PROJECT_ID';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.botsubscription.com/v2/projects/{$project_id}/payment-requests");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_PROJECT_API_KEY',
    'Content-Type: application/json',
    'Idempotency-Key: checkout-order-8472'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'user_id' => '123456789012345678',
    'plan_id' => '11111111-1111-1111-1111-111111111111',
    'merchant_account_id' => '22222222-2222-2222-2222-222222222222',
    'success_url' => 'https://example.com/checkout/success?order=8472',
    'cancel_url' => 'https://example.com/checkout/cancel?order=8472'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Payment request createdapplication/json

{
  "ok": true,
  "request_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/payment-requests",
  "code": 201,
  "message": "Payment request created successfully",
  "data": {
    "payment_request_id": "11111111-1111-1111-1111-111111111111",
    "payment_url": "https://checkout.stripe.com/c/pay/cs_live_example",
    "merchant_account_id": "22222222-2222-2222-2222-222222222222",
    "amount": "23.99",
    "currency": "USD",
    "status": "pending",
    "request_type": "invoice",
    "created_at": "2026-08-29T10:30:00.000Z",
    "user_id": "123456789012345678",
    "provider": "stripe",
    "provider_payment_id": "pi_3NkQz2ABC123",
    "settled_at": null,
    "payment_request_data": {}
  }
}

data.payment_url is a direct Stripe Checkout URL. Return it to your frontend and navigate the customer's browser to it.

Return URL rejectedapplication/json

{
  "ok": false,
  "request_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/payment-requests",
  "code": 422,
  "error": {
    "error_code": "REDIRECT_ORIGIN_NOT_ALLOWED",
    "message": "The success_url hostname is not authorized for this project"
  }
}

Active membership conflictapplication/json

{
  "ok": false,
  "request_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/payment-requests",
  "code": 409,
  "error": {
    "error_code": "CONFLICT",
    "message": "User already has an active membership for this plan"
  }
}

Platform user and community behavior

A user_id may identify a platform user the project has not seen before. For Discord, you may supply that user's snowflake. The API can materialize the local user automatically, so the customer does not need to be in the corresponding Discord guild or Telegram community while paying.

Payment does not join the customer to a Discord guild, Telegram group, or Telegram channel. If the same platform account joins later, BotSubscription restores applicable access while the membership remains valid and the bot has the required permissions. For Discord, this includes restoring active membership roles.

Confirm payment authoritatively

Do not grant access from the success_url redirect alone. Customers can revisit or copy redirect URLs, and browser navigation can occur before asynchronous payment processing finishes.

Use a verified completion webhook or fetch the Payment Request until it reaches an authoritative status. The webhook signature guide explains how to verify server-to-server events.

Errors

Status	Meaning
`409`	The user already has an active membership, or another documented resource conflict prevents creation.
`422`	A return URL is malformed, is not HTTP(S), or has a hostname that is not trusted for the project.
`403`	The token lacks the required scope or is not authorized for the project or resource.
`404`	The plan, merchant account, project, or another referenced resource does not exist.
`5xx`	A genuine internal failure. Invalid or unauthorized return URLs are not expected to produce a server error.

Last updated: August 29, 2026