payinall Entegrasyonuna Giriş

payinall API, çevrimiçi ödeme kabul eden tüm üye iş yerlerinin kullanabilmesi amacı ile tasarlanmıştır. Tercih edilen sunucu taraflı programlama dilleri ile entegre olabilir. Ayrıca API ile çeşitli sorgular yapılabilmektedir. API'nin kullanılabilmesi için üye iş yerlerine önceden tanımlanmış olan merchantId ve secretKey verilmesi gerekmektedir. merchantId üye iş yerini belirten benzersiz bir numara iken, secretKey sorgulama yapmak için kullanılması gereken benzersiz bir numaradır.

Canlı Ortama Geçiş

Olası tüm durumlar için ödeme adımlarınızı Test Bilgileri ile test edin.
Sonuç sayfanızın (BackrefUrl) payinall'dan gelen yanıtı yorumlamasına dikkat edin.
payinall servislerinden dönebilecek tüm hatalara karşı kodunuzu düzenleyin.

API

API Entegrasyonu

Taksit ve Bin Sorgulama

Bu metot ile kartın ilk 6 hanesini girerek, işlemlere yapılabilecek taksit oranları bilgisine ulaşabilirsiniz. Taksit oranları, kartın bağlı olduğu bankaya bağlı olarak ortaya çıkmaktadır.

Üye iş yerinin API entegrasyonu için kullandığı ödeme formunda bazı kontrollerin bulunması gerekmektedir. Bu kontroller:

Kart numarasının Luhn Algoritmasından geçmesi gerekmektedir.
Kartın son kullanma tarihinin geçmemiş olması gerekmektedir.
Kart sahibinin isim ve soy ismi bilgilerinin girilmesi gerekmektedir.

Üye iş yerlerine sunulan servisler:

3D ile Ödeme
Taksit ve Bin Sorgulama
Ödeme Sorgulama
Ön Provizyonlu Ödeme

3D ile Ödeme

Bu metot, girilen kart bilgileri ile işleme ait miktarın kartın bakiyesinden çekilmesini sağlamaktadır. Tek çekim ve taksitli çekim seçenekleri ile işlemler gerçekleştirilebilir.

Ödeme Sorgulama

Bu metot ile bir islemin kayda geçip geçmediği sorgulanır ve işlemin detay bilgilerine ulaşılır.

3D Güvenli Ödeme İşlem Akışı

Standard Page

Taksit ve Bin Sorgulama

Servis Adresleri:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/payment3d/bin/v1

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/payment3d/bin/v1

Taksit sorgulama işlemi bir kredi kartı girildiğinde ve kredi kartı anlaşmalı bir taksit programına dahilse, kartın ilk 6 hanesinin kullanılması ile taksit oranları hakkında bilgi vermektedir.

Servise Gönderilmesi Gereken Parametreler:

Parametre İsmi	Tip	Zorunluluk	Açıklama
MerchantId	string	Evet	Üye iş yerine ait benzersiz Id numarası
BinCode	string	Evet	Kartın ilk 6 hanesi

Servisten Gelen Yanıta Ait Parametreler:

Parametre İsmi	Tip	Açıklama
BankCode	string	Kartın ait olduğu bankanın standard kodu.
BankName	string	Kartın ait olduğu bankanın adı.
CardBrand	string	Kartın ait olduğu ödeme kuruluşu.
CardType	string	Girilen kartın türü.
installment (Installments)	number	Girilen kart ile yapılabilecek taksit miktarı.
BankName	string	Kartın ait olduğu bankanın adı.
CardBrand	string	Kartın ait olduğu ödeme kuruluşu.
CardType	string	Girilen kartın türü.

Servisten Dönen Mesaj Kodları:

MessageCode	Açıklama
MessageCode = 00	Başarılı
MessageCode = 7201	Geçersiz MerchantId

JSON Request-Response (İstek-Yanıt)

//Request
                                    {
                                        "MerchantId": "5d891bbeea1e5e94b02b266b",
                                        "BinCode": "450803"
                                    }

//Response
                                    {
                                        "SystemTime": 1571813371325,
                                        "Success": true,
                                        "MessageCode": "00",
                                        "Message": "Başarılı",
                                        "UserMessage": "İşleminiz başarıyla gerçekleştirildi.",
                                        "SaleRate": "2.5",
                                        "CardType": "Credit",
                                        "CardBrand": "VISA",
                                        "BankCode": "64",
                                        "BankName": "T. İŞ BANKASI A.Ş.",
                                        "IsInstallment": true,
                                        "Installments": [
                                            {
                                                "installment": 1,
                                                "gatewayId": "5d9fb188e578e039573880b9",
                                                "ccMerchantRateInstallment": "2.5"
                                            },
                                            {
                                                "installment": 2,
                                                "gatewayId": "5d9fb188e578e039573880b9",
                                                "ccMerchantRateInstallment": "4"
                                            },
                                            {
                                                "installment": 3,
                                                "gatewayId": "5d9fb188e578e039573880b9",
                                                "ccMerchantRateInstallment": "5"
                                            },
                                            {
                                                "installment": 6,
                                                "gatewayId": "5d9fb188e578e039573880b9",
                                                "ccMerchantRateInstallment": "8"
                                            },
                                            {
                                                "installment": 9,
                                                "gatewayId": "5d9fb188e578e039573880b9",
                                                "ccMerchantRateInstallment": "12"
                                            },
                                            {
                                                "installment": 12,
                                                "gatewayId": "5d9fb188e578e039573880b9",
                                                "ccMerchantRateInstallment": "15"
                                            }
                                        ]
                                    }

//Request
                                    {
                                        "MerchantId": "5db6c40a03dd6ec2358b9c5f",
                                        "BinCode": "469181"
                                    }

//Response
                                    {
                                        "SystemTime": 1641888930572,
                                        "Success": true,
                                        "MessageCode": "00",
                                        "Message": "Başarılı",
                                        "UserMessage": "İşleminiz başarıyla gerçekleştirildi.",
                                        "SaleRate": "4.8",
                                        "CardType": "Credit",
                                        "CardBrand": "VISA",
                                        "BankCode": "146",
                                        "BankName": "ODEA BANK",
                                        "IsInstallment": true,
                                        "Installments": [
                                            {
                                                "installment": 1,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b9",
                                                "ccMerchantRateInstallment": "1.13"
                                            },
                                            {
                                                "installment": 2,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b8",
                                                "ccMerchantRateInstallment": "1.848"
                                            },
                                            {
                                                "installment": 3,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b7",
                                                "ccMerchantRateInstallment": "2.3205"
                                            },
                                            {
                                                "installment": 4,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b6",
                                                "ccMerchantRateInstallment": "2.793"
                                            },
                                            {
                                                "installment": 5,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b5",
                                                "ccMerchantRateInstallment": "3.2655"
                                            },
                                            {
                                                "installment": 6,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b4",
                                                "ccMerchantRateInstallment": "3.738"
                                            },
                                            {
                                                "installment": 7,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b3",
                                                "ccMerchantRateInstallment": "4.2105"
                                            },
                                            {
                                                "installment": 8,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b2",
                                                "ccMerchantRateInstallment": "4.683"
                                            },
                                            {
                                                "installment": 9,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b1",
                                                "ccMerchantRateInstallment": "5.1555"
                                            },
                                            {
                                                "installment": 10,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602b0",
                                                "ccMerchantRateInstallment": "5.628"
                                            },
                                            {
                                                "installment": 11,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602af",
                                                "ccMerchantRateInstallment": "6.1005"
                                            },
                                            {
                                                "installment": 12,
                                                "gatewayId": "602d0bdcb1d2715ef89ada6f",
                                                "_id": "5f5630afabd3ba0705e602ae",
                                                "ccMerchantRateInstallment": "6.573"
                                            }
                                        ]
                                    }

3D İle Ödeme

3D ile ödeme işlemi bir kart ve tutar girildiğinde, girilen tutarın söz konusu kartın bakiyesinden düşürülmesini içerir. Eğer kart bilgileri geçerliyse 3D ile ödeme işlemi tek çekim ve taksitli çekim işlemlerine uygundur.

3D ile ödeme API ile üç aşamada yapılır.

1-Ödeme Bilgilerini Gönderme

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/payment3d/secure3D/v1

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/payment3d/secure3D/v1

Servise Gönderilmesi Gereken Parametreler:

Parametre İsmi	Tip	Zorunluluk	Açıklama
Amount	decimal	Evet	Kartın bakiyesinden düşecek ödeme tutarı
BackrefUrl	string	Evet	3D Secure işleminde üye iş yerine başarılı ya da hatalı sonucu bildiren URL adresi. Bu adrese sonuç JSON olarak dönmektedir.
CardExpireMonth	string	Evet	Ödeme işleminin yapılacağı kartın son kullanma tarihi ayı
CardExpireYear	string	Evet	Ödeme işleminin yapılacağı kartın son kullanma tarihi yılı
CardNumber	string	Evet	Ödeme işleminin yapılacağı kartın üzerinde yazan numara
CardOwner	string	Evet	Ödeme yapılacak kartın üzerinde yazan isim (kartın sahibi)
CardSecurityCode	string	Evet	Ödeme yapılacak kartın arka yüzünde yazan üç haneli güvenlik numarası
ClientIp	string	Evet	Ödemeyi gerçekleştiren üye iş yerine ait IP adresi
Description	string	Evet	Üye iş yerinin ödemeye ait doldurabileceği açıklama alanı
BasketId	string	Evet	Üye iş yerinin ilgili ödemenin sepetini tanımlamak için kullanılan id
Installment	string	Evet	Ödeme işleminin kaç orana bölünerek gerçekleşeceğini belirten taksit miktarı alanı
Language	string	Evet	Bu alana "TR" girilmelidir.
MerchantId	string	Evet	Üye iş yerine ait benzersiz Id numarası
PaymentChannel	string	Evet	Bu alana 'Api' yazılmalıdır
Signature	string	Evet	HMac Sha512 hashleme metodu kullanılarak oluşturulan imza
TransactionId	string	Evet	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin sipariş numarası. 10 ile 60 karakter arasında alfa-numerik olması gerekmektedir.
TransactionTime	timestamp	Evet	İşlemin gerçekleştiği unix timestamp değeri

Signature (İmza) Oluşturma

Aşağıdaki alanların art arda eklenmesi ve ardından hashlenmesi ile imza oluşmaktadır. Oluşan imzanın servise gönderilmesi gerekmektedir. Hashlemede kullanılacak algoritma HMac Sha512 algoritmasıdır.

secretKey + MerchantId + TransactionId + TransactionTime + Amount + Currency + Installment + CardNumber (İlk 6 hanesi)

Servisten Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
Message	string	Girilen bilgiler doğrultusunda servisten dönen mesaj
MessageCode	string	Dönen mesaja ait kod
Secure3dUrl	string	Müşterinin ekranında gösterilmesi gereken 3D şifre ekranının oluştuğu Url adresi
Success	string	Girilen bilgiler doğrultusunda 3D ödeme isteği yapılabiliyorsa true, yapılamıyorsa false döner
SystemTime	number	Dönen yanıta ait unix timestamp değeri
UserMessage	string	Dönen yanıta ait kullanıcıya yönelik mesaj

JSON Request-Response (İstek-Yanıt)

//Request
                                    {
                                        "MerchantId": "5d891bbeea1e5e94b02b266b",
                                        "Language": "TR",
                                        "TransactionId": "e5180a5a-605b-4f91-b085-6427c595a138",
                                        "BackrefUrl": "http://backref.merchant.com/refpage",
                                        "Currency": "TRY",
                                        "Installment": "3",
                                        "Description": "May the force be with you.",
                                        "BasketId": "123456",
                                        "PaymentChannel": "Api",
                                        "Amount": 12.5,
                                        "CardNumber": "4508034508034509",
                                        "CardExpireMonth": "12",
                                        "CardExpireYear": "30",
                                        "CardSecurityCode": "000",
                                        "CardOwner": "testname",
                                        "ClientIp": "10.10.2.27",
                                        "TransactionTime": "1571819068557",
                                        "Signature": "6e08a470a313634f2f46c4fce375f1c86457fe6c196d0928d32feb0a2376a21db0600e0c268864869f1f975c6d0718301cc2acbeb76f54e89156b112c1199d7a"
                                }

//Response
                                    {
                                        "Secure3dUrl": "https://payinallpostestapi.erpapay.com/api/payment3d/get3dSign/v1?id=e5180a5a-605b-4f91-b085-6427c595a138",
                                        "SystemTime": 1571819080625,
                                        "Success": true,
                                        "MessageCode": "00",
                                        "Message": "Başarılı",
                                        "UserMessage": "3d işlem başlatma başarılı."
                                    }

Birinci aşamada servise gönderilen ödeme bilgilerinin ardından servisten bir yanıt döner. Eğer işlem başarılıysa dönen yanıtın içerisinde yer alan Secure3DUrl içerisinde URL adresi saklar. Bu adres ile kullanıcının 3D imza bilgisini girmesi sağlanır. Kullanıcı söz konusu adresi bir tarayıcıda açarak bankadan şifre talep eder ve SMS ile gelen şifreyi girer. Bu aşamadan sonra banka kredi kartı doğrulaması yapar. Bankadan gelen yanıt doğrultusunda kullanıcı işleminin gerçekleşip gerçekleşmediğini tarayıcıda açtığı sayfada görebilir. Ayrıca bankadan dönen yanıt BackrefUrl alanına yazılan adrese JSON şeklinde döner.

Örnek yanıt:

                             {
                                     "TransactionId": "e5180a5a-605b-4f91-b085-6427c595a138",
                                     "SystemTime": "1575969358720",
                                     "Success": true,
                                     "MessageCode": "7280",
                                     "Message": "İşleminiz başarıyla gerçekleştirildi",
                                     "UserMessage": "3D Secure işlemi başarıyla gerçekleştirildi"
                                  }

2- 3D Güvenli Ödeme Tamamlama

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/payment3d/complete3dpayment/v1

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/payment3d/complete3dpayment/v1

Birinci aşamada servise gönderilen ödeme bilgilerinin ardından servisten bir yanıt döner. Eğer işlem başarılıysa dönen yanıtın içerisinde yer alan Secure3DUrl içerisinde URL adresi saklar. Bu adres ile kullanıcının 3D imza bilgisini girmesi sağlanır. Kullanıcı söz konusu adresi bir tarayıcıda açarak bankadan şifre talep eder ve SMS ile gelen şifreyi girer. Bu aşamadan sonra banka kredi kartı doğrulaması yapar. Bankadan gelen yanıt doğrultusunda kullanıcı işleminin gerçekleşip gerçekleşmediğini tarayıcıda açtığı sayfada görebilir. Ayrıca bankadan dönen yanıt BackrefUrl alanına yazılan adrese JSON şeklinde döner.

Kullanıcının Secure2DUrl adresini tarayıcıda açması ve başarılı bir şekilde 3D imza adımını geçmesinin ardından 3D güvenli ödeme tamamlama adımına geçilir. Bu adımda gerekli parametreler verilmesi ile 3D güvenli ödeme işlemi sonuca ulaşır.

Servisten Gönderilmesi Gereken Parametreler

Parametre İsmi	Tip	Zorunluluk	Açıklama
MerchantId	string	Evet	Üye iş yerine ait benzersiz Id numarası
TransactionId	string	Evet	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin sipariş numarası
smsCode	string	Evet	Bu alana "000000" girilmelidir. Bu alan sadece "TEST" ortamı için gereklidir "PROD" ortamda gönderilmemesi gerekir

Servise Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
Message	string	Girilen bilgiler doğrultusunda servisten dönen mesaj
MessageCode	string	Dönen mesaja ait kod
Success	string	Girilen bilgiler doğrultusunda 3D ödeme isteği yapılabiliyorsa true, yapılamıyorsa false döner
SystemTime	timestamp	Dönen yanıta ait unix timestamp değeri
UserMessage	string	Dönen yanıta ait kullanıcıya yönelik mesaj

JSON Request-Response (İstek-Yanıt)

//Request
                                   {
                                        "MerchantId": "5d891bbeea1e5e94b02b266b",
                                        "TransactionId": "e5180a5a-605b-4f91-b085-6427c595a138",
                                   }

//Response
                                    {
                                        "SystemTime": 1571819080625,
                                        "Success": true,
                                        "MessageCode": "7280",
                                        "Message": "İşleminiz başarıyla gerçekleştirildi",
                                        "UserMessage": "İşleminiz başarıyla gerçekleştirildi."
                                    }

3D İle Ödeme

Link Oluşturularak Ödeme Alma Yöntemidir

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/payorderlink/createpaylink

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/payorderlink/createpaylink

Servise Gönderilmesi Gereken Parametreler:

Parametre İsmi	Tip	Zorunluluk	Açıklama
merchantId	string	Evet	Müşteriye verilen benzersiz müşteri numarası
secretKey	string	Evet	Müşteriye verilen benzersiz müşteri anahtarı
BackrefUrl	string	Evet	3D Secure işleminde üye iş yerine başarılı ya da hatalı sonucu bildiren URL adresi. Bu adrese sonuç JSON olarak dönmektedir.

Parametre İsmi	Tip	Açıklama
message	string	Girilen bilgiler doğrultusunda servisten dönen mesaj
paymentUrl	string	iletilen bilgilere göre oluşturulan link adresi
linkId	string	iletilen bilgilere göre oluşturulan linkin id bilgisi
success	boolen	Girilen bilgiler doğrultusunda dönen boolen cevap

JSON Request-Response (İstek-Yanıt)

//Request
                                    {
                                        "merchantId": "5d891bbeea1e5e94b02b266b",
                                        "secretKey": "SJKL7895VV",
                                        "backrefUrl": "http://backref.merchant.com/refpage"
                                    }

//Response
                                    {
                                        "linkId": "68da73cd9b5e4278409959c5",
                                        "paymentUrl": "https://posmerchant.payinall.com/paymentlink/c21b232df5065d9bb472c05f84a2e694e7c19a545b8a40c49b781688713e3",
                                        "message": Link Oluşturma işlemi başarılı.,
                                        "success": true,
                                        }

Ön Provizyonlu Ödeme

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/payment3d/capture/v1

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/payment3d/capture/v1

Öncelikle ön provizyonlu ödeme yapabilmek için üye işyerinin VakıfBank'a tanımlı olup ön provizyon onayı alınması gerekmektedir. Daha sonra eğer ön provizyonlu ödeme yapılmak istenirse, ödeme bilgilerini gönderme servisinde isAuth parametresi true olarak gönderilir. isAuth Parametresi true olarak gönderildikten sonra yukarıda belirtilen bitirme servisine gerekli parametreler gönderilerek ön provizyonlu ödeme tamamlanmış olur. Ön provizyonlu ödeme şeklinde, para 25 gün askıda kalmakta olup 26.gün işlem iptal olmaktadır.

Servisten Gönderilmesi Gereken Parametreler

Parametre İsmi	Tip	Zorunluluk	Açıklama
MerchantId	string	Evet	Üye iş yerine ait benzersiz Id numarası
SecretKey	string	Evet	Üye iş yerine ait benzersiz Id numarası
TransactionId	string	Evet	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin sipariş numarası. 10 ile 60 karakter arasında alfa-numerik olması gerekmektedir.

Servise Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
TransactionId	string	üye iş yerinin sipariş numarası
SystemTime	string	Dönen yanıta ait unix timestamp değeri
Success	string	Girilen bilgiler doğrultusunda ön provizyonlu işlem yapıldıysa true, yapılmadıysa false döner
MessageCode	timestamp	Dönen mesaja ait kod
Message	string	Girilen bilgiler doğrultusunda servisten dönen mesaj

JSON Request-Response (İstek-Yanıt)

//Request
                                   {
                                        "MerchantId": "5fe9e0068ce7bc27e8472ebe",
                                        "SecretKey": "RNBYJYuTn77PruEndjOY3JiP",
                                        "TransactionId": "DOFu0KQyZ6pQ",
                                   }

//Response
                                    {
                                        "TransactionId": DOFu0KQyZ6pQ,
                                        "SystemTime": 1643899034500,
                                        "Success": true,
                                        "MessageCode": "00",
                                        "Message": "VakıfBank Provizyon Kapama Başarılı.",
                                    }

Ödeme Sorgulama

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/payment3d/paymentInfo/v1

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/payment3d/paymentInfo/v1

Taksit sorgulama işlemi bir kredi kartı girildiğinde ve kredi kartı anlaşmalı bir taksit programına dahilse, kartın ilk 6 hanesinin kullanılması ile taksit oranları hakkında bilgi vermektedir.

Ödeme sorgulama işlemi üye iş yeri Id'si ve bir sipariş numarası girildiğinde, söz konusu sipariş numarasına ait ödemenin kayıtlara geçip geçmeme bilgisi ve ödemenin detayları ile ilgili bilgi verir.

Servise Gönderilmesi Gereken Parametreler

Parametre İsmi	Tip	Zorunluluk	Açıklama
MerchantId	string	Evet	Üye iş yerine ait benzersiz Id numarası
TransactionId	string	Evet	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin sipariş numarası

Servisten Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
TransactionId	string	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin sipariş numarası
SystemTime	timestamp	Dönen yanıta ait unix timestamp değeri
Success	string	Girilen bilgiler doğrultusunda 3D ödeme isteği yapılabiliyorsa true, yapılamıyorsa false döner
Amount	decimal	Kartın bakiyesinden düşen ödeme tutarı
TotalPay	string	Üye iş yerine ödenecek toplam tutar
MessageCode	string	Dönen mesaja ait kod
Message	string	Girilen bilgiler doğrultusunda servisten dönen mesaj
UserMessage	string	Dönen yanıta ait kullanıcıya yönelik mesaj
ErrorCode	string	Dönen hata mesajına ait kod
ErrorDetail	string	Girilen bilgiler doğrultusunda servisten dönen hata mesajı detayı

JSON Request-Response (İstek-Yanıt) (Başarılı/Başarısız İşlem Örneği)

//Request
                                   {
                                        "MerchantId": "5d891bbeea1e5e94b02b266b",
                                        "TransactionId": "test123456789"
                                   }

//Response
                                    {
                                        "TransactionId": "test123456789",
                                        "SystemTime": 1574077298636,
                                        "Success": true,
                                        "Amount": "100.00",
                                        "TotalPay": "98.1500",
                                        "MessageCode": "0000",
                                        "Message": "İşlem Başarılı",
                                        "UserMessage": "İşlem Başarılı"
                                    }

//Request
                                   {
                                        "MerchantId": "60eda22e72243031a024bb89",
                                        "TransactionId": "Rf4e0PgwGG4G"
                                   }

//Response
                                    {
                                        "TransactionId": "Rf4e0PgwGG4G",
                                        "SystemTime": 1641116967200,
                                        "Success": false,
                                        "MessageCode": "7719",
                                        "Message": "İşlem Başarısız",
                                        "UserMessage": "İşlem Başarısız"
                                        "ErrorCode": "58",
                                        "ErrorDetail": "POSa İzin Verilmeyen İşlem"
                                    }

İPTAL SERVİSİ

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/void/v1/create/void

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/void/v1/create/void

İptal servisi aynı gün içinde çalışmaktadır, ertesi gün iptal işlemi yapılamaz. İptal servisinde, request bilgisinde TransactionId,secretKey ve MerchantId bilgisi gönderilmektedir. Dönen sonuç başarılı olduğunda işlem direkt olarak iptal edilmiş olmaktadır.

Servise Gönderilmesi Gereken Parametreler

Parametre İsmi	Tip	Zorunluluk	Açıklama
payorderId	string	Evet	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin işlem numarası
secretKey	string	Evet	İstek esnasında gönderilen üye iş yerinin secretkey bilgisi
merchantId	string	Evet	Üye iş yerini belirten benzersiz bir numara

Servisten Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
TransactionId	string	üye iş yerinin işlem numarası
MessageCode	string	Dönen mesaja ait kod
Message	string	Girilen bilgiler doğrultusunda servisten dönen mesaj
UserMessage	string	Dönen yanıta ait kullanıcıya yönelik mesaj
ErrorCode	string	Dönen hata mesajına ait kod

JSON Request-Response (İstek-Yanıt) (Başarılı İşlem Örneği)

//Request
                                   {
                                        "payorderId": "test123456789",
                                        "merchantId": "5d891bbeea1e5e94b02b266b",
                                        "secretKey": "Xfur6QewXiKMHXsPJmnRrJkF"

                                        }

//Response
                                    {
                                        "TransactionId": "test123456789",
                                        "SystemTime": 1758713039283,
                                        "Success": true,
                                        "MessageCode": "00",
                                        "Message": "Başarılı",
                                        "UserMessage": "İşleminiz başarıyla gerçekleştirildi.",

                                    }

İade SERVİSİ

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/refund/v1/create/refund

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/refund/v1/create/refund

İade servisi ertesi gün işlemlerde çalışmaktadır, aynı gün içinde iade işlemi yapılmaz. İade servisinde, request bilgisinde TransactionId, secretKey, description, status ve MerchantId gönderilmektedir. İşlem başarılı olduğunda, response kısmında iade edilecek işlemin bilgileri bulunmaktadır ve bu sırada payinall'a istek düşmektedir. İade işlemi payinall tarafından onaylandığında işlem iade edilmiş olmaktadır.

Servise Gönderilmesi Gereken Parametreler

Parametre İsmi	Tip	Zorunluluk	Açıklama
payorderId	string	Evet	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin sipariş numarası
merchantId	string	Evet	Üye iş yerini belirten benzersiz bir numara
secretKey	string	Evet	Üye iş yerini belirten benzersiz bir numara
makerDescription	string	Evet	İade işlemi sırasında gönderilen açıklama bilgisi
status	number	Evet	İade işlemi olduğunu belirten statu bilgisi

Servisten Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
status	String	İşlemin başarılı ya da başarısız olma durumunda dönen sonuç
approval	string	üye iş yerinin iade ettiği işlem bilgisi
Message	string	Girilen bilgiler doğrultusunda servisten dönen mesaj

JSON Request-Response (İstek-Yanıt)

//Request
                                    
                                    {
                                        "payorderId": "test123456789",
                                        "merchantId": "5d891bbeea1e5e94b02b266b",
                                        "secretKey": "Xfur6QewXiKMHXsPJmnRrJkF",
                                        "makerDescription": "iade ödemesi deneme"
                                        "status": 4

                                        }

//Response
                                    {
                                        "status": "OK",
                                        "approval": 
                                        {
                                        "makerDescription": "deneme",
                                        "type": 4,
                                        "payorderId": "68cbd131bf1566a23cddd6b6",
                                        "merchantId": "687f626b3c88616d096815ef",
                                        "active": true,
                                        "_id": "68d3d7308e71e8f44007b005",
                                        "dateCreate": "2025-09-24T11:34:08.749Z",
                                        "__v": 0
                                        },
                                        "message": "İade Talebiniz Payinall'a Düşmüştür",
                                    }

İade SERVİSİ

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/refund/refundMerchantUser/v1

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/refund/refundMerchantUser/v1

İade servisi ertesi gün işlemlerde çalışmaktadır, aynı gün içinde iade işlemi yapılmaz. İade servisinde, request bilgisinde TransactionId ve MerchantId gönderilmektedir. İşlem başarılı olduğunda, response kısmında iade edilecek işlemin bilgileri bulunmaktadır ve bu sırada payinall'a istek düşmektedir. İade işlemi payinall tarafından onaylandığında işlem iade edilmiş olmaktadır.

Servise Gönderilmesi Gereken Parametreler

Parametre İsmi	Tip	Zorunluluk	Açıklama
TransactionId	string	Evet	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin sipariş numarası
MerchantId	string	Evet	Üye iş yerini belirten benzersiz bir numara

Servisten Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
Success	boolean	İşlemin başarılı ya da başarısız olma durumunda dönen sonuç
TransactionId	string	üye iş yerinin sipariş numarası
MessageCode	string	Dönen mesaja ait kod
Message	string	Girilen bilgiler doğrultusunda servisten dönen mesaj
UserMessage	string	Dönen yanıta ait kullanıcıya yönelik mesaj

JSON Request-Response (İstek-Yanıt)

//Request
                                    
                                    {
                                        "TransactionId": "test123456789"
                                        "MerchantId": "5d891bbeea1e5e94b02b266b"
                                    }

//Response
                                    {
                                        "status": "1",
                                        "Message": "İşlem zaten bekleme listesinde",
                                    }

//Request
                                    {
                                        "TransactionId": "test123456789"
                                        "MerchantId": "5d891bbeea1e5e94b02b266b"
                                    }

//Response
                                    {
                                        "status": "OK",
                                        "Message": "İşlem zaten bekleme listesinde",
                                    }

İşlem Listeleme Servisi

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/transaction/PayorderInfo

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/transaction/PayorderInfo

Yapılan satış, iptal, iade işlemlerinin başarılı ya da başarısız olma durumlarını öğrenmek için kullanılan servistir. Request kısmında token, başlangıç ve bitiş tarihleri MerchantId ve status bilgileri gönderilmektedir.

Servise Gönderilmesi Gereken Parametreler

Parametre İsmi	Tip	Zorunluluk	Açıklama
token	string	Evet	login olma servisinde oluşturulan token bilgisi
merchantID	string	Evet	Üye iş yerini belirten benzersiz bir numara
statustype	string	Hayır	işlemin başarılı ya da başarısız olma durumunu gösteren bilgi. Başarılı işlem için 0 başarısız işlem için 1 gönderilir.
startDate	string	Evet	Filtreleme için gönderilen başlangıç tarihi
endDate	string	Evet	Filtreleme için gönderilen bitiş tarihi

Servisten Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
data	array	işlemleri gösterir
totaltransaction	number	yapılan toplam işlem sayısı
successtransaction	number	yapılan toplam başarılı işlem sayısı
successrefund	number	yapılan başarılı iade sayısı
successcancel	number	yapılan başarılı iptal sayısı
totalrefund	number	günlük işlem tutarı
netsale	number	günlük net işlem tutar
footertotal	number	toplam tutar
footercount	number	toplam işlem sayısı

JSON Request-Response (İstek-Yanıt)

//Request
                                    
                                    {
                                        "endDate": "2022-07-05T23:59:59.999Z"
                                        "startDate": "2022-07-05T00:00:00.000Z"
                                        "token": "2528e2b0c4cf385b3b9e611d24445d848867be2225bf07154fe265b039a6daas"
                                        "statustype": 0
                                        "merchantId": "622b62b5cf936dbdda1b775v"
                                    }

//Response
                                        {
                                            "data": [
                                            {
                                              "PfTotalRate": 1.6
                                              "GatewayId": "5db0147d2dcad11632c4675b
                                              "OrderId": "PjjmajFk8kF1I1uR4GGH
                                              "Status": 7
                                              "Currency": "TRY"
                                              "Installment": "1"
                                              "PaymentChannel": "payinall"
                                              "Amount": 400
                                              "TotalFee": 1.1
                                              "TotalPay": 1
                                              "DateUpdate": "05-07-2022 10:58:30"

                                            }
                                        ],
                                            "totaltransaction": 3,
                                            "successtransaction": 2,
                                            "successrefund": 1,
                                            "totalsale": 1300,
                                            "totalrefund": 400,
                                            "netsale": 900,
                                            "footercount": 3,
                                            "footertotal": 1700,
                                        }

Logın Servisi

Servis Adresi:

Test Ortam Adresi:

https://payinallpostestapi.erpapay.com/api/oauth/token

Gerçek Ortam Adresi:

https://payinallposapi.erpapay.com/api/oauth/token

Login servisine kullanıcı adı ve şifre gönderilerek sonucunda token oluşmaktadır.

Servise Gönderilmesi Gereken Parametreler

Parametre İsmi	Tip	Zorunluluk	Açıklama
grant_type	string	Evet	Standart olarak "password" gönderilir.
client_id	string	Evet	Standart olarak "wepApi" gönderilir.
client_secret	string	Evet	İstek esnasında gönderilen ve yanıtta döndürülen üye iş yerinin sipariş numarası
username	string	Evet	Kullanıcı adı gönderilmektedir.
password	string	Evet	Şifre gönderilmektedir.

Servisten Gelen Yanıta Ait Parametreler

Parametre İsmi	Tip	Açıklama
access_token	string	üye iş yerinin token bilgisi
expires_in	number	oluşan token süresi
sms_authentication	boolean	sms doğrulamasının olup olmadığını gösterir
count	number	yanlış istek atma sayısı
lastTryDate	string	en son yanlış istek atma tarihi
token_type	string	oluşan token tipi

JSON Request-Response (İstek-Yanıt)

//Request
                                   {
                                        "grant_type": "password"
                                        "client_id": "wepApi"
                                        "client_secret": "erparaclientsecret"
                                        "username": ""
                                        "password": ""
                                   }

//Response
                                    {
                                        "access_token": "caacf028cd63e039c561a4f4f4e9f79d9a879fe679607a153c3708129d089b5b",
                                        "expires_in": 3600,
                                        "sms_authentication": true,
                                        "count": 0,
                                        "lastTryDate": " ",
                                        "token_type": "Bearer",
                                    }

Üye İşyeri / Müşteri Numarası	Secret Key	Kart Numarası	Tarih	CVV	3D Şifre
687f626b3c88616d096815ef	Xfur6QewXiKMHXsPJmnRrJkF	4876125794792381	12/30	999	000000

ÖRNEK KODLAR - Signature Oluşturma

                                        

                                     {
                                         
                                            $time = time(); //unix time 
                                            $secret_key =  "HCxZAa9tCkLP2N6JjgGbKA9R";
                                            $merchant_id =  "606f0f2072f1094060ebb6b6";
                                            $transaction_id =  uniqid();
                                            $transaction_time =  $time; 
                                            $transaction_amount =  350;
                                            $transaction_currency =  "TRY";
                                            $transaction_installment =  "2";
                                            $transaction_CardNumber =  "4691810771946876";
                                            $holded =  $secret_key . $merchant_id . $transaction_id . $transaction_time . strval($transaction_amount) . 
                                            $transaction_currency . $transaction_installment . $transaction_CardNumber;
                                            $secretRESULTkey =  bin2hex(hash_hmac('SHA512', $holded, $secret_key, true));

                                     }



                                    const crypto = require('crypto'); //npm install crypto --save
                                    let secretKey = "HCxZAa9tCkLP2N6JjgGbKA9R";
                                    let merchantId = "606f0f2072f1094060ebb6b6";
                                    let transaction = 
                                    {
                                                    Amount: "100",
                                                    Currency: "TRY",
                                                    Installment: "1",
                                                    MerchantId: merchantId,
                                                    TransactionId: make_transaction_id(15),
                                                    TransactionTime: nowDate.getUnixTime(),
                                                    CardNumber: "4691810771946876"
                                   }
                                   let word = secretKey.toString() + transaction.MerchantId + transaction.TransactionId + transaction.TransactionTime + 
                                   transaction.Amount.toString() + transaction.Currency + transaction.Installment + transaction.CardNumber;
                                   let signature = crypto.createHmac('SHA512', secretKey.toString()).update(word).digest('hex').toString('base64');



                                    /** HashingHelper Sınıfını eklediğinizi varsayarsak */
                                    
                                    public static string CreateParemeterMessage(string secretKey,PaymentRequest paymentRequest)
                                    {       
                                        return secretKey + paymentRequest.MerchantId + paymentRequest.TransactionId +paymentRequest.TransactionTime+ 
                                            paymentRequest.Amount
                                            + paymentRequest.Currency + paymentRequest.Installment + paymentRequest.CardNumber;
                                    }
                                    public static string CreateHash512(string secretKey,string paremeterMessage)
                                    {
                                        var stringBuilder = new StringBuilder(); ;
                                        byte[] secretkeyBytes = Encoding.UTF8.GetBytes(secretKey);
                                        byte[] paremeterBytes = Encoding.UTF8.GetBytes(paremeterMessage);
                                        using (var hmac512 = new HMACSHA512(secretkeyBytes))
                                        {
                                            byte[] hashValue = hmac512.ComputeHash(paremeterBytes);
                                            foreach (var value in hashValue)
                                            {
                                                stringBuilder.Append(value.ToString("x2"));
                                            }
                                        }
                                        return stringBuilder.ToString();
                            
                                     }

                                    const string SecretKey = "HCxZAa9tCkLP2N6JjgGbKA9R";
                                    const string MerchantId = "606f0f2072f1094060ebb6b6";
                                  
                                    var paremeterMessage = HashingHelper.CreateParemeterMessage(SecretKey, paymentRequest);
                                    paymentRequest.Signature = HashingHelper.CreateHash512(SecretKey, paremeterMessage);




                                    let secret_key = "HCxZAa9tCkLP2N6JjgGbKA9R";
                                    let merchant_id = "606f0f2072f1094060ebb6b6";
                                    let transaction_id = make_transaction_id(15);
                                    let transaction_time = Math.round(new Date().getTime() / 1000);
                                    let transaction_amount = "100";
                                    let transaction_currency = "TRY";
                                    let transaction_installment = "1";
                                    let transaction_CardNumber = "4691810771946876";
                                    let word2 = secret_key.toString() + merchant_id + transaction_id + transaction_time + 
                                    transaction_amount.toString() + transaction_currency + transaction_installment + transaction_CardNumber;
                                    let hash = sha512.hmac.create(secret_key.toString());
                                    hash.update(word2);

payinall Entegrasyon Rehberi