Ana içeriğe geç

İşlem Bildirimi

Craftgate, aşağıda belirtilen işlemlerin sonucunu ve işlem bilgilerini, sizin tanımlayacağınız bir URL e düzenli olarak iletir. Böylece Craftgate üzerinden gerçekleştirilen tüm ödeme/iptal/iade/para transferi işlemlerinizin sonuçlarını -ödeme akışı kesintiye uğrasa bile- dinleyebilir, akışlarınızı ödeme sonuçlarına göre planlayabilirsiniz.

  1. Ödeme İşlemi Sonucu(API_AUTH): Ödeme işleminin sonucu, başarılı ya da başarısız olması farketmeksizin, sizin ödeme sırasında ilettiğiniz webhook adresine iletilir.
  2. 3D Ödeme İşlemi Sonucu(API_VERIFY_AND_AUTH): 3D Pay model ödeme yöntemlerinde bu event gönderilir.
  3. Ödeme Formu kullanımlarında Ödeme İşlemi Sonucu(CHECKOUTFORM_AUTH): Ödeme formu kullanılarak yapılan ödeme işleminin sonucu, başarılı ya da başarısız olması farketmeksizin, sizin 3D ödeme başlatma sırasında ilettiğiniz webhook adresine iletilir.
  4. 3D Secure Doğrulama İşlemi Sonucu(THREEDS_VERIFY): 3D Secure doğrulama işleminin sonucu, başarılı ya da başarısız olması farketmeksizin, sizin 3D ödeme başlatma sırasında ilettiğiniz webhook adresine iletilir.
  5. Ödeme İade İşlemi Sonucu(REFUND): Ödeme iade işleminin sonucu başarılı ise webhook adresine iletilir.
  6. Ödeme Kırılımı İade İşlemi Sonucu(REFUND_TX): Ödeme kırılımının iade işleminin sonucu başarılı ise webhook adresine iletilir.
  7. Para Transferi Tamamlama İşlemi Sonucu(PAYOUT_COMPLETED): Pazaryerlerindeki para transferi işleminin tamamlanması sonucunda iletilir.
  8. Autopilot İşlemi Sonucu(AUTOPILOT): Autopilot işlemleri sonucu webhook adresine iletilir.
  9. Cüzdan Oluşma işlemi sonucu(WALLET_CREATED): Cüzdan oluşması durumunda cüzdan bilgileri ile webhook adresine iletilir.
  10. Cüzdan Hareketi İşlemi Sonucu(WALLET_TX_CREATED): Cüzdan hareketi gerçekleştirildiğinde işlem sonucu webhook adresine iletilir.
  11. Alışveriş Kredisi Sonucu (BNPL_NOTIFICATION): BNPL süreçlerinden alışveriş kredisi için kredi başvurusu sonrası durum değişikliği olduğunda işlem sonucu webhook adresine iletilir.
  12. Banka Hesap Hareketi İşlemi(BANK_ACCOUNT_TRACKING_RECORD): Banka hesap hareketi izleme sonucunda bir para transferi gerçekleştirildiğinde işlem sonucu webhook adresine iletilir.
  13. Parçalı Ödeme Tamamlanma(MULTI_PAYMENT_COMPLETED): Parçalı ödeme işlemleri tamamlandığında webhook adresine iletilir.
  14. BKM Express Ödeme Kontrol(BKM_EXPRESS_PAYMENT_NOTIFICATION): Ödeme tamamlanmadan önce ödemeye ait kontrollerin yapılması için bildirim gönderilir.

Önemli Not​

  1. 3DS ödeme akışında, iletmiş olduğunuz callbackUrl adresine yapılacak olan istekler tarayıcı üzerinden gerçekleşmektedir. Son kullanıcının bu akışı durdurması veya kullanıcının internetinde yaşanabilecek sorunlardan dolayı callbackUrl adresine yapılan istekler yapılamayabilir. O nedenle webhook servislerimiz özellikle 3DS ödemelerin takibi ve kullanıcı davranışlarının tespiti için faydalı olabilmektedir.
  2. İşlem bildirimine zamanla yeni eventler eklenebilmektedir. Bu nedenle, işlemediğiniz bir event gelmesi durumunda uygulamanızı buna göre tasarlamalısınız.

Webhook Bildirimi Alınabilmesi için Adres Tanımı Yapılması​

Webhook bildiriminin aktifleşleştirilmesi için Craftgate paneli Ayarlar->Üye İşyeri Ayarları->Webhook Bildirim Ayarları altındaki Üye işyeri Webhook URL alanının doldurulması gerekmektedir. Webhook URL adresi olarak POST isteklerini kabul edip HTTP kodlarından 2xx dönen bir URL bilgisi girmeniz durumunda, Craftgate ödemeler sonrası ilgili veriyi gönderiyor olacaktır.

Webhook Ayarları

Webhook Adresine Çağrı Yapılması ve İletilen İstek​

Webhook çağrısı, ödemeyle alakalı ilgili aksiyon tamamlandıktan 30 saniye sonra sizin belirttiğiniz webhookUrl adresine yapılmaya başlanır. 2xx cevabı alınmadığı durumda sırasıyla 10 sn, 30 sn, 3 dk, 10 dk, 30 dk bekletilerek tekrar tekrar deneme yapılır. 5 denemenin sonucunda hala başarılı olmamışsa iptal edilir. Tekrar deneme mekanizması nedeniyle, gelen mesajın karşılığı olan ödeme ile ilgili sisteminizdeki durumunun kontrol edilmesi önemlidir.

Ödeme, İptal, İade, 3D ödeme ve 3D secure doğrulama, Para transferi sonuçları belirtmiş olduğunuz webhook adresine JSON formatında POST http metodu ile iletilir.

3DS ödemesi sırasında:

  • Eğer POS 3D Model kullanılıyorsa, 3DS kullanıcı doğrulama aşamasından sonra 3DS tamamlama servisini çağırmanız gerektiği anlamına gelir. Bu aşamada THREEDS_VERIFY event'i 3DS kullanıcı doğrulamasından sonra ve API_AUTH event'i 3DS tamamlandıktan sonra gönderilecektir.
  • Eğer POS 3D Pay modelini kullanıyorsa, THREEDS_VERIFY yerine -kullanıcı doğruladığında banka tarafında ödeme çekileceği için- API_VERIFY_AND_AUTH event'i gönderilecektir.
  • Ödeme formu kullanıyorsanız, diğer event'ler yerine yalnızca CHECKOUTFORM_AUTH gönderilecektir.

İstek Parametreleri​

eventTimestamp
long

İsteğin oluşturulduğu tarihin epoch değeri

eventType
string

İsteğin hangi işlem için gerçekleştiğini belirtir

Değerler:
API_AUTH
API_VERIFY_AND_AUTH
CHECKOUTFORM_AUTH
THREEDS_VERIFY
REFUND
REFUND_TX
PAYOUT_COMPLETED
AUTOPILOT
WALLET_CREATED
WALLET_TX_CREATED
BNPL_NOTIFICATION
BANK_ACCOUNT_TRACKING_RECORD
MULTI_PAYMENT_COMPLETED
BKM_EXPRESS_PAYMENT_NOTIFICATION
status
string

İşleme ait durum bilgisidir

Değerler:
SUCCESS
FAILURE
payloadId
string

Event tipine göre işlemin ID değeri. Örn; Ödemeye ait ID değeri veya Ödeme formuna ait token bilgisi gibi

payload
Object

Gelen eventType bilgisine göre ilgili işleme ait ek detayları içerir. PAYOUT_COMPLETED, AUTOPILOT,WALLET_CREATED, WALLET_TX_CREATED, BNPL_NOTIFICATION, BANK_ACCOUNT_TRACKING_RECORD eventleri için dolu gelir.

Webhook Adresine İletilen İsteğin Craftgate tarafından Gönderildiği Kontrolü​

Webhook URL inize gelen isteklerin Craftgate sisteminden gönderildiğini bilgisinin teyit edilebilmesi için, HTTP headerları arasında gönderilen x-cg-signature-v1değerinin kontrol edilmesi gerekmektedir. x-cg-signature-v1 değeri, istek içerisinde gönderilen -payload dışındaki- alanların String olarak birleştirilmesi, bu değerin HmacSHA256 algoritması ile hash'lenmesi, sonrasında oluşan yeni değerin Base64 ile encode edilmesi ile hesaplanır. Hesaplama sırasında SHA-256 çıktısının digest (bytes), byte encoding'inin de UTF-8 olması gerektiği unutmayınız.

Örnek olarak, API entegrasyonu kullanılarak, 2022-01-01T09:30:32 GMT+3 (epoch: 1641018632) tarihinde başarılı bir şekilde alınan 2150001 id'li ödeme için eventType+eventTimestamp+status+payloadId bilgileri String olarak birleştirildiğinde API_AUTH1641018632SUCCESS2150001 değeri oluşmaktadır. Bu değeri Craftgate Üye işyeri paneli Ayarlar kısmında bulunan Üye İşyeri Webhook Key değeri olan 1Q2w3E4r5T6y7U8i9Op ile hash'leyip, Base64 ile encode ettiğinizde, sonuç eNXKxfxUpVmp/wBrNUmOLjNXL0sYl0mh1s/rEB8K8NU= şeklinde oluşacaktır. Değer Craftgate tarafından header'da iletilen x-cg-signature-v1 değeri ile karşılaştırılabilir.

Algoritmanın detayları için client'larımıza ait aşağıdaki kodlar incelenebilir.

Java.NETPHPNode.jsGo

Webhook Örnek Veri​

İşlem TipiÖrnek Veri
API_AUTH{"eventType": "API_AUTH","eventTime": "2023-04-13T14:15:32.123456","eventTimestamp": 1681384532,"status": "SUCCESS","payloadId": "271591"}
API_VERIFY_AND_AUTH{"eventType": "API_VERIFY_AND_AUTH","eventTime": "2023-04-13T14:15:32.123456","eventTimestamp": 1681384532,"status": "SUCCESS","payloadId": "271591"}
CHECKOUTFORM_AUTH{"eventType": "CHECKOUTFORM_AUTH","eventTime": "2023-04-13T13:58:17.123456","eventTimestamp": 1681383497,"status": "SUCCESS","payloadId": "14755c78-2e55-4171-ade2-7c9e7dc453ef"}
THREEDS_VERIFY{"eventType": "THREEDS_VERIFY","eventTime": "2023-04-13T14:13:12.123456","eventTimestamp": 1681384392,"status": "SUCCESS","payloadId": "271591"}
REFUND{"eventType": "REFUND","eventTime": "2023-04-14T11:27:17.123456","eventTimestamp": 1681460837,"status": "SUCCESS","payloadId": "24"}
REFUND_TX{"eventType": "REFUND_TX","eventTime": "2023-04-14T11:27:22.123456","eventTimestamp": 1681460842,"status": "SUCCESS","payloadId": "144"}
PAYOUT_COMPLETED{"eventType": "PAYOUT_COMPLETED","eventTime": "2023-04-14T10:41:07.123456","eventTimestamp": 1681458067,"status": "SUCCESS","payloadId": "50","payload": {"settlementFileId": 50,"settlementType": "SETTLEMENT"}}
AUTOPILOT{"eventType": "AUTOPILOT","eventTime": "2023-04-14T11:07:31.123456","eventTimestamp": 1681459651,"status": "SUCCESS","payloadId": "62-garanti-59","payload": {"posAlias": "62-garanti-59","posName": "garanti","nonThreeDsStatus": "PASSIVE","threeDsStatus": "ACTIVE","notificationsEnabled": false}}
WALLET_CREATED{"eventType": "WALLET_CREATED", "eventTime": "2023-04-26T16:16:47.123456", "eventTimestamp": 1682515007, "status": "SUCCESS", "payloadId": "34", "payload": { "currency": "TRY", "walletId": 34, "memberId": 39, "negativeAmountLimit": 0 } }
WALLET_TX_CREATED{"eventType": "WALLET_TX_CREATED", "eventTime": "2023-04-28T15:13:12.123456", "eventTimestamp": 1682683992, "status": "SUCCESS", "payloadId": "34", "payload": { "currency": "TRY", "walletTransactionType": "PAYMENT_REDEEM", "id": 158, "memberId": 39, "transactionId": 1, "walletId": 34, "amount": -10 } }
BNPL_NOTIFICATION{"eventType": "BNPL_NOTIFICATION", "eventTime": "2023-11-01T00:00:00.123456", "eventTimestamp": 1699477200, "status": "SUCCESS", "payloadId": "204", "payload": {"additionalAction": "APPROVAL_REQUIRED"}}
BANK_ACCOUNT_TRACKING_RECORD{"eventType": "BANK_ACCOUNT_TRACKING_RECORD","eventTime": "2023-07-24T10:27:00.123456","eventTimestamp": 1690208820,"status": "SUCCESS","payloadId": "537","payload": {"currency": "TRY","recordDate": "2016-02-05T12:24:41","senderName": "Alican Akkuş","key": "160205987654321","recordType": "RECEIVE","description": "7654321 numaralı sipariş","senderIban": "TR870006400000111351052758","amount": 81500}}
MULTI_PAYMENT_COMPLETED{"eventType": "MULTI_PAYMENT_COMPLETED", "eventTime": "2024-04-05T15:40:02.123456", "eventTimestamp": 1712320802, "status": "SUCCESS", "payloadId": "774a7c17-1a47-4104-a562-35a521ad3ac7", "payload": { "paymentIds": [ 11914 ], "conversationId": "convId-123", "externalId": "externalId-123", "multiPaymentStatus": "COMPLETED", "token": "774a7c17-1a47-4104-a562-35a521ad3ac7" } }
BKM_EXPRESS_PAYMENT_NOTIFICATION{"eventType":"BKM_EXPRESS_PAYMENT_NOTIFICATION","eventTime":"2024-06-26T18:56:37.123456","eventTimestamp":1719417397,"status":"SUCCESS","payloadId":"dcfdc163-0545-46d7-8f86-5a11718e56ec","payload":{"ticketId":"dcfdc163-0545-46d7-8f86-5a11718e56ec","paidPrice":"1,00","installment":1,"price":"1,00"}}