Sipay Business Api
Turkish
  • Turkish
  • English
Turkish
  • Turkish
  • English
Turkish
  • Turkish
  • English
  1. Webhook
  • Overview
    • Hızlı Başlangıç Rehberi
    • Partner Cüzdan Entegrasyonu
  • Authentication
    • Get Access Token
      POST
  • Account
    • Get Business Account
      POST
    • Check Personal Wallet (AccountNumber)
      POST
    • Check Personal Wallet (PhoneNumber)
      POST
  • Wallet
    • Create Wallet For Business Account
      POST
    • Wallet Info
      POST
    • Wallet List By Filter
      POST
  • Transaction
    • Business To Personal Transfer
      POST
    • Business To Business Transfer
      POST
    • Send Money To Bank Account
      POST
    • Transfer To Virement
      POST
    • Get Payment Types
      GET
  • Transaction Data
    • Transaction Type Code List
    • SendMoneyToBankAccount sonrası işlem durumu nasıl kontrol edilir?
    • Summary Record By Filter
      POST
    • Get Request Withdraw List By Filter
      POST
    • Get Request Withdraw By Ext Id
      POST
    • Transaction Receipt
      POST
  • Webhook
    • Bankaya Para Transferi Webhook
    • Para Yükleme Webhook
    • Başarısız Para Yükleme Webhook
  1. Webhook

Bankaya Para Transferi Webhook

Bankaya Para Transferi Webhook
POST /v1/Transaction/SendMoneyToBankAccount ile oluşturulan para çekme talimatlarının sonucu asenkron webhook bildirimleriyle iletilebilir.

Webhook türleri#

Bankaya para transferi için iki ayrı webhook eventi bulunmaktadır:
EventAçıklama
WithdrawalTransferResultPara çekme işleminin başarı, başarısızlık, iptal veya iade gibi sonuçlarını bu sayfada açıklanan özel payload ile bildirir.
WithdrawCompletedYalnızca başarıyla tamamlanan para çekme işlemleri için standart SummaryRecord payload'ını gönderir.
Bu eventler ayrı ayrı yapılandırılır. WithdrawalTransferResult eventinin etkinleştirilmesi, WithdrawCompleted eventini otomatik olarak etkinleştirmez. Her iki event de etkinse aynı başarılı işlem için iki ayrı webhook bildirimi gönderilebilir.
Bu sayfanın devamı WithdrawalTransferResult webhook payload'ını açıklamaktadır. SummaryRecord payload'ı bu webhook'un payload'ı değildir.

Başarılı işlem webhook'u#

Para çekme talimatı banka tarafından başarıyla tamamlandığında aşağıdaki yapıda bir webhook gönderilir:
{
  "tenant_id": 5,
  "amount": 25,
  "currency_code": "TRY",
  "ext_transaction_id": "EXT-EXAMPLE-001",
  "request_withdraw_id": 2610095975284361006,
  "transaction_id": 2610099713036521748,
  "account_type_id": 1,
  "account_number": "12345678",
  "wallet_number": "87654321",
  "before_process_status": 0,
  "after_process_status": 1,
  "money_transfer_state": 0,
  "money_transfer_type": 3,
  "to_iban": "TR000000000000000000000000",
  "response_status": 0,
  "response_code": "100",
  "response_message": "İşlem başarılı",
  "transaction_type": "A01",
  "to_name": "EXAMPLE USER",
  "reason": ""
}
Aşağıdaki değerler birlikte başarılı bir payout sonucunu gösterir:
money_transfer_state = 0
after_process_status = 1
transaction_id > 0
Standart Pending → Completed akışında before_process_status = 0 olur. İşlem operasyonel süreç sonrasında tamamlanmışsa önceki statü farklı olabilir.

Sonuç eşleşmeleri#

Finansal sonucu belirlemek için money_transfer_state, before_process_status, after_process_status ve transaction_id alanları birlikte değerlendirilmelidir.
Sonuçmoney_transfer_statebefore_process_statusafter_process_statusAçıklama
Başarılı0Genellikle 0 veya 31İşlem tamamlanmıştır ve transaction_id > 0 olmalıdır.
Provider başarısızlığı / operasyonel işlem1Genellikle 03Finansal olarak kesin değildir; daha sonra başarılı veya iptal edilmiş duruma geçebilir.
İptal4Genellikle 0 veya 32İşlem iptal edilmiştir ve aktif fund-out bulunmamaktadır.
Başarılı işlem sonrası iade512Daha önce tamamlanmış payout banka tarafından iade edilmiştir.
after_process_status = 5 iade anlamına gelmez. Bu değer ClosedManually statüsüdür.

Tekrarlanan başarılı bildirim#

Aynı Completed bildirimi, işlem daha önce tamamlandıktan sonra tekrar alınabilir. Böyle bir bildirim aşağıdaki değerleri içerebilir:
before_process_status = 1
after_process_status = 1
money_transfer_state = 0
response_status = 2
response_code = "312"
Bu, yeni bir finansal başarısızlık değildir. İşlemin daha önce başarıyla tamamlandığını gösteren idempotent bir tekrar bildirimidir ve ikinci bir finansal aksiyon başlatmamalıdır.

Başarısız işlem senaryoları#

API çağrısı kabul edilmezse#

SendMoneyToBankAccount isteği, payout talimatı kabul edilmeden önce hata ile reddedilirse webhook gönderilmez. Örneğin:
{
  "status": 2,
  "code": "311",
  "message": "Cüzdan bakiyeniz yetersiz olduğundan işlemi gerçekleştiremiyoruz"
}

Provider işlemi başarısız olarak bildirirse#

money_transfer_state = 1
after_process_status = 3
Bu durum finansal olarak kesin değildir. İşlem operasyonel süreç sonrasında Completed veya Rejected/Cancelled durumuna geçebilir. Güncel durum GetRequestWithdrawByExtId ile takip edilmelidir.

Provider işlemi iptal ederse#

money_transfer_state = 4
after_process_status = 2
Bu kombinasyon, işlem talimatının iptal edildiğini ve aktif fund-out bulunmadığını gösterir.

Başarılı işlem sonrası iade#

Banka daha önce başarıyla tamamlanan işlemi iade ederse aynı ext_transaction_id için yeni bir webhook gönderilir:
money_transfer_state = 5
before_process_status = 1
after_process_status = 2
transaction_id > 0
İade bildirimi, daha önce işlenen başarılı bildirimin tekrarı olarak değerlendirilmemelidir.

Manuel veya operasyonel işlem#

İşlemin manuel incelemeye girmesi tek başına webhook oluşturmaz. Bu aşamada GetRequestWithdrawByExtId aşağıdaki değeri döndürebilir:
process_level_status = 3
Bu statü finansal olarak kesin değildir. İşlem daha sonra başarılı veya iptal edilmiş duruma geçebilir. Provider ayrıca Failed sonucu gönderirse money_transfer_state = 1 ve after_process_status = 3 içeren bir WithdrawalTransferResult webhook'u alınabilir.

response_* alanları#

response_status, response_code ve response_message, provider bildirimine ait finansal sonucu değil, bildirimin platform tarafından nasıl işlendiğini açıklar.
Finansal sonuç yalnızca bu alanlara göre belirlenmemelidir. Sonuç sınıflandırmasında öncelikle aşağıdaki alanlar birlikte kullanılmalıdır:
money_transfer_state
before_process_status
after_process_status
transaction_id

Webhook gecikirse veya alınamazsa#

Birincil bildirim WithdrawalTransferResult webhook'udur. Webhook alınamazsa, sonuç belirsizse veya mutabakat gerekiyorsa aynı ext_transaction_id ile aşağıdaki servis kullanılmalıdır:
process_level_status değerleri:
DeğerDurumAçıklama
0Pendingİşlem devam etmektedir; finansal olarak kesin değildir.
1CompletedPayout tamamlanmıştır. Daha sonra ayrı bir iade bildirimi gelebilir.
2RejectedAktif fund-out bulunmamaktadır. İlk ret/iptal veya sonradan gerçekleşen iade olabilir.
3Failed / Operational ProcessingFinansal olarak kesin değildir; sorgulamaya devam edilmelidir.
4Cancelledİşlem iptal edilmiştir ve aktif fund-out bulunmamaktadır.
5ClosedManuallyFinansal sonucu tek başına belirlemez; operasyon/destek teyidi gerekir.
process_level_status = 3 terminal durum değildir.

Raporlama ve mutabakat#

Başarıyla tamamlanan işlemin standart kayıt bilgileri isteğe bağlı olarak aşağıdaki servisle sorgulanabilir:
Bu servis raporlama, audit ve mutabakat içindir. Açık veya devam eden payout durumunu belirlemek için kullanılmamalıdır.

Teslimat ve idempotency#

Webhook'lar asenkron gönderilir ve teslim sırası garanti edilmez.
Herhangi bir HTTP 2xx yanıtı başarılı teslim onayı olarak kabul edilir.
Webhook yalnızca ext_transaction_id ile tekilleştirilmemelidir. Başarılı işlem ve daha sonra gerçekleşen iade aynı ext_transaction_id değerini kullanır.
İdempotency için aşağıdaki alanların birleşimi kullanılabilir:
ext_transaction_id
+ money_transfer_state
+ after_process_status
+ transaction_id
Tekrarlanan Completed bildirimi ikinci bir finansal aksiyon başlatmamalıdır.
Daha sonra gelen Refunded bildirimi mutlaka işlenmelidir.
Gecikmiş bir Completed bildirimi, daha önce işlenmiş Refunded sonucunun üzerine yazmamalıdır.
Previous
Transaction Receipt
Next
Para Yükleme Webhook
Built with