JetBot API v1.0

Integration documentation for partners.

1. Connection and Authentication

To work with the API, follow these steps:

1. Get Bearer Token: Contact the JetBot administrator to create an API account and receive an access token.
2. Generate RSA Keys: You need an RSA key pair (4096 bit) to sign requests.
   • The Private Key remains with you and is used to generate the signature.
   • The Public Key must be provided to the administrator to verify your requests.
3. Whitelist IP: Provide the static IP address of your server from which requests will be sent. Access to the API is allowed only from trusted IPs.

Important: Your merchant API balance is directly linked to your Telegram account balance in the bot. To top up your balance, you need to perform a standard deposit operation via the Telegram bot: @jetpaycryptobot.

Important: Sandbox uses separate credentials, tokens, and URLs. Request access to the Sandbox separately for safe integration testing.

Request Headers

All API requests must contain the Authorization HTTP header:

Authorization: Bearer YOUR_TOKEN

2. Signature Generation

Methods that change state (e.g., creating a payout) require a mandatory signature parameter to protect against request forgery.

RSA-SHA512 Signature Algorithm:

1. Collect all parameters from the request body (JSON or Form-data) into a dictionary.
2. Exclude the signature field from this dictionary if present.
3. Sort the parameters by keys (parameter names) alphabetically (A-Z).
4. Assemble the string for signing in the format: METHOD_PATH?key1=value1&key2=value2.
   Example string: /api/payout?amount=1000&order_id=123&recipient=4444555566667777
   Note: parameter values must be exactly the same as in the sent request.
5. Sign the resulting string with your Private Key using the SHA512 hashing algorithm.
6. Encode the resulting binary signature into a Base64 string.
7. Pass this string in the signature parameter in the request body.

Python Code Example:

from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import padding
import base64

def sign_request(method_path, data, private_key_path):
    # 1. Sorting and assembling the string
    sorted_keys = sorted([k for k in data.keys() if k != 'signature'])
    params = [f"{k}={data[k]}" for k in sorted_keys]
    data_string = f"{method_path}?{'&'.join(params)}"
    
    # 2. Loading the key
    with open(private_key_path, "rb") as key_file:
        private_key = serialization.load_pem_private_key(
            key_file.read(), password=None
        )
        
    # 3. Signing
    signature = private_key.sign(
        data_string.encode(),
        padding.PKCS1v15(),
        hashes.SHA512()
    )
    
    return base64.b64encode(signature).decode()

3. API Methods

Get the current balance of your merchant account in USDT.

Example Response:

{
  "balance": 5400.50,
  "currency": "USDT"
}

Get the current USDT/RUB exchange rate for your merchant account. No signature required.

Example Response:

{
  "rate": "71.82"
}

The rate field is a string with two decimal places (dot as separator), rubles per 1 USDT.

Create a new payout request to a bank card (in RUB).

Parameter	Type	Required	Description
amount	Float/Int	Yes	Payout amount in Rubles (RUB). Min and max amounts depend on current service limits (usually 100 - 60000 RUB).
recipient	String	Yes	Recipient's bank card number (digits only, no spaces, 16 digits).
order_id	String	Yes	Unique order ID in your system. Used to prevent duplicates and check status.
phone	String	No	Recipient's phone number in format 79xxxxxxxxx (11 digits). If not provided, a placeholder is used.
name	String	No	Recipient's name (Latin or Cyrillic). Useful for some payment gateways.
signature	String	Yes	RSA-SHA512 signature of the request (see "Signature Generation" section).

Example Success Response:

{
  "status": "success",
  "id": "provider_abc123",  // Transaction ID in the processing gateway
  "payout_id": 42          // Internal payout ID in JetBot
}

Create a new payout via SBP (Faster Payments System / Система быстрых платежей) — by recipient phone number and bank, without a card number. This is a separate endpoint; /api/payout and its behavior remain unchanged.

SBP payout specifics:

• Always processed manually (confirmed by an administrator). The response status is created.
• Maximum amount — 20,000 RUB per payout.
• Exchange rate is 1% lower than the standard one (multiplier reduced, e.g. 0.93 → 0.92).

Signature: generated the same way as for /api/payout, but the method path is /api/payout/sbp (example string: /api/payout/sbp?amount=5000&bank=Sberbank&name=Ivan Ivanov&order_id=123&phone=79001234567).

Parameter	Type	Required	Description
amount	Float/Int	Yes	Payout amount in rubles (RUB). From 100 to 20,000 RUB.
bank	String	Yes	Recipient's bank name (e.g., "Sberbank", "Tinkoff"). 2–50 characters.
name	String	Yes	Recipient's name.
phone	String	Yes	Recipient's phone number (Russian mobile, format 79xxxxxxxxx; input starting with 8 or +7 is normalized automatically).
order_id	String	Yes	Unique order identifier in your system.
signature	String	Yes	RSA-SHA512 signature of the request (method path — /api/payout/sbp).

Example Success Response:

{
  "status": "created",      // SBP payout accepted, awaiting manual confirmation
  "id": "19E3BABE0796332",  // Public ID (used for status checks and receipts)
  "order_id": "my_order_001",
  "payout_id": 42           // Internal payout ID in JetBot
}

Get the current status of a payout. You can use the following as <ID>:

• payout_id - internal JetBot ID (returned upon creation).
• order_id - your unique order ID (merchant_order_id).
• id - gateway ID.

Example Response:

{
  "id": 42,
  "order_id": "my_order_001",
  "amount": 1500.00,
  "status": "confirmed",     // Possible statuses: confirmed, pending, failed, cancelled
  "jetbot_status": "success", // Detailed gateway status: success, process, error, etc.
  "payout_type": "card",     // Payout type: "card" or "sbp"
  "recipient": "4276....1234", // For SBP — 3-line details: name, bank, phone
  "created_at": "2023-10-27 14:30:00"
}

Download a PDF receipt for a successful payout. Use the receipt ID (id field returned when creating a payout) as <public_id>. Internal payout number (payout_id), order_id, and other identifiers cannot be used to download receipts. No signature required.

The response is a PDF file (Content-Type: application/pdf). The time on the receipt is in Moscow time (MSK, UTC+3).

Example Request (cURL):

curl -H "Authorization: Bearer <TOKEN>" \
     -o receipt.pdf \
     https://api.jetbot.pw/api/payout/358472DC4B20E6A/receipt

Possible Errors:

• 409 — the payout is still processing or has failed (receipts are only available for successful payouts).
• 404 — payout not found.

4. Error Codes

Code	Description
400	Bad Request. Parameter validation error (invalid card format, missing required fields, etc.).
401	Unauthorized. Invalid or missing Bearer Token.
402	Payment Required. Insufficient funds on the merchant balance to make the payout.
403	Forbidden. Access denied. Possible reasons: IP address not whitelisted, invalid digital signature.
404	Not Found. Requested resource (e.g., payout by ID) not found.
500	Internal Server Error. Internal server error or error on the payout provider side.
503	Service Unavailable. Service temporarily unavailable or rate limit exceeded.

5. Rate Limits

To ensure API stability, the following limits apply:

• API (api.jetbot.pw): 10 requests per second per IP.
• If the limit is exceeded, the server will return a 503 response code. Please implement a retry mechanism with exponential backoff.