Payantis VPOS

Payantis VPOS, kurumların e-ticaret veya uzaktan ödeme kanallarında kartlı ödeme kabul etmesini sağlayan sanal POS entegrasyon modülüdür. Bu API ile satış, ön otorizasyon, ön otorizasyon kapama, iptal, iade, reversal ve işlem sorgulama akışları tek bir ödeme altyapısı üzerinden yönetilir.

VPOS entegrasyonu iki ana ödeme kanalından oluşur:

3D Secure ödeme akışı: Kart hamili doğrulaması gerektiren güvenli ödeme senaryolarında kullanılır. Kurum, ödeme bilgilerini ve hash değerini gönderir; kart hamili 3D doğrulama adımına yönlendirilir. İşlem sonucu OkUrl veya FailUrl adresine dönüş/callback alanlarıyla iletilir.

Non-secure ödeme akışı: 3D Secure doğrulaması kullanılmadan ödeme veya işlem operasyonu yapılmasını sağlar. Satış, ön otorizasyon, kapama, iptal, iade ve sorgulama işlemleri TxnType değeriyle ayrıştırılır.

Temel Kavramlar

TenantCode: Multitenant yapıda işlemin hangi kurum/müşteri adına yapıldığını belirten koddur.

MerchantCode: Payantis üzerinde tanımlı üye işyeri kodudur.

TerminalCode: Sanal POS terminalini temsil eden koddur.

OrderId: Kurum tarafında üretilen benzersiz sipariş numarasıdır. İptal, iade, kapama ve sorgulama işlemlerinde referans alınır.

TxnType: İşlem tipini belirler. Auth, PreAuth, PostAuth, Void, Refund, Reversal ve Inquiry değerleri desteklenir.

SecureType: Ödemenin güvenlik modelini belirtir. 3D işlemlerde ThreeDModel veya ThreeDPay, 3D olmayan işlemlerde NonSecure kullanılır.

Hash: 3D ödeme request ve response bütünlüğünü doğrulamak için kullanılan güvenlik değeridir. SHA512 algoritması ve Base64 encoding ile üretilir.

Rnd: Hash hesaplamasında kullanılan rastgele dizedir.

TxnStatus: İşlemin VPOS yaşam döngüsü statüsüdür. Örn: Pending, Successful, Refunded, Void, Posted.

Desteklenen İşlem Tipleri

TxnType	Açıklama
`Auth`	Satış/otorizasyon işlemi yapar.
`PreAuth`	Ön otorizasyon açar; tutar daha sonra `PostAuth` ile kapatılır.
`PostAuth`	Açık ön otorizasyonu kapatır. Tutar orijinal ön otorizasyon tutarına eşit veya daha küçük olabilir.
`Void`	Uygun durumdaki işlemi iptal eder.
`Refund`	Başarılı işlem için tam veya parçalı iade başlatır. Toplam iade tutarı orijinal işlem tutarını aşmamalıdır.
`Reversal`	İşlemin ters kayıt/reversal sürecini başlatır.
`Inquiry`	Sipariş/işlem durumunu sorgular.

3D Secure Hash Hesaplama

3D ödeme request'lerinde Hash alanı zorunludur. Hash değeri aşağıdaki bilgiler pipe (|) karakteriyle birleştirilerek SHA512 algoritması ile hesaplanır ve Base64 olarak encode edilir.

Request hash sırası:

Response hash sırası:

terminalCode|orderId|rnd|procReturnCode|storeKey

Kurum, hem request gönderirken hash üretmeli hem de dönüşte gelen response hash değerini doğrulamalıdır. Bu kontrol, ödeme sonucunun gerçekten Payantis VPOS tarafından üretildiğini ve dönüş verisinin değiştirilmediğini teyit eder.

Endpointler

Endpoint	Amaç
`POST /api/v1/payment/3d-secure`	3D Secure ödeme başlatır. ThreeDModel veya ThreeDPay akışlarında kullanılır.
`POST /api/v1/payment/non-secure`	Non-secure satış, ön otorizasyon, kapama, iptal, iade, reversal ve sorgulama işlemlerini yürütür.

Test Ortamı

3D işlemler: https://staging-vpos-gateway.payantis.io/

Non-3D işlemler: https://staging-vpos.payantis.io/

Test üye işyeri bilgileri entegrasyon sırasında kurumla paylaşılır. Dokümandaki örneklerde TenantCode, UserName, Password, StoreKey, TerminalCode ve MerchantCode değerleri test amaçlı kullanılmıştır.

Temel Kavramlar#

Desteklenen İşlem Tipleri#

3D Secure Hash Hesaplama#

Endpointler#

Test Ortamı#

Temel Kavramlar

Desteklenen İşlem Tipleri

3D Secure Hash Hesaplama

Endpointler

Test Ortamı