Sipariş Oluşturma

Base url : https://api.paymago.com/api

3D Ödeme Servisi İstek Modeli;

Create Order

POST /pos/createOrder

Aşağıda, bir sipariş oluşturmak için kullanılacak API isteği detayları yer almaktadır. Bu bilgiler, POST isteği ile gönderilecektir.

Headers

Name
Value

Content-Type

application/json

Authorization

Bearer <token>

Body

Parametre
Tür
Zorunlu
Açıklama

amount

String

Evet

İşlemin tutarını belirtir.

currencyCode

String

Evet

İşlemin para birimi kodunu belirtir (Örneğin, Türk Lirası için "949").

orderId

String

Evet

Sipariş kimliğini temsil eder. Her sipariş için benzersiz olmalıdır.

installment

String

Hayır

Taksit sayısını belirtir. Taksitsiz işlem için boş bırakılabilir.

cardHolderName

String

Evet

Kart sahibinin adını belirtir.

cardNumber

String

Evet

Kart numarasını belirtir.

expireYear

String

Evet

Kartın son kullanma yılını belirtir.

expireMonth

String

Evet

Kartın son kullanma ayını belirtir.

cvc

String

Evet

Kartın güvenlik kodunu (CVC) belirtir.

saleProduct

String

Evet

Satılan ürünün adını belirtir.

saleProductPrice

String

Evet

Satılan ürünün fiyatını belirtir.

saleDescription

String

Hayır

Satılan ürünle ilgili kısa bir açıklama sağlar.

isSecureTransaction

Boolean

Evet

İşlemin güvenli olup olmadığını belirtir. Genellikle 3D Secure gibi güvenlik önlemlerini ifade eder.

callbackUrl

String

Evet

İşlem sonucunun bildirileceği URL'yi belirtir.

Bu parametrelerin her birinin doğru ve eksiksiz bir şekilde doldurulması, sipariş oluşturma işleminin başarılı bir şekilde tamamlanmasını sağlar. Özellikle zorunlu alanların doldurulması, işlemin geçerli olması için kritik öneme sahiptir.

Response

{ 
      // LINK GELDIGI DURUMDAKI RESPONSE
  "data": {
        "responseMessage": "(TR) - işlem başarılı - 43061",
        "orderId": "5555eeee67776666888555",
        "returnUrl": "https://bank.example.com/3d-secure-authentication",
        "errorCode": null,
        "status": "SUCCESS",
        "paymentId": "5555eeee67776666888555",
        "paymentData": null,
        "returnType": "1"
    },
    "success": "true",
    "message": null,
    "resultCode": "0000"
}

3D Ödeme Servisi İşlem Akışı;

3D ödeme modelini kullanarak başarılı bir ödeme gerçekleştirebilmek için, entegrasyon sürecinizi aşağıda listelenen adımları izleyerek tamamlamanız gerekmektedir.

1. Adım:

Üye işyeri, kart bilgileri, sepet detayları, ödeme tutarı ve taksit bilgilerini, ayrıca ödemenin sonucunun bildirilmesini istediği web adresi (BACK_URL) ile birlikte yukarıda belirtilen istek modelini kullanarak 3D ödeme servisine gönderir ve böylece sipariş oluşturma sürecini başlatır.

İşlemlerin güvenli ve sorunsuz bir şekilde gerçekleştirilebilmesi ve dolandırıcılık işlemlerinin önlenebilmesi için tüm parametrelerin eksiksiz olarak gönderilmesi gerekmektedir.

Servise gönderilecek örnek bir JSON dosyası şu şekildedir;

{
  "amount": "150.00",
  "currencyCode": "949",
  "orderId": "ORD123456",
  "installment": "",
  "cardHolderName": "John Doe",
  "cardNumber": "4111111111111111",
  "expireYear": "2025",
  "expireMonth": "12",
  "cvc": "123",
  "saleProduct": "Smartphone",
  "saleProductPrice": "150.00",
  "saleDescription": "Latest model smartphone",
  "isSecureTransaction": true,
  "callbackUrl": "https://example.com/callback"
}

orderId değeri her işlem için benzersiz olmalı ve string formatında GUID (Globally Unique Identifier) olarak gönderilmelidir. Bu, işlemlerin doğru şekilde takip edilebilmesi ve karışıklıkların önlenmesi için gereklidir.

Hint: GUID oluşturmak için aşağıdaki kod örneğini kullanabilirsiniz (C# için):

string orderId = Guid.NewGuid().ToString();

2. Adım

API, üye iş yerinden gelen işlem bilgilerini değerlendirerek yanıt mesajını gönderir.

Sipariş oluşturma Servisi Cevap Mesajı Parametreleri

Parametre
Tip
Zorunlu
Kaynak
Açıklama

ResponseMessage

String

Hayır

Sistem

İşlem sonucuyla ilgili genel bir yanıt mesajını belirtir. Bu mesaj, işlem sonucunu kullanıcıya iletmek için kullanılır.

OrderId

String

Evet

Kullanıcı

Kullanıcı tarafından sağlanan benzersiz sipariş kimliği. İşlemin hangi siparişle ilişkili olduğunu belirtir.

ReturnUrl

String

Hayır

Sistem

İşlem sonrasında kullanıcının yönlendirileceği URL'yi belirtir. Genellikle başarılı ödeme sonrası kullanılan geri dönüş URL'sidir.

ErrorCode

String

Hayır

Sistem

İşlem sırasında oluşan bir hata varsa, bu kod hata türünü belirtir. Örneğin, ödeme reddedildiğinde bir hata kodu döner.

Status

String

Hayır

Sistem

İşlemin durumunu belirtir. Örneğin, "Başarılı", "Başarısız" gibi işlem durumu bilgileri dönebilir.

PaymentId

String

Hayır

Sistem

Ödeme işlemi için sistem tarafından oluşturulan benzersiz kimlik. Bu kimlik, işlem kaydının takibi için kullanılır.

PaymentData

String

Hayır

Sistem

Secure gibi ek doğrulama bilgilerinin saklanabileceği bir alan olabilir.

ReturnType

İnt

Hayır

Sistem

İşlem sonrasında kullanıcıya sunulacak geri dönüş türünü belirtir. 1 HTML, 2 URL olarak tanımlanmıştır.

Yanıt mesajı içinde, işlemin sonucunu belirten ReturnType alanı yer alır. ReturnType değerine göre kullanıcının nasıl yönlendirileceği aşağıda açıklanmıştır:

ReturnType Değerlerine Göre Yönlendirme

ReturnType = 1

  • Açıklama: Bu değer, kullanıcının 3D Doğrulama Sayfasına yönlendirilmesi gerektiğini belirtir.

  • Eylem: Size bir URL dönecektir. Bu URL'yi kullanarak kullanıcıyı 3D Doğrulama Sayfasına yönlendirmelisiniz. Bu durumda PaymentData değişkeni "null" olarak dönecektir.

ReturnType = 2

  • Açıklama: Bu değer, kullanıcının bankanın 3D doğrulama iframe'ini içeren bir HTML sayfası ile doğrulama yapması gerektiğini belirtir.

  • Eylem: Size ham HTML verisi dönecektir. Bu HTML verisini kullanıcıya göstermeniz gerekmektedir. Bu durumda ReturnUrl değişkeni "null" olarak kabul edilir.

Link veya HTML iFrame değerini kullanabilmek için iki farklı konfigürasyon yapmanız gerekmektedir.

PreviousAuthorizationNextSipariş Sonlandırma

Last updated