Hızlı başlangıç

Minimum bir ödeme entegrasyonu: API aracılığıyla fatura oluşturma ve ödeme bildirimini işleme. Son bölüm sipariş teslimini ele alır. Örnekler kendi içinde bütündür; SDK kullanılmaz.

ipucu

Bir yapay zekâ ajanıyla mı çalışıyorsunuz? Ona bu sayfanın markdown sürümünü verin. Siteniz veya mağazanız için bir entegrasyon kurmaya yetecek ayrıntıyı içerir.

Ön koşullar

Değer	Nereden alınır
API anahtarı (API key)	Entegrasyonlar (Integrations) bölümü
Proje ID'si (Project ID)	Projeler (Projects) bölümü
Webhook gizli anahtarı (Webhook secret)	Proje ayarları

Aynı proje ayarlarında Webhook URL'yi ayarlayın — sunucunuzdaki bildirim işleyicisinin adresi. Yalnızca HTTPS; yönlendirmeler izlenmez.

Örnekler test değerleri kullanır — bunları kendi değerlerinizle değiştirin.

Fatura oluşturma

POST https://api.bitsby.app/invoices/create, API anahtarı Authorization başlığında gönderilir.

Parametre	Zorunlu	Değer
`projectId`	evet	Proje ID'si, UUID
`amountFiat`	evet	Fatura tutarı
`currencyFiat`	evet	Para birimi: USD, EUR, RUB
`timeToPay`	evet	Saat cinsinden ödeme süresi: 0.5, 1, 3, 6, 12
`description`	hayır	Açıklama, ödeme sayfasında alıcıya gösterilir
`serviceData`	hayır	Hizmet verisi, alıcıya gösterilmez. Sipariş numarasını göndermenizi öneririz: ödeme bildiriminde geri gelir

cURL
PHP
TypeScript
JavaScript
Python

curl -X POST https://api.bitsby.app/invoices/create \
  -H "Authorization: Token MSvL2ltaDZdWVjmZURURMVWhqSJLT2NURjhL2Fla1Z1T1IxQTltKs1T3Ay" \
  -F "projectId=9deea1e2-0c08-41a3-bdc2-a34eada3892d" \
  -F "amountFiat=49.90" \
  -F "currencyFiat=USD" \
  -F "timeToPay=1" \
  -F "description=Order 4172" \
  -F "serviceData=order-4172"

<?php
$apiKey    = 'MSvL2ltaDZdWVjmZURURMVWhqSJLT2NURjhL2Fla1Z1T1IxQTltKs1T3Ay';
$projectId = '9deea1e2-0c08-41a3-bdc2-a34eada3892d';

$ch = curl_init('https://api.bitsby.app/invoices/create');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => ['Authorization: Token '.$apiKey],
    CURLOPT_POSTFIELDS     => http_build_query([
        'projectId'    => $projectId,
        'amountFiat'   => 49.90,
        'currencyFiat' => 'USD',
        'timeToPay'    => 1,
        'description'  => 'Order 4172',
        'serviceData'  => 'order-4172',  // your order id
    ]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['result'] !== 'success') {
    exit('API error: '.$response['data']);
}

$invoice = $response['data'];

// $invoice['id']  — invoice id, store it with the order
// $invoice['url'] — payment page for the customer

const API_KEY = 'MSvL2ltaDZdWVjmZURURMVWhqSJLT2NURjhL2Fla1Z1T1IxQTltKs1T3Ay';
const PROJECT_ID = '9deea1e2-0c08-41a3-bdc2-a34eada3892d';

interface Invoice {
    id: string;
    uid: string;
    url: string;
    timeToPayDatetime: string;
}

const response = await fetch('https://api.bitsby.app/invoices/create', {
    method: 'POST',
    headers: { Authorization: `Token ${API_KEY}` },
    body: new URLSearchParams({
        projectId: PROJECT_ID,
        amountFiat: '49.90',
        currencyFiat: 'USD',
        timeToPay: '1',
        description: 'Order 4172',
        serviceData: 'order-4172',  // your order id
    }),
    signal: AbortSignal.timeout(10_000),
});

const result: { result: string; data: Invoice | string } = await response.json();

if (result.result !== 'success') {
    throw new Error(`API error: ${result.data}`);
}

const invoice = result.data as Invoice;

// invoice.id  — invoice id, store it with the order
// invoice.url — payment page for the customer

const API_KEY = 'MSvL2ltaDZdWVjmZURURMVWhqSJLT2NURjhL2Fla1Z1T1IxQTltKs1T3Ay';
const PROJECT_ID = '9deea1e2-0c08-41a3-bdc2-a34eada3892d';

const response = await fetch('https://api.bitsby.app/invoices/create', {
    method: 'POST',
    headers: { Authorization: `Token ${API_KEY}` },
    body: new URLSearchParams({
        projectId: PROJECT_ID,
        amountFiat: '49.90',
        currencyFiat: 'USD',
        timeToPay: '1',
        description: 'Order 4172',
        serviceData: 'order-4172',  // your order id
    }),
    signal: AbortSignal.timeout(10_000),
});

const result = await response.json();

if (result.result !== 'success') {
    throw new Error(`API error: ${result.data}`);
}

const invoice = result.data;

// invoice.id  — invoice id, store it with the order
// invoice.url — payment page for the customer

import requests

API_KEY = 'MSvL2ltaDZdWVjmZURURMVWhqSJLT2NURjhL2Fla1Z1T1IxQTltKs1T3Ay'
PROJECT_ID = '9deea1e2-0c08-41a3-bdc2-a34eada3892d'

response = requests.post(
    'https://api.bitsby.app/invoices/create',
    headers={'Authorization': f'Token {API_KEY}'},
    data={
        'projectId': PROJECT_ID,
        'amountFiat': '49.90',
        'currencyFiat': 'USD',
        'timeToPay': '1',
        'description': 'Order 4172',
        'serviceData': 'order-4172',  # your order id
    },
    timeout=10,
)

result = response.json()

if result['result'] != 'success':
    raise RuntimeError(f"API error: {result['data']}")

invoice = result['data']

# invoice['id']  — invoice id, store it with the order
# invoice['url'] — payment page for the customer

Yanıt:

{
  "result": "success",
  "data": {
    "id": "ade9550d-3dc7-4fd3-b94e-3b4c12aaaa0c",
    "uid": "MXNj4m8HhcM4",
    "createDatetime": "2026-09-14 10:12:03",
    "timeToPayDatetime": "2026-09-14 11:12:03",
    "commissionFiatUSD": 0.5,
    "amountFiatUSD": 49.9,
    "url": "https://dash.bitsby.app/invoices/pay/MXNj4m8HhcM4"
  }
}

data.id değerini siparişle birlikte saklayın ve alıcıyı data.url adresine — ödeme sayfasına gönderin. Bağlantıyı istediğiniz şekilde iletin: yönlendirme, e-posta, bot mesajı. Fatura, timeToPayDatetime (UTC) zamanına kadar geçerlidir.

Bildirimi işleme

Bir fatura Ödendi (Paid) durumuna geçtiğinde hizmet, projenin Webhook URL'sine bir POST isteği gönderir. Gövde JSON'dur; imza başlıklardadır:

Başlık	Değer
`X-Timestamp`	Gönderim zamanı, saniye cinsinden unix time
`X-Signature`	`sha256=` + `<timestamp>.<request body>` dizesinin hex HMAC-SHA256 değeri

İmzalama anahtarı, webhook gizli anahtarıdır. İmza ham istek gövdesi üzerinden hesaplanır, bu nedenle JSON'u ayrıştırmadan önce imzayı doğrulayın.

PHP
TypeScript
JavaScript
Python

<?php
$secret = 'k7QwR2mZ9tXbN4vL8sJpH3dF6yA1cE0u';

$body      = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// Reject replayed requests: allow up to 5 minutes of clock drift
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(400);
    exit;
}

$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$body, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit;
}

$invoice = json_decode($body, true)['invoice'];

if ($invoice['status'] === 'paid') {
    // $invoice['serviceData'] — the order id passed at creation: 'order-4172'
    // $invoice['amountFiat']  — the original invoice amount: 49.9
    // Issue the order here, see the next section
}

http_response_code(200);

import { createHmac, timingSafeEqual } from 'node:crypto';
import express, { type Request, type Response } from 'express';

const SECRET = 'k7QwR2mZ9tXbN4vL8sJpH3dF6yA1cE0u';
const app = express();

// express.raw: the signature is computed over the raw request body
app.post('/webhook', express.raw({ type: 'application/json' }), (req: Request, res: Response) => {
    const timestamp = req.get('X-Timestamp') ?? '';
    const signature = req.get('X-Signature') ?? '';
    const body = (req.body as Buffer).toString('utf8');

    // Reject replayed requests: allow up to 5 minutes of clock drift
    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
        return res.sendStatus(400);
    }

    const expected = 'sha256=' + createHmac('sha256', SECRET)
        .update(`${timestamp}.${body}`, 'utf8')
        .digest('hex');

    const a = Buffer.from(expected);
    const b = Buffer.from(signature);

    if (a.length !== b.length || !timingSafeEqual(a, b)) {
        return res.sendStatus(403);
    }

    const { invoice } = JSON.parse(body);

    if (invoice.status === 'paid') {
        // invoice.serviceData — the order id passed at creation: 'order-4172'
        // invoice.amountFiat  — the original invoice amount: 49.9
        // Issue the order here, see the next section
    }

    res.sendStatus(200);
});

app.listen(8080);

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const SECRET = 'k7QwR2mZ9tXbN4vL8sJpH3dF6yA1cE0u';
const app = express();

// express.raw: the signature is computed over the raw request body
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const timestamp = req.get('X-Timestamp') ?? '';
    const signature = req.get('X-Signature') ?? '';
    const body = req.body.toString('utf8');

    // Reject replayed requests: allow up to 5 minutes of clock drift
    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
        return res.sendStatus(400);
    }

    const expected = 'sha256=' + createHmac('sha256', SECRET)
        .update(`${timestamp}.${body}`, 'utf8')
        .digest('hex');

    const a = Buffer.from(expected);
    const b = Buffer.from(signature);

    if (a.length !== b.length || !timingSafeEqual(a, b)) {
        return res.sendStatus(403);
    }

    const { invoice } = JSON.parse(body);

    if (invoice.status === 'paid') {
        // invoice.serviceData — the order id passed at creation: 'order-4172'
        // invoice.amountFiat  — the original invoice amount: 49.9
        // Issue the order here, see the next section
    }

    res.sendStatus(200);
});

app.listen(8080);

import hashlib
import hmac
import time

from flask import Flask, request

SECRET = 'k7QwR2mZ9tXbN4vL8sJpH3dF6yA1cE0u'
app = Flask(__name__)


@app.post('/webhook')
def webhook():
    timestamp = request.headers.get('X-Timestamp', '')
    signature = request.headers.get('X-Signature', '')
    # The signature is computed over the raw request body
    body = request.get_data(as_text=True)

    # Reject replayed requests: allow up to 5 minutes of clock drift
    if abs(time.time() - int(timestamp or 0)) > 300:
        return '', 400

    expected = 'sha256=' + hmac.new(
        SECRET.encode(),
        f'{timestamp}.{body}'.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return '', 403

    invoice = request.get_json()['invoice']

    if invoice['status'] == 'paid':
        # invoice['serviceData'] — the order id passed at creation: 'order-4172'
        # invoice['amountFiat']  — the original invoice amount: 49.9
        # Issue the order here, see the next section
        pass

    return '', 200

10 saniye içinde 2xx koduyla yanıt verin. Başka bir kod, yönlendirme veya zaman aşımı başarısız teslimat sayılır: hizmet, 5 dakikadan 24 saate kadar artan aralıklarla yeniden dener, sonra durur. Uzun işlemleri bir kuyruğa aktarın: önce 200 ile yanıt verin, siparişi sonra işleyin.

Bildirim biçiminin tamamı ve alan referansı Webhook URL bölümündedir.

Sipariş teslimi

Durumu paid olan doğrulanmış bir bildirim, ödemeyi onaylar. Teslim adımları:

invoice.serviceData ile siparişi bulun — fatura oluşturulurken gönderilen değer (order-4172).
invoice.id ile bu faturanın daha önce teslim edilip edilmediğini kontrol edin. Aynı invoice.id ile bildirim birden fazla kez gelebilir — siparişi bir kez teslim edin ve işlendi işaretini saklayın.
invoice.amountFiat ve invoice.currencyFiat ile tutarı ve para birimini doğrulayın — bunlar faturanın orijinal değerleridir ve asla değişmez. amountFiatUSD değerinin üzerine fiilen alınan tutar yazılır. Tutarları dize olarak değil sayı olarak karşılaştırın: sondaki sıfırlar atılır, bu yüzden 49.90 değeri 49.9 olarak gelir. Değerler siparişle uyuşmuyorsa faturayı teslim yerine manuel incelemeye yönlendirin — bu tür durumlar Ödeme eşleştirme ve tutar uyuşmazlıkları sayfasında ele alınır.
Siparişi teslim edin ve işlendi olarak işaretleyin.

Teslim sırasında ödeme süresini kontrol etmeyin: ödeme, timeToPayDatetime zamanından sonra on-chain onaylanmış olabilir ve satıcı bir ödemeyi faturayla manuel olarak eşleştirebilir. Bildirimin kendisi ödemeyi onaylar.

Sırada ne var

API referansı — fatura listeleri, iptal, istatistikler, bakiyeler
Webhook imzası doğrulama — imza mekanizması ayrıntılarıyla
Ödeme eşleştirme ve tutar uyuşmazlıkları — eksik ödeme, fazla ödeme, eşleşmemiş ödemeler
HTML formları — API olmadan ödeme alma

Ön koşullar​

Fatura oluşturma​

Bildirimi işleme​

Sipariş teslimi​

Sırada ne var​

Ön koşullar

Fatura oluşturma

Bildirimi işleme

Sipariş teslimi

Sırada ne var