API Integration Manual

This reference covers everything you need to integrate RubitPay's payment gateway into your platform — accepting payments from Russian and Chinese customers via a single, unified API.

Base URL

All API requests are made over HTTPS to the following base URL:

https://api.rubitpay.com

All requests must use UTF-8 encoding and the header:

Content-Type: application/json

Dates and times follow the ISO 8601 standard. When no time zone is specified, UTC+03:00 (Moscow Time) is assumed.

Authentication

Every API request must be signed using your shop_id and secret key. The signature is passed as the sign parameter in the request body. Contact your account manager to receive your credentials.

Request Signing

All request parameters (excluding sign itself) are used to generate the signature according to the following algorithm:

1. Sort all parameter keys alphabetically.
2. Concatenate their values with a colon (:) separator.
3. Append : and your secret key at the end.
4. Compute the SHA-256 hash of the resulting string.
5. Pass the hex digest as the sign field in your request body.

Example — Python

import hashlib

def generate_sign(params: dict, secret_key: str) -> str:
    # Sort keys alphabetically, exclude 'sign'
    keys = sorted(k for k in params.keys() if k != "sign")
    value_str = ":".join(str(params[k]) for k in keys)
    raw = value_str + ":" + secret_key
    return hashlib.sha256(raw.encode("utf-8")).hexdigest()

# Example for invoice/create
params = {
    "shop_id": "79834981",
    "shop_order_id": "ORDER-001",
    "amount": "299.45",
    "currency": "RUB",
    "payway": "bank_card",
}
# Sorted: amount, currency, payway, shop_id, shop_order_id
# String: "299.45:RUB:bank_card:79834981:ORDER-001:your_secret"
params["sign"] = generate_sign(params, "your_secret_key")

Backward Compatibility

RubitPay follows a stable API versioning policy. The following changes may occur at any time without incrementing the API version and are considered backward-compatible:

• Adding new optional request parameters to existing methods
• Adding new fields to existing API responses
• Changing the order of fields in responses
• Adding new error codes
• Adding new optional HTTP request or response headers
• Adding new types of webhook callback notifications

Single-Step Payment Flow

In a single-step payment, funds are blocked and charged immediately with a single invoice/create request.

1. User places an order on your platform.
2. Call invoice/try to pre-calculate the invoice and retrieve any additional parameters.
3. If result: true, check add_ons_config for any required additional fields.
4. Call invoice/create with all required parameters. Redirect the user to the returned payment URL.
5. RubitPay sends a webhook to your notification URL with the payment result.
6. On successful notification, the payment is complete.

Two-Step Payment Flow

In a two-step payment, funds are first held (blocked) and then explicitly charged or released. Most commonly used for bank card payments.

1. Call invoice/try to pre-calculate.
2. Call invoice/hold to block funds. Redirect the user to complete the hold authorization.
3. RubitPay notifies your URL when funds are successfully held.
4. Call invoice/charge to capture the held funds, or invoice/unhold to release them.
5. RubitPay sends a final webhook confirming the charge or unhold result.

Idempotency

To prevent duplicate invoices, shop_order_id must be unique per shop account. If you submit a request with the same shop_order_id as an existing invoice, the system will return the existing invoice rather than creating a new one.

invoice/try — Pre-calculate Invoice

Retrieves additional parameters required for invoice creation. Use this before invoice/create or invoice/hold to determine if any extra fields are needed for the selected payment method.

Request Parameters

Response Fields

invoice/create — Create Payment Invoice

Creates a payment invoice and returns the URL and method required to redirect the user to complete payment (single-step flow).

Request Parameters

Full Example

import hashlib, requests

def sign(params, secret):
    keys = sorted(k for k in params if k != "sign")
    raw = ":".join(str(params[k]) for k in keys) + ":" + secret
    return hashlib.sha256(raw.encode()).hexdigest()

payload = {
    "shop_id":       "YOUR_SHOP_ID",
    "shop_order_id": "ORD-20240412-001",
    "amount":        "1500.00",
    "currency":      "RUB",
    "payway":        "bank_card",
    "description":   "Order #001 — RubitPay Demo",
    "success_url":   "https://yourshop.com/success",
    "fail_url":      "https://yourshop.com/fail",
}
payload["sign"] = sign(payload, "YOUR_SECRET_KEY")

response = requests.post(
    "https://api.rubitpay.com/invoice/create",
    json=payload,
    headers={"Content-Type": "application/json"}
)
data = response.json()

if data["result"]:
    # Redirect user to data["redirect_url"]
    redirect_url = data["redirect_url"]
else:
    error = data["error_code"]

invoice/hold — Hold Funds

Initiates the first step of a two-step payment. Blocks (holds) funds on the payer's account without charging them immediately. Use invoice/charge to capture or invoice/unhold to release.

Request parameters are identical to invoice/create. Contact your account manager to confirm which payment methods support two-step flow.

invoice/charge — Capture Held Funds

Completes the second step of a two-step payment by capturing previously held funds. Must be called after a successful invoice/hold.

invoice/unhold — Release Held Funds

Cancels a previously held payment and returns the funds to the payer. Must be called after a successful invoice/hold and before invoice/charge.

Request parameters are the same as invoice/charge.

Webhook Notifications

After each significant payment event, RubitPay sends an HTTP POST notification to your configured callback URL. Your server must respond with HTTP 200 to acknowledge receipt.

Notification Payload Fields

Error Codes

When result: false is returned, the error_code field indicates the type of error. Errors fall into two categories:

• Fatal errors — Communication with the API should stop and the user should be informed of payment failure.
• Non-fatal errors — Wait for a server notification; the payment may still resolve successfully.

Supported Currencies

Sandbox Environment

A full sandbox environment is available for testing your integration before going live. All API methods are supported in sandbox mode.

# Sandbox base URL
https://sandbox.api.rubitpay.com

# Use test credentials provided by your account manager
# Sandbox transactions do not process real funds