Güncel Kur $ USD 47,20 ₺ € EUR 53,91 ₺ £ GBP 63,48 ₺
Anasayfa/Geliştirici API
Geliştirici

Tahsilatı kendi sistemine entegre et

buluttahsil REST API'si ile arka planından ödeme oluştur, müşteriyi güvenli ödeme sayfasına yönlendir ve sonucu sunucu tarafında teyit et. İstekler form-encoded, yanıtlar JSON.

Başlarken

Tüm uçlar tek bir taban adres altında çalışır. İstekler application/x-www-form-urlencoded gövdeyle POST edilir; yanıtlar JSON döner.

BASEhttps://api.sanalpos.org
Taban adres ve API anahtarınız (api_key), hesabınız açıldığında size özel olarak verilir. Yukarıdaki adres yalnızca örnektir.

Kimlik doğrulama

Her istek, Authorization başlığında API anahtarınızı taşımalıdır. Anahtar doğrudan gönderilir (Bearer öneki yoktur). Anahtar hesabınıza (kiracı) özeldir; yalnızca kendi tahsilatlarınıza erişir.

HTTP başlığı
Authorization: API_ANAHTARINIZ
Content-Type: application/x-www-form-urlencoded
API anahtarını yalnızca sunucu tarafında sakla ve kullan. Tarayıcı/mobil istemciye asla gömme.

Ödeme oluştur

Bir tahsilat kaydı oluşturur ve size benzersiz bir pay_code döner. Müşteriyi bu pay_code ile ödeme sayfasına yönlendirirsiniz.

POST/paylink/paycreate

Parametreler

AlanTipAçıklama
customer_name zorunlustringMüşteri adı soyadı.
email zorunlustringMüşteri e-posta adresi.
amount zorunludecimalTutar, ana birim (örn. 1500.00 = 1.500 TL).
currency zorunlustringPara birimi: id (1), kod (TRY), kısa kod (TL) veya sembol ().
payment_type zorunluint1 = canlı, 2 = test (banka test ortamı).
3d zorunluint1 = 3D Secure ile (önerilir), 0 = 3D'siz (yalnızca anlaşmanıza bağlı).
lang zorunlustringÖdeme sayfası dili (tr, en…).
company_name opsiyonelstringMüşterinin firma adı (ödeme sayfasında görünür).
mobile_no opsiyonelstringMüşteri cep telefonu.
message opsiyonelstringÖdeme sayfasında gösterilecek açıklama.
pay_finish_date opsiyoneldatetimeSon ödeme tarihi (Y-m-d H:i:s). Varsayılan: +1 gün.
efatura_company_id opsiyonelinte-Fatura alıcı firma kaydı id'si.
efatura_products opsiyoneljsone-Fatura kalemleri (JSON).
İstek örneği — dili seç, tüm örnekler değişir
curl -X POST https://api.sanalpos.org/paylink/paycreate \
  -H "Authorization: API_ANAHTARINIZ" \
  -d "customer_name=Ahmet Yılmaz" \
  -d "[email protected]" \
  -d "amount=1500.00" \
  -d "currency=TRY" \
  -d "payment_type=1" \
  -d "3d=1" \
  -d "lang=tr"
<?php
$ch = curl_init("https://api.sanalpos.org/paylink/paycreate");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => ["Authorization: API_ANAHTARINIZ"],
  CURLOPT_POSTFIELDS     => http_build_query([
    "customer_name" => "Ahmet Yılmaz",
    "email"         => "[email protected]",
    "amount"        => "1500.00",
    "currency"      => "TRY",
    "payment_type"  => 1,
    "3d"            => 1,
    "lang"          => "tr",
  ]),
]);
$res = json_decode(curl_exec($ch), true);
$payCode = $res["pay_code"]; // pay_code ile müşteriyi ödeme sayfasına yönlendir
import requests

r = requests.post("https://api.sanalpos.org/paylink/paycreate",
    headers={"Authorization": "API_ANAHTARINIZ"},
    data={
        "customer_name": "Ahmet Yılmaz",
        "email": "[email protected]",
        "amount": "1500.00",
        "currency": "TRY",
        "payment_type": 1,
        "3d": 1,
        "lang": "tr",
    })
res = r.json()
pay_code = res["pay_code"]
const body = new URLSearchParams({
  customer_name: "Ahmet Yılmaz",
  email: "[email protected]",
  amount: "1500.00",
  currency: "TRY",
  payment_type: "1",
  "3d": "1",
  lang: "tr",
});
const r = await fetch("https://api.sanalpos.org/paylink/paycreate", {
  method: "POST",
  headers: { Authorization: "API_ANAHTARINIZ" },
  body,
});
const res = await r.json();
const payCode = res.pay_code;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "API_ANAHTARINIZ");
var form = new FormUrlEncodedContent(new Dictionary<string, string> {
    ["customer_name"] = "Ahmet Yılmaz",
    ["email"]         = "[email protected]",
    ["amount"]        = "1500.00",
    ["currency"]      = "TRY",
    ["payment_type"]  = "1",
    ["3d"]            = "1",
    ["lang"]          = "tr",
});
var resp = await client.PostAsync("https://api.sanalpos.org/paylink/paycreate", form);
var json = await resp.Content.ReadAsStringAsync();
var client = HttpClient.newHttpClient();
var body = "customer_name=Ahmet Yılmaz&[email protected]"
         + "&amount=1500.00&currency=TRY&payment_type=1&3d=1&lang=tr";
var req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sanalpos.org/paylink/paycreate"))
    .header("Authorization", "API_ANAHTARINIZ")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
var res = client.send(req, HttpResponse.BodyHandlers.ofString());
Yanıt — başarılı
{
  "status": true,
  "pay_code": "1721030400aB3xZ9kLmN",
  "pay_id": 12345
}
Yanıt — hata
{
  "status": false,
  "message": "Geçersiz currency: 'XXX'. Kabul edilen: id (1), kod (TRY), kısa-kod (TL)."
}

Durum sorgula

Bir tahsilatın güncel durumunu sunucu tarafında sorgular. Siparişi/rezervasyonu onaylamadan önce ödemenin gerçekten alındığını bu uçla teyit edin.

POST/paylink/status

Parametreler

AlanTipAçıklama
pay_code zorunlustringpaycreate'ten dönen ödeme kodu.
İstek örneği
curl -X POST https://api.sanalpos.org/paylink/status \
  -H "Authorization: API_ANAHTARINIZ" \
  -d "pay_code=1721030400aB3xZ9kLmN"
<?php
$ch = curl_init("https://api.sanalpos.org/paylink/status");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => ["Authorization: API_ANAHTARINIZ"],
  CURLOPT_POSTFIELDS     => http_build_query(["pay_code" => "1721030400aB3xZ9kLmN"]),
]);
$res = json_decode(curl_exec($ch), true);
if ($res["paid"]) { /* ödeme teyitli → siparişi onayla */ }
import requests

res = requests.post("https://api.sanalpos.org/paylink/status",
    headers={"Authorization": "API_ANAHTARINIZ"},
    data={"pay_code": "1721030400aB3xZ9kLmN"}).json()

if res["paid"]:
    ...  # ödeme teyitli → siparişi onayla
const r = await fetch("https://api.sanalpos.org/paylink/status", {
  method: "POST",
  headers: { Authorization: "API_ANAHTARINIZ" },
  body: new URLSearchParams({ pay_code: "1721030400aB3xZ9kLmN" }),
});
const res = await r.json();
if (res.paid) { /* ödeme teyitli → siparişi onayla */ }
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "API_ANAHTARINIZ");
var form = new FormUrlEncodedContent(new Dictionary<string, string> {
    ["pay_code"] = "1721030400aB3xZ9kLmN",
});
var json = await (await client.PostAsync("https://api.sanalpos.org/paylink/status", form)).Content.ReadAsStringAsync();
var req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sanalpos.org/paylink/status"))
    .header("Authorization", "API_ANAHTARINIZ")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(HttpRequest.BodyPublishers.ofString("pay_code=1721030400aB3xZ9kLmN"))
    .build();
var res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
Yanıt
{
  "status": true,
  "paid": true,               // ödeme alındı mı (status == 3)
  "payment_status": "3",      // aşağıdaki durum kodları
  "amount": "1500.00",
  "provision_no": "...",      // banka provizyon no
  "result_status": "success",
  "bank_proc_code": "00",     // 00 = onay
  "date": "2026-07-18 12:30:00"
}
Güvenlik: Müşteri ödeme sonrası sitenize geri döndüğünde URL'deki durum bilgisine güvenmeyin (manipüle edilebilir). Siparişi kapatmadan önce her zaman bu uçla sunucu tarafında teyit edin.

Para birimleri

Desteklenen para birimlerini listeler. paycreate'te currency alanı için id/kod kullanabilirsiniz.

POST/paylink/currencies
cURL
curl -X POST https://api.sanalpos.org/paylink/currencies \
  -H "Authorization: API_ANAHTARINIZ"
Yanıt
[
  { "id": 1, "code": "TRY", "code_short": "TL", "symbol": "₺" },
  { "id": 2, "code": "USD", "code_short": "US", "symbol": "$" },
  { "id": 3, "code": "EUR", "code_short": "EU", "symbol": "€" }
]

İptal et

Henüz ödenmemiş bir tahsilat kaydını iptal eder (durum → 7).

POST/paylink/cancel

Parametreler

AlanTipAçıklama
pay_id zorunluintpaycreate'ten dönen pay_id.
Yanıt
{
  "status": true,
  "pay_id": 12345,
  "message": "12345 id li kayıt iptal edilmiştir.",
  "date": "2026-07-18 12:35"
}

Ödeme durum kodları

payment_status alanı aşağıdaki değerleri alır:

KodDurumAçıklama
1TaslakKayıt oluşturuldu, henüz işleme alınmadı.
2Ödeme BekleniyorMüşteri ödeme sayfasına yönlendirilebilir.
3Ödeme AlındıKart ödemesi başarıyla tamamlandı (paid = true).
4BaşarısızÖdeme reddedildi veya hata oluştu.
53D Onay Bekliyor3D Secure doğrulaması sürüyor.
6EFT / Havale ile ÖdendiBanka havalesi/EFT ile kapatıldı.
7İptalKayıt iptal edildi.

Entegrasyon akışı

Ödeme oluştur

Backend'inden /paylink/paycreate çağrısı yap, dönen pay_code ve pay_id'yi sakla.

Müşteriyi yönlendir

Müşteriyi pay_code ile güvenli ödeme sayfasına gönder. Kart bilgisi 3D Secure ile bankada toplanır; sizin sisteminizde kart verisi tutulmaz.

Sonucu teyit et

Müşteri geri döndüğünde /paylink/status ile sunucu tarafında ödemeyi doğrula (paid = true).

Siparişi kapat

Teyit alındıysa siparişi/rezervasyonu onayla. Dilersen e-Arşiv fatura otomatik kesilir.

Güvenlik

Entegrasyonun güvenli olması için aşağıdaki ilkeleri uygulayın:

Yalnızca HTTPS

Tüm istekler TLS (HTTPS) üzerinden yapılmalıdır. Şifresiz (http) istek kabul edilmez.

API anahtarını gizli tut

Anahtarı yalnızca sunucu tarafında sakla; tarayıcı, mobil uygulama veya herkese açık depoya (git) koyma. Sızması durumunda panelden anında yenile.

Sunucu tarafında teyit et

Ödemeyi her zaman /paylink/status ile doğrula. Müşterinin döndüğü sayfadaki URL bilgisine güvenme.

3D Secure kullan

3d=1 ile chargeback (ters ibraz) riskini düşür. Kart bilgisi sizde değil, banka tarafında toplanır — PCI yükü sizde olmaz.

Önce test et

Canlıya geçmeden payment_type=2 ile test ortamında (bankanın test kartlarıyla) tüm akışı doğrula.

e-Fatura (e-Arşiv)

Tahsilatla birlikte GİB e-Arşiv fatura akışı da API üzerinden yönetilebilir: taslak oluşturma, SMS onayı, kesilen faturayı indirme ve müşteriye e-posta ile gönderme. e-Fatura uçları ve entegrasyon detayları için bizimle iletişime geçin — kurumunuza özel akış birlikte planlanır.

e-Fatura entegrasyonu için yaz

Entegrasyona mı başlıyorsun?

API anahtarı, test ortamı ve teknik destek için ekibimiz yanında.

Bize yazın