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.
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.
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.
Authorization: API_ANAHTARINIZ Content-Type: application/x-www-form-urlencoded
Bir tahsilat kaydı oluşturur ve size benzersiz bir pay_code döner. Müşteriyi bu pay_code ile ödeme sayfasına yönlendirirsiniz.
| Alan | Tip | Açıklama |
|---|---|---|
customer_name zorunlu | string | Müşteri adı soyadı. |
email zorunlu | string | Müşteri e-posta adresi. |
amount zorunlu | decimal | Tutar, ana birim (örn. 1500.00 = 1.500 TL). |
currency zorunlu | string | Para birimi: id (1), kod (TRY), kısa kod (TL) veya sembol (₺). |
payment_type zorunlu | int | 1 = canlı, 2 = test (banka test ortamı). |
3d zorunlu | int | 1 = 3D Secure ile (önerilir), 0 = 3D'siz (yalnızca anlaşmanıza bağlı). |
lang zorunlu | string | Ödeme sayfası dili (tr, en…). |
company_name opsiyonel | string | Müşterinin firma adı (ödeme sayfasında görünür). |
mobile_no opsiyonel | string | Müşteri cep telefonu. |
message opsiyonel | string | Ödeme sayfasında gösterilecek açıklama. |
pay_finish_date opsiyonel | datetime | Son ödeme tarihi (Y-m-d H:i:s). Varsayılan: +1 gün. |
efatura_company_id opsiyonel | int | e-Fatura alıcı firma kaydı id'si. |
efatura_products opsiyonel | json | e-Fatura kalemleri (JSON). |
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¤cy=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());
{
"status": true,
"pay_code": "1721030400aB3xZ9kLmN",
"pay_id": 12345
}
{
"status": false,
"message": "Geçersiz currency: 'XXX'. Kabul edilen: id (1), kod (TRY), kısa-kod (TL)."
}
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.
| Alan | Tip | Açıklama |
|---|---|---|
pay_code zorunlu | string | paycreate'ten dönen ödeme kodu. |
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());
{
"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"
}
Desteklenen para birimlerini listeler. paycreate'te currency alanı için id/kod kullanabilirsiniz.
curl -X POST https://api.sanalpos.org/paylink/currencies \ -H "Authorization: API_ANAHTARINIZ"
[
{ "id": 1, "code": "TRY", "code_short": "TL", "symbol": "₺" },
{ "id": 2, "code": "USD", "code_short": "US", "symbol": "$" },
{ "id": 3, "code": "EUR", "code_short": "EU", "symbol": "€" }
]
Henüz ödenmemiş bir tahsilat kaydını iptal eder (durum → 7).
| Alan | Tip | Açıklama |
|---|---|---|
pay_id zorunlu | int | paycreate'ten dönen pay_id. |
{
"status": true,
"pay_id": 12345,
"message": "12345 id li kayıt iptal edilmiştir.",
"date": "2026-07-18 12:35"
}
payment_status alanı aşağıdaki değerleri alır:
| Kod | Durum | Açıklama |
|---|---|---|
| 1 | Taslak | Kayıt oluşturuldu, henüz işleme alınmadı. |
| 2 | Ödeme Bekleniyor | Müşteri ödeme sayfasına yönlendirilebilir. |
| 3 | Ödeme Alındı | Kart ödemesi başarıyla tamamlandı (paid = true). |
| 4 | Başarısız | Ödeme reddedildi veya hata oluştu. |
| 5 | 3D Onay Bekliyor | 3D Secure doğrulaması sürüyor. |
| 6 | EFT / Havale ile Ödendi | Banka havalesi/EFT ile kapatıldı. |
| 7 | İptal | Kayıt iptal edildi. |
Backend'inden /paylink/paycreate çağrısı yap, dönen pay_code ve pay_id'yi sakla.
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.
Müşteri geri döndüğünde /paylink/status ile sunucu tarafında ödemeyi doğrula (paid = true).
Teyit alındıysa siparişi/rezervasyonu onayla. Dilersen e-Arşiv fatura otomatik kesilir.
Entegrasyonun güvenli olması için aşağıdaki ilkeleri uygulayın:
Tüm istekler TLS (HTTPS) üzerinden yapılmalıdır. Şifresiz (http) istek kabul edilmez.
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.
Ödemeyi her zaman /paylink/status ile doğrula. Müşterinin döndüğü sayfadaki URL bilgisine güvenme.
3d=1 ile chargeback (ters ibraz) riskini düşür. Kart bilgisi sizde değil, banka tarafında toplanır — PCI yükü sizde olmaz.
Canlıya geçmeden payment_type=2 ile test ortamında (bankanın test kartlarıyla) tüm akışı doğrula.
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 yazAPI anahtarı, test ortamı ve teknik destek için ekibimiz yanında.