Postapos API Dökümantasyonu

Postapos, işletmenizin tüm tahsilat süreçlerini tek noktadan yönetebileceğiniz, bulut tabanlı bir sanal POS ve ödeme platformudur. Farklı bankaların sanal poslarını tek çatı altında toplar; kredi kartı, taksitli satış ve linkle ödeme gibi yöntemlerle tahsilatlarınızı hızlandırır, finansal süreçlerinizi güvenle kontrol altında tutar.

Kredi kartı ödemeleri, taksitli satışlar, ödeme linki, hızlı tahsilat, müşteri (bayi) yönetimi ve detaylı raporlama işlemlerinin tümünü tek panelden yürütürsünüz.

Postapos ile Neler Yapabilirsiniz?

Birden çok bankanın sanal posunu tek çatı altında yönetin.

Peşin ve taksitli ödeme seçenekleri sunun.

Linkle (barındırılan) ödeme ile uzaktan güvenle tahsilat alın.

Otomatik mutabakat ve detaylı raporlarla finansı izleyin.

Güvenli, hızlı ve kesintisiz ödeme altyapısından yararlanın.

Postapos API Nedir?

Postapos API, tahsilat çözümlerini kendi sistemlerinize (e‑ticaret, ERP, CRM) sorunsuz entegre etmeniz için geliştirilmiş bir REST arayüzüdür. Ödeme linki oluşturma, taksit sorgulama, ödeme başlatma ve işlem sorgulama gibi işlemleri programatik olarak gerçekleştirir; finansal süreçlerinizi otomatikleştirerek güvenli ve kesintisiz yönetmenizi sağlar.

API entegrasyonu hakkında destek için destek@postapos.com adresine yazabilirsiniz.
Postapos Destek Ekibi

Postapos API ile tahsilat altyapınızı kendi sisteminize (e‑ticaret, ERP, CRM) bağlarsınız: ödeme linki üretir, taksit sorgular, ödeme başlatır ve işlemlerinizi sorgularsınız. REST, JSON ve HTTPS üzerinden çalışır.

Base URL

https://{sunucu}.postapos.com/api/v1

Kimlik Doğrulama

Bearer API anahtarı

Güvenlik

IP kısıtı zorunlu · HTTPS

Yanıt Formatı

JSON · data / error

curl https://{sunucu}.postapos.com/api/v1/me \
  -H "Authorization: Bearer postapos_live_xxxxxxxxxxxxxxxx"

Her istek bir API anahtarı ile kimlik doğrular. Anahtarı panelden Genel Ayarlar › API Entegrasyon'dan üretirsiniz; yalnız oluşturmada bir kez gösterilir.

Anahtarı her istekte Authorization başlığında Bearer olarak gönderin. Anahtarın kapsamı (firma / müşteri) onu üreten yere göre otomatik belirlenir.

GET/me FirmaMüşteri

İstek

curl https://{sunucu}.postapos.com/api/v1/me \
  -H "Authorization: Bearer postapos_live_xxxxxxxxxxxxxxxx"

Yanıt · 200

{
  "data": {
    "scope": "firma",
    "firma": { "name": "Örnek Firma A.Ş." },
    "key": {
      "name": "Muhasebe entegrasyonu",
      "ip_whitelist": ["88.240.0.0/16"],
      "created_at": "2026-09-28T10:00:00+00:00",
      "last_used_at": "2026-09-28T12:00:00+00:00"
    }
  }
}

Anahtarınızı sunucu tarafında saklayın; tarayıcı/mobil istemciye gömmeyin. Sızarsa API Entegrasyon › Yenile ile iptal edin.

Çağıranın kendi kurumsal bilgilerini döner. Firma anahtarı firma bilgilerini (marka dahil: logo, favicon); müşteri anahtarı yalnız kendi bayi bilgilerini görür — firmanın verisini göremez.

GET/company FirmaMüşteri

Parametre almaz. Müşteri kapsamında slug, logo, favicon, site_title alanları dönmez (bunlar firmaya özeldir).

Yanıt

{
  "data": {
    "name": "Örnek Firma A.Ş.",
    "site_title": "Örnek Tahsilat",
    "slug": "ornek",
    "email": "info@ornek.com",
    "phone": "0216 000 00 00",
    "address": "…",
    "tax_office": "…",
    "tax_number": "1234567890",
    "province": "İstanbul", "district": "Kadıköy",
    "logo": "https://{sunucu}.postapos.com/cdn/…",
    "favicon": "https://{sunucu}.postapos.com/cdn/…",
    "contact": { "name": "Ad Soyad", "email": "yetkili@ornek.com", "phone": "05xx xxx xx xx" },
    "is_active": true,
    "created_at": "2026-09-28T10:00:00+00:00"
  }
}

Her API anahtarı IP kısıtlıdır. Anahtar yalnız beyaz listedeki IP adreslerinden gelen isteklerde çalışır.

İzinli IP'leri (IPv4, IPv6 veya CIDR) anahtarı oluştururken belirlersiniz. Beyaz liste dışından gelen istek 403 ip_forbidden ile reddedilir.

{
  "error": { "code": "ip_forbidden", "message": "İstek IP adresi bu anahtar için izinli değil." }
}

Hatalar uygun HTTP durum kodu ve bir error nesnesiyle döner.

{
  "error": { "code": "validation_error", "message": "amount alanı zorunludur." }
}

HTTP	code	Açıklama
401	unauthorized	Anahtar eksik ya da geçersiz.
403	ip_forbidden	İstek IP'si beyaz listede değil.
403	key_inactive	Anahtar askıda ya da süresi dolmuş.
403	package_required	API için Profesyonel paket ya da Web Servis (API) modülü gerekir.
404	not_found	Kayıt yok ya da kapsamınız dışında.
422	validation_error	Gönderilen alanlar geçersiz.
429	rate_limited	İstek limiti aşıldı.

İstekler anahtar başına dakikalık olarak sınırlıdır. Limit aşılırsa 429 rate_limited döner.

Kalan hakkınızı yanıt başlıklarından takip edebilirsiniz:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
Retry-After: 12

Hazır entegrasyon paketleri ve örnek kodlar. İndirip kendi sisteminize uyarlayabilirsiniz.

RAR PHP Entegrasyon Paketi Postapos Api - Php.rar · 4 KB ZIP WooCommerce Eklentisi (WordPress) postapos-woocommerce.zip · 13 KB

Tutar ve opsiyonel bilgilerle bir ödeme linki üretir. Kart sahibi bu linkte 3D Secure ile öder; API kart bilgisi almaz, PCI yükü tarafınıza geçmez.

POST/payment-links FirmaMüşteri

Gövde parametreleri

Parametre	Tip	Zorunlu	Açıklama
amount	number	Zorunlu	Tahsilat tutarı (TL).
payer_name	string	Zorunlu	Ödeyen adı / ünvan.
description	string	Zorunlu	İşlem açıklaması / referans.
installments	array	Opsiyonel	İzinli taksitler, ör. [1,3,6]. Boşsa tek çekim.
dealer_id	integer	Opsiyonel	Linki bağlayacağınız müşteri.
commission_mode	integer	Opsiyonel	1 = komisyon hariç · 2 = dahil (varsayılan 1).
expires_at	date	Opsiyonel	Son geçerlilik. Boşsa +7 gün.
recipient_email	string	Opsiyonel	Verilirse link e-posta ile gönderilir.
recipient_phone	string	Opsiyonel	Verilirse link SMS ile gönderilir.

İstek

curl -X POST https://{sunucu}.postapos.com/api/v1/payment-links \
  -H "Authorization: Bearer postapos_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500.00,
    "payer_name": "Ahmet Yılmaz",
    "description": "Sipariş #1024",
    "installments": [1, 3, 6]
  }'

Yanıt · 200

{
  "data": {
    "code": "AB12CD",
    "url": "https://{sunucu}.postapos.com/odeme/AB12CD",
    "status": "active",
    "amount": 1500.00,
    "expires_at": "2026-10-05",
    "dealer_id": null,
    "sent": []
  }
}

Önerilen akış budur — kart verisi sizde tutulmaz, 3D Secure Postapos tarafında tamamlanır.

Bir ödeme linkinin durumunu ve (ödendiyse) ödeme sonucunu döner. code = POST /payment-links yanıtındaki koddur. Linki oluşturduktan sonra "ödendi mi?" diye bunu yoklarsınız. Müşteri yalnız kendi linkini görür; yoksa 404 not_found.

GET/payment-links/{code} FirmaMüşteri

Yol parametresi

Parametre	Tip	Zorunlu	Açıklama
code	string	Zorunlu	Ödeme linki kodu (POST /payment-links yanıtındaki code).

Yanıt

{
  "data": {
    "code": "AB12CD",
    "status": "paid",          // active | paid | expired | canceled
    "paid": true,
    "amount": 1500.00,
    "url": "https://{sunucu}.postapos.com/odeme/AB12CD",
    "description": "Sipariş #1024",
    "expires_at": "2026-10-05",
    "payment": {               // ödendiyse dolu; değilse null
      "id": "9F1C2A…",
      "process_no": "P260928ABC123",
      "status": "success",
      "total_amount": 1575.00,
      "installment": 3,
      "card": { "masked": "454671******1234", "bank": "Yapı Kredi" },
      "created_at": "2026-09-28T13:20:00+00:00"
    }
  }
}

paid: true ise siparişinizi tamamlayın. payment yalnız ödendiğinde dolar.

Durum değerleri

status	Açıklama
active	Link aktif, henüz ödenmedi.
paid	Ödeme tamamlandı; payment alanı doludur.
expired	Son geçerlilik tarihi geçti, artık ödenemez.
canceled	Link iptal edildi.

İleri seviye: kartı kendi arayüzünüzde toplayıp ödemeyi başlatırsınız. Önce GET /installments ile seçenek alın, option olarak buradaki id'yi gönderin. Yanıt olarak 3D yönlendirme adresi döner; kullanıcıyı oraya yönlendirin. Ham kart aldığınız için PCI‑DSS sorumluluğu tarafınıza geçer.

POST/payments FirmaMüşteri

Gövde parametreleri

Parametre	Tip	Zorunlu	Açıklama
option	string	Zorunlu	/installments seçeneğinin id'si (Pos + taksit).
amount	number	Zorunlu	Tutar (TL) — /installments ile aynı.
card_holder	string	Zorunlu	Kart sahibi ad soyad.
card_number	string	Zorunlu	Kart numarası.
expiry	string	Zorunlu	AA/YY.
cvv	string	Zorunlu	Güvenlik kodu (saklanmaz).
return_url	string	Zorunlu	Sonuç buraya döner (https zorunlu).
commission_mode	integer	Opsiyonel	1 = hariç · 2 = dahil (varsayılan 1).
dealer_id	integer	Opsiyonel	Ödemeyi bağlayacağınız müşteri.
description	string	Opsiyonel	Açıklama / referans.

İstek

curl -X POST https://{sunucu}.postapos.com/api/v1/payments \
  -H "Authorization: Bearer postapos_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "option": "a1b2c3d4",
    "amount": 1575.00,
    "card_holder": "AHMET YILMAZ",
    "card_number": "5400000000000000",
    "expiry": "12/28",
    "cvv": "000",
    "return_url": "https://magaza.com/odeme/sonuc"
  }'

Yanıt · 200

{
  "data": {
    "id": "9F1C2A…",
    "process_no": "P260928ABC123",
    "status": "pending_3d",
    "redirect_url": "https://{sunucu}.postapos.com/odeme/3d/9F1C2A…"
  }
}

Kullanıcı 3D'yi tamamlayınca sonuç return_url'e POST edilir — bkz. Ödeme Sonucu.

Mümkünse /payment-links kullanın — ham kart almadan, PCI yükü olmadan tahsilat yaparsınız.

Kullanıcı 3D doğrulamayı tamamlayınca ödeme sonucunu, POST /payments çağrısında verdiğiniz return_url adresine POST (form-encoded) ile göndeririz. Tarayıcı otomatik yönlendirir; sonuç sayfanızda kullanıcıya gösterirsiniz.

Gönderilen alanlar

status=success               # success | failed
id=9F1C2A…                   # tahsilat guid → GET /payments/{id}
process_no=P260928ABC123
amount=1575.00
card=454671******1234
message=                     # başarısızsa banka/hata mesajı
signature=3b7f8c…            # HMAC-SHA256

İmza doğrulama

Bildirimin gerçekten bizden geldiğini doğrulamak için imzayı yeniden hesaplayın:

secret    = sha256(API_ANAHTARINIZ)
beklenen  = HMAC_SHA256("{id}|{process_no}|{status}|{amount}", secret)
gecerli   = (beklenen === signature)

beklenen ile gelen signature aynıysa bildirim geçerlidir. Ayrıca kesin durum için her zaman GET /payments/{id} (id = guid) ile sorgulayabilirsiniz — tarayıcı kapanırsa yedek budur.

Sipariş/stok gibi kritik işlemleri yalnız imzayı doğruladıktan (veya GET /payments/{id} ile teyit ettikten) sonra tamamlayın.

Kart BIN'i ve tutara göre uygun taksit seçeneklerini döner: her seçenek için çekilecek tutar, aylık ödeme ve komisyon. Müşteri Kuralları (izinli taksit + maksimum tutar) otomatik uygulanır. Her seçeneğin id'si POST /payments çağrısında kullanılır.

GET/installments FirmaMüşteri

Sorgu parametreleri

Parametre	Tip	Zorunlu	Açıklama
bin	string	Zorunlu	Kartın ilk 6-8 hanesi.
amount	number	Zorunlu	Tutar (TL).
commission_mode	integer	Opsiyonel	1 = komisyon hariç · 2 = dahil (varsayılan 1).
dealer_id	integer	Opsiyonel	Müşteri Kurallarının uygulanacağı müşteri.

Yanıt

{
  "data": {
    "card": { "bin": "454671", "bank": "Yapı Kredi", "brand": "VISA", "program": "World", "program_logo": "https://{sunucu}.postapos.com/cdn/…", "type": "credit" },
    "options": [
      { "id": "9F3KQ7ZB2MX", "installment": 1, "charged_amount": 1500.00, "monthly": 1500.00, "commission_rate": 0.00, "commission_amount": 0.00 },
      { "id": "K2P8XQ4ZC1N", "installment": 3, "charged_amount": 1575.00, "monthly": 525.00, "commission_rate": 5.00, "commission_amount": 75.00 }
    ]
  }
}

Tahsilatları kapsamlı olarak listeler: tutar, komisyon, kart (banka/program/tip), taksit, kanal, müşteri ve durum. Kapsama göre: firma tüm tahsilatlarını; müşteri yalnız kendi ve alt bayilerinin tahsilatlarını görür. Müşteri kapsamında komisyon, pos ve müşterinin etn_code / custom1 / custom2 alanları dönmez (bunlar yalnız firma kapsamında gelir).

GET/payments FirmaMüşteri

Sorgu parametreleri

Parametre	Tip	Zorunlu	Açıklama
status	string	Opsiyonel	success · failed · canceled · refunded.
bank	string	Opsiyonel	Kart bankası adı.
card_type	string	Opsiyonel	credit · debit.
installment	integer	Opsiyonel	Taksit sayısı (1 = tek çekim).
dealer_id	integer	Opsiyonel	Belirli bir müşterinin tahsilatları.
from / to	date	Opsiyonel	Tarih aralığı (created_at).
search	string	Opsiyonel	İşlem no, kart sahibi, kart no ya da banka.
limit	integer	Opsiyonel	Sayfa boyutu (1–100, varsayılan 25).
cursor	string	Opsiyonel	Sonraki sayfa için meta.next_cursor.

Yanıt

{
  "data": [
    {
      "id": "9f1c2a…",
      "process_no": "P260928ABC123",
      "status": "success",
      "status_message": null,
      "channel": "poslink",
      "created_at": "2026-09-28T13:20:00+00:00",
      "amount": 1500.00,
      "total_amount": 1575.00,
      "currency": "TRY",
      "installment": 3,
      "extra_installment": 0,
      "card": {
        "holder": "AHMET YILMAZ",
        "masked": "454671******1234",
        "bin": "454671",
        "bank": "Yapı Kredi",
        "program": "World",
        "brand": "VISA",
        "type": "credit"
      },
      "dealer": {
        "id": 12,
        "name": "Örnek Bayi",
        "tax_number": "1234567890",
        "parent": null,
        "etn_code": "urn:mail:defaultpk@ornek.com",
        "custom1": "Bölge: Marmara",
        "custom2": "Cari Kodu: 120.01.001"
      },
      "description": "Sipariş #1024",
      "amount_original": 1500.00,
      "exchange_rate": 1,
      "commission_mode": 1,
      "commission_rate": 5.00,
      "commission_amount": 75.00,
      "pos": "Yapı Kredi Sanal Pos"
    }
  ],
  "meta": { "per_page": 25, "next_cursor": "eyJpZCI6…", "has_more": true }
}

amount_original, exchange_rate, commission_* ve pos yalnız firma kapsamında döner. next_cursor boşsa son sayfadasınız.

Tek bir tahsilatın güncel durumunu ve detayını döner (liste ile aynı alanlar). id = tahsilat guid'i (liste/başlatma yanıtındaki id). Ödeme sonucunu doğrulamanın kesin yoludur. Müşteri yalnız kendi + alt bayilerinin kaydını görür; bulunamazsa 404 not_found.

GET/payments/{id} FirmaMüşteri

Yanıt

{
  "data": {
    "id": "9F1C2A…",
    "process_no": "P260928ABC123",
    "status": "success",
    "status_message": null,
    "channel": "api",
    "created_at": "2026-09-28T13:20:00+00:00",
    "amount": 1500.00,
    "total_amount": 1575.00,
    "currency": "TRY",
    "installment": 3,
    "extra_installment": 0,
    "card": { "holder": "AHMET YILMAZ", "masked": "454671******1234", "bin": "454671", "bank": "Yapı Kredi", "program": "World", "brand": "VISA", "type": "credit" },
    "dealer": { "id": 12, "name": "Örnek Bayi", "tax_number": "1234567890", "parent": null },
    "description": "Sipariş #1024",
    "amount_original": 1500.00,
    "exchange_rate": 1,
    "commission_mode": 1,
    "commission_rate": 5.00,
    "commission_amount": 75.00,
    "pos": "Yapı Kredi Sanal Pos"
  }
}

amount_original, exchange_rate, commission_*, pos yalnız firma kapsamında döner.

Müşteri (bayi) listesini sayfalı döner; her kayıtta il/ilçe ve başarılı ödeme özeti (toplam tutar, işlem sayısı, tek çekim / taksitli) bulunur. Kapsama göre: firma anahtarı firmanın müşterilerini, müşteri anahtarı yalnız kendi alt bayilerini görür. Müşteri kapsamında müşterinin etn_code / custom1 / custom2 alanları dönmez (bunlar yalnız firma kapsamında gelir).

GET/customers FirmaMüşteri

Sorgu parametreleri

Parametre	Tip	Zorunlu	Açıklama
search	string	Opsiyonel	Ad, e-posta, telefon ya da vergi no.
page	integer	Opsiyonel	Sayfa numarası (varsayılan 1).
limit	integer	Opsiyonel	Sayfa boyutu (1–100, varsayılan 25).

Yanıt

{
  "data": [
    {
      "id": 12,
      "name": "Örnek Bayi",
      "tax_number": "1234567890",
      "phone": "0216 …",
      "email": "bayi@ornek.com",
      "province": "İstanbul", "district": "Kadıköy",
      "is_active": true,
      "etn_code": "urn:mail:defaultpk@ornek.com",
      "custom1": "Bölge: Marmara",
      "custom2": "Cari Kodu: 120.01.001",
      "summary": {
        "total_amount": 154200.00,
        "transaction_count": 87,
        "single": 51,
        "installment": 36
      }
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 42, "last_page": 2 }
}

Kullanıcı listesini sayfalı döner. Kapsama göre: firma anahtarı firmanın personelini (type=staff), müşteri anahtarı yalnız kendi kullanıcılarını döner. Personel kullanıcılarda şube ve izin haritası da bulunur.

GET/users FirmaMüşteri

Sorgu parametreleri

Parametre	Tip	Zorunlu	Açıklama
search	string	Opsiyonel	Ad, e-posta ya da telefon.
page	integer	Opsiyonel	Sayfa numarası (varsayılan 1).
limit	integer	Opsiyonel	Sayfa boyutu (1–100, varsayılan 25).

Yanıt

{
  "data": [
    {
      "id": 5,
      "name": "Ahmet Yılmaz",
      "first_name": "Ahmet",
      "last_name": "Yılmaz",
      "email": "ahmet@ornek.com",
      "phone": "05xx xxx xx xx",
      "type": "staff",
      "is_admin": false,
      "is_active": true,
      "branch": "Merkez",
      "permissions": { "tahsilat_goruntule": "kendi", "musteriler": "tam" },
      "created_at": "2026-09-28T10:00:00+00:00"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 8, "last_page": 1 }
}

type: staff (personel) · dealer (müşteri) · sub_dealer (alt müşteri). Yetkili kullanıcıda (is_admin: true) permissions boş döner — tüm modüllere erişir. branch yalnız personelde dolar.