HepsipayFrameInit

Üye iş yerinin Hepsipay ile ödeme akışını başlatma noktası olup Hepsipay ile Ödeme ekranını Hosted veya Redirected (Common Payment Page) olarak çağırmak için tetiklenen servistir. Üye iş yeri ödeme akışını başlatabilmek için gerekli ön bilgileri bu servis üzerinden gönderir.

Üye işyerinin Hepsipay ile ödeme akışını başlatma noktasıdır.

Endpoint

/v2/hepsipayframe/init

Method Type

POST

Request Example

Example Request:

{
    "Amount": 1200,
    "AccountKey": "905551112233",
    "MerchantCallBackUrl": "https://www.Hepsipay.com",
    "BasketItems": [
{
    "Product": "Çikolata",
    "Price": 1200,
    "SubMerchantMemberId": 2,
    "SubMerchantMemberPrice": 100,
    "ExternalId": "12345",
    "CategoryId": "987"
}
    ],
    "IsGuestUser": false,
    "Force3ds": false,
    "AllowedInstallments": [1,2,3],
    "MerchantOrderNumber": "1234",
    "FrameType": 1,
    "CheckoutMerchantUrl": "test.com/checkout/cart",
    "BankOrderId": "f5135f15-5484-4312-8591-ba8d94557dde",
    "PosAlias": "GARANTI",
    "ExternalId": "cdfd292d-5111-4f18-9141-4df1860fb20c"
}

İşyeri ödeme için akışı başlatmak için gerekli ön bilgileri bu servise gönderir.

InputName

Type

Required

Description

Amount

int

Tutar bilgisi

AccountKey

string

İşlem yapılan gsm no veya email bilgisidir. GSM formatı 905551112233 olmalıdır. Farklı bir GSM formatı ile istek atıldığında format hatası verilmektedir.

MerchantCallBackUrl

string

İşlem sonucunun üye işyerine iletilmesi için gerekli link bilgisi.

Bu url ile gönderilecek hepsipay tarafından gönderilecek payload şu şekilde olmalı : payload: {MerchantOrderNumber: string, token: string}

BasketItems

List<Product>

Sepet içerisindeki ürün bilgileri(Sepet içerisindeki toplam değer price amount a eşit olmalıdır).

OutputName	Type	Required	Description
Product	string	M	Ürün bilgisi
Price	int	M	Ürün tutar bilgisini içerir. Provider Craftgate olan üyeişyerleri bu değeri pozitif bir değer olarak göndermelidir.
SubMerchantMemberId	int	O	Merchant bir pazar yeri ise satıcının Craftgate üye ID zorunludur.
SubMerchantMemberPrice	int	O	Merchant bir pazaryeri ise sepete eklenen ürün için satıcının hakediş tutarı bilgisi zorunludur.
CategoryId	string	M	Merchant tarafında satılan ürünün kategori identity bilgisidir. Örnek: "0002131" Kodu: 0002131 Kategori Kodu Açıklaması: Tekstil
ExternalId	string	O	İlgili ürün ya da hizmeti ifade eden dış ID değeri. Genellikle üye işyeri sistemind e bu kırılıma ilişkin ID değeri kullanılır.

IsGuestUser

bool

Kullanıcı misafir(üye işyeri sistemine giriş yapmamış) ise bu alan true gönderilmelidir. IsGuestUser “T” olarak gönderildiğinde hep tek seferlik session token üretiriz ve kullanıcı/müşteri her geldiğinde sms otp doğrulaması Hepsipay tarafından yapılır.

Hepsipay tarafında ilk kez registered olarak gelen(IsGuestUser : True) ve ilk kez SMS OTP ile doğrulama yapıldıktan sonra Hepsipay tarafında tutulan “AccountAlreadyLinked” değeri True olarak setlenir ve bu bilgi CheckAvailability servisinde de response’ta dönülür. )

Ancak IsGuestUser : “False” gönderilirse, kullanıcı ilk kez geldiğinde SMS OTP ile doğrulama bir kere yapılır ve bu doğrulama 90 gün boyunca geçerli olur ve tekrar doğrulama yaptırılmaz.

Force3ds

bool

Üye işyeri ödeme adımının 3d ile gerçekleşmesini istiyorsa bu alan true gönderilmelidir.

AllowedInstallments

List <int>

Üye işyerinin izin vermiş olduğu taksit sayıları.

MerchantOrderNumber

string

Üye işyerine ait sipariş numarası.

FrameType

int

Frame tipidir. Default değeri frameType:1 (hosted)'dır.

FrameType: 1 (hosted - Merchant checkout ekranın içine render olacak şekilde stiller uygulanır.)

FrameType: 2 (redirected (Common Payment Page) - Merchant checkout ekranında render olmaz harici sayfada ödeme alınır.)

CheckoutMerchantUrl

string

Merchant'ın ödeme sayfasının adres bilgisidir. FrameType : 2 (redirected) olduğunda gönderimi zorunludur.

BankOrderId

string

Merchant’ın bankaya iletilmesini istediği unique bilgidir. Şipariş numarası gibi bilgiler bu alanda gönderilebilir.

PosAlias

string

Her bir işlemi istediği postan geçirebilmek üzere bu alan kullanılmalıdır. Buraya geçilecek bilgi ile servis providerda tanımlı POS Alias bilgilerinin uyuşuyor olmasına dikkat edilmelidir.

ExternalId

string

İşyeri tarafından belirlenebilecek external bir değerdir. Genellikle poliçe/teklif numarası gibi bilgilere sahip olan işyerleri tarafından kullanılabilecek bir değerdir. Eğer bu değer girilmiş ve servise provider Craftgate ise Craftgate’deki external id’ye karşılık gelir. Alan doldurulursa, bu değer Craftgate üye işyeri panelinden “externalid” alanından izlenebilir. Kullanılmazsa Craftgate’de Hepsipay tarafından oluşturulmuş HP referans numarası izlenebilir.

MerchantExternalCustomerId

string

Sadece provider’ı Payten olan üyeişyerleri için zorunludur. Enterprise dışındaki diğer üyeişyerleri bunu dummy bir değer olarak gönderebilir.

Description

Example Response:

{
    "FrameUrl": "https://pf-ui-pwh-qa.hepsipay.com?token=F164B6A4D6C1C6338F2FCE1BBBFB9852988C6BE5C5C998244608527EC42CB17D2AC9AE918FF99D8D83A5447F8668F8A2&refId=D30C590EA4C4D119D362C8AFFCDBCB82&merchantId=89ca9383-cf52-12cd-1047-14e25bc71393&hasRefId=false",
    "Token": "F164B6A4D6C1C6338F2FCE1BBBFB9852988C6BE5C5C998244608527EC42CB17D2AC9AE918FF99D8D83A5447F8668F8A2",
    "FrameType": 1,
    "Success": true,
    "MessageCode": "0000",
    "Message": "İşlem Başarıyla Gerçekleştirildi.",
    "UserMessageTitle": "Tebrikler!",
    "UserMessage": "İşlem Başarıyla Gerçekleştirildi."
}

OutputName	Type	Description
FrameUrl	string	Yüklenecek frame linki
Token	string	Sorgulamalarda kullanabilecek işlem tokenidir.
FrameType	string	Frame tipidir. Default değeri frameType:1 (hosted)'dır.
Success	string	Default alanlarımızdandır. İşlemin başarılı gerçekleşip gerçekleşmediği bilgisidir.
MessageCode	string	Default alanlarımızdandır. Request’in sonucu success:true ise o halde 000 değeri gelecektir. Aksi taktirde Hepsipay sistemi tarafından uygun hata kodları dönecektir. İşlemin başarısız olduğunda hangi hata kodu ile sonlandığını belirtir.
Message	string	Default alanlarımızdandır. Hepsipay tarafından hata koduna bağlı olarak hata mesajı olarak dönülmektedir.
UserMessageTitle	string	Default alanlarımızdandır. User’a verilecek mesajın başlık bilgisidir.Genelde null değeri dönecektir.
UserMessage	string	Default alanlarımızdandır. User’a verilmesi istenen hata mesajıdır.

Örnek Kodlar

try {
 
        $header = ["Content-Type: application/json"];
        $header = ["merchant-no: XXXXX"]; // Hepsipay tarafından iletilir.
        $header = ["terminal-no: YYYYY"]; // Hepsipay tarafından iletilir.
        $header = ["signature-no: e74ef7c4994cd3f5ff03f89a310cda8bcf29af12a39ebf1e7dbf27c99efe3784eb5eaaf4f535d666eb513620c8b66ec483a2dfa281c85bc2bb8ff18518f5cdf2"];
 
        $data_string = '{"Amount":1000,"AccountKey":"905998868296","MerchantCallBackUrl":"http:\/\/hepsipaysdk.entegrasyon.alttantire.local\/examples\/payment_result.php","BasketItems":[{"Product":"\u00c7ikolata","Price":500,"SubMerchantMemberId":null,"SubMerchantMemberPrice":null,"CategoryId":"3","ExternalId":"10"},{"Product":"\u00c7ikolata","Price":500,"SubMerchantMemberId":null,"SubMerchantMemberPrice":null,"CategoryId":"3","ExternalId":"10"}],"AllowedInstallments":[1,2,3],"FrameType":1,"MerchantOrderNumber":"1234-56797","BankOrderId":"ABC-123-4567","ExternalId":"EXT-ID-123-4567"}';
 
        $ch = @curl_init("https://merchantpfpayment-gateway-qa.hepsipay.com/v2/hepsipayframe/init");
 
        @curl_setopt($ch, CURLOPT_POST, true);
        @curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
        @curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
        @curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        @curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
        @curl_setopt($ch, CURLOPT_TIMEOUT, 10); //timeout in seconds
 
        $result = curl_exec($ch);
 
        if (@curl_errno($ch)) {
        $error_msg = curl_error($ch);
        @curl_close($ch);
        throw new Exception($error_msg);
    } else {
 
        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        $header = substr($result, 0, $header_size);
        $body = substr($result, $header_size);
 
        if ($http_code === 401) {
        throw new Exception("Yetkisiz Erişim. " . $http_code);
    }
 
        $data = json_decode($result);
        @curl_close($ch);
 
        return $data;
 
    }
 
} catch (Exception $e) {
    throw new Exception($e->getMessage());
}

iFrame olarak Kullanım

Eğer işyeri mevcut checkout ekranlarında Hepsipay ile Ödemeyi alternatif bir ödeme yöntemi olarak sunmak istiyor ise o halde HepsipayFrameInit servisini çağırırken FrameType : 1 olarak geçmelidir. Bu değer geçilmese de default olarak “1” değeriyle frame init olur. İşyerinin kendi checkout sayfasında embedded şekilde Hepsipay Frame’inin yerleştirilmesi sağlanmalıdır. Bu seçenekle ilerlendiğinde UI/UX organizasyonu işyeri tarafından yapılmalıdır.

(UI/UX entegrasyonu konusunda daha detaylı bilgi için dokümandaki “Hepsipay Frontend / UI Entegrasyonu – WEB SDK” ve “Hepsipay Frontend / UI Entegrasyonu – Embed Iframe with JS Events” başlıklarını inceleyebilirsiniz.)

Common Payment Page (Redirected) olarak Kullanım

Eğer işyerinin bir checkout sayfası yok ve hepsipay frame’i ana ödeme sayfası olarak görüntülemek istiyorsa (yani alternatif bir ödeme seçeneği değil ana ödeme yapısı olarak Hepsipay’in ekranlarının açılması isteniyorsa) o halde işyeri, ödemenin alınacağı sayfada önce “Checkavailability” servisi çağrılır ve bu servis sonucunda “true” değer alınmışsa sonrasında HepsipayFrameInit servisini çağırmalıdır. HepsipayFrameInit servisini çağırırken FrameType : 2 olarak geçilmelidir.

Bu şekilde FrameType : 2 olarak çağrılan HepsipayFrameInit servis sonucunda gelen URL direkt olarak redirect edilerek yeni bir pencerede açılacaktır. Bu yöntem (Common Payment Page) sadece Web Browser üzerinden kullanılabilmektedir, native mobil uygulama üzerinde kullanılamayacaktır (mobilde browser üzerinden açılan web uygulaması değilse).

Common Payment Page yöntemiyle açılan Hepsipay ödeme sayfasında kullanıcının ödemeyi sonlandırması (başarılı/başarısız) sonucunda, Hepsipay ödeme sayfası kapatılır ve “CheckoutMerchantUrl” parametresi ile belirtilen adrese (sipariş özeti sayfası vb.) yönlendirilir. Yine bu yöntemle ilerlendiğinde işyerinin backend’ine ödeme sonuç bildirimi senkron olarak “MerchantCallbackURL” input parametresinde işyerinin geçtiği endpoint üzerinden yapılmaktadır.

Cüzdan Bakiyesi ile Ödeme – Common Payment Page Akış Diagramı

Kayıtlı Kartı Seçerek Ödeme – Common Payment Page Diagramı

Alışveriş Kredisi ile Ödeme – Common Payment Page Diagramı

Checkavailability Ek Servisler