3D Secure ödemeyi başlat

cURL

curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: order-1001" \
  -d '{ ...payload... }'

const res = await fetch(
  "https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Idempotency-Key": "order-1001",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ /* payload */ }),
  },
);
const data = await res.json();

import httpx
res = httpx.post(
    "https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Idempotency-Key": "order-1001",
    },
    json={ ... },
)
data = res.json()

var req = new HttpRequestMessage(HttpMethod.Post, "https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
req.Headers.Add("Idempotency-Key", "order-1001");
// Content = JsonContent.Create(payload);
var resp = await http.SendAsync(req);

req, _ := http.NewRequest("POST", "https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init", nil)
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Idempotency-Key", "order-1001")
// req.Body = bytes.NewReader(payloadJSON)
resp, _ := http.DefaultClient.Do(req)

$ch = curl_init("https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $accessToken",
    "Idempotency-Key: order-1001",
  ],
  CURLOPT_POSTFIELDS => json_encode(\$payload),
]);
$data = json_decode(curl_exec($ch), true);

HttpResponse<String> response = Unirest.post("https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": {\n    \"amount\": 15000,\n    \"currency\": \"TRY\"\n  },\n  \"installment\": 1,\n  \"card\": {\n    \"holder_name\": \"<string>\",\n    \"number\": \"<string>\",\n    \"expire_month\": \"<string>\",\n    \"expire_year\": \"<string>\",\n    \"cvv\": \"<string>\"\n  },\n  \"callback_url\": \"https://example.com/3ds/return\",\n  \"external_id\": \"ORDER-1001\",\n  \"basket_id\": \"BASKET-2026-001\",\n  \"description\": \"<string>\",\n  \"buyer\": {\n    \"id\": \"cust-001\",\n    \"name\": \"Ahmet\",\n    \"surname\": \"Yılmaz\",\n    \"email\": \"musteri@example.com\",\n    \"phone\": \"+905551112233\",\n    \"ip_address\": \"85.105.10.10\",\n    \"identity_number\": \"12345678901\"\n  },\n  \"billing_address\": {\n    \"contact_name\": \"Ahmet Yılmaz\",\n    \"city\": \"İstanbul\",\n    \"country\": \"TR\",\n    \"address\": \"Maslak Mh. ...\",\n    \"postal_code\": \"34485\"\n  },\n  \"shipping_address\": {\n    \"contact_name\": \"Ahmet Yılmaz\",\n    \"city\": \"İstanbul\",\n    \"country\": \"TR\",\n    \"address\": \"Maslak Mh. ...\",\n    \"postal_code\": \"34485\"\n  },\n  \"basket_items\": [\n    {\n      \"name\": \"Kablosuz kulaklık\",\n      \"price\": 7500,\n      \"quantity\": 2,\n      \"id\": \"SKU-001\"\n    }\n  ],\n  \"cancel_url\": \"https://example.com/checkout/cancel\",\n  \"return_url\": \"<string>\",\n  \"operation_type\": \"sale\",\n  \"extra_properties\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": {\n    \"amount\": 15000,\n    \"currency\": \"TRY\"\n  },\n  \"installment\": 1,\n  \"card\": {\n    \"holder_name\": \"<string>\",\n    \"number\": \"<string>\",\n    \"expire_month\": \"<string>\",\n    \"expire_year\": \"<string>\",\n    \"cvv\": \"<string>\"\n  },\n  \"callback_url\": \"https://example.com/3ds/return\",\n  \"external_id\": \"ORDER-1001\",\n  \"basket_id\": \"BASKET-2026-001\",\n  \"description\": \"<string>\",\n  \"buyer\": {\n    \"id\": \"cust-001\",\n    \"name\": \"Ahmet\",\n    \"surname\": \"Yılmaz\",\n    \"email\": \"musteri@example.com\",\n    \"phone\": \"+905551112233\",\n    \"ip_address\": \"85.105.10.10\",\n    \"identity_number\": \"12345678901\"\n  },\n  \"billing_address\": {\n    \"contact_name\": \"Ahmet Yılmaz\",\n    \"city\": \"İstanbul\",\n    \"country\": \"TR\",\n    \"address\": \"Maslak Mh. ...\",\n    \"postal_code\": \"34485\"\n  },\n  \"shipping_address\": {\n    \"contact_name\": \"Ahmet Yılmaz\",\n    \"city\": \"İstanbul\",\n    \"country\": \"TR\",\n    \"address\": \"Maslak Mh. ...\",\n    \"postal_code\": \"34485\"\n  },\n  \"basket_items\": [\n    {\n      \"name\": \"Kablosuz kulaklık\",\n      \"price\": 7500,\n      \"quantity\": 2,\n      \"id\": \"SKU-001\"\n    }\n  ],\n  \"cancel_url\": \"https://example.com/checkout/cancel\",\n  \"return_url\": \"<string>\",\n  \"operation_type\": \"sale\",\n  \"extra_properties\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status": "completed",
  "is_success": true,
  "message": "İşlem başarıyla tamamlandı",
  "error_code": "bank_declined",
  "provider_error_code": "51",
  "extra_properties": {}
}

{
  "type": "https://docs.payven.com.tr/errors/bad_request",
  "title": "Geçersiz istek",
  "status": 400,
  "code": "bad_request",
  "detail": "amount.amount alanı zorunlu.",
  "correlation_id": "9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8"
}

{
  "type": "https://docs.payven.com.tr/errors/invalid_token",
  "title": "Geçersiz token",
  "status": 401,
  "code": "invalid_token",
  "detail": "Access token geçersiz veya süresi dolmuş — refresh edin."
}

{
  "type": "https://docs.payven.com.tr/errors/forbidden",
  "title": "Yetki yok",
  "status": 403,
  "code": "forbidden",
  "detail": "Bu rol bu kaynağı göremez."
}

{
  "type": "https://docs.payven.com.tr/errors/idempotency_key_in_use",
  "title": "Idempotency-Key çakışması",
  "status": 409,
  "code": "idempotency_key_in_use",
  "detail": "Bu Idempotency-Key daha önce farklı bir istek gövdesi ile kullanıldı."
}

{
  "type": "https://docs.payven.com.tr/errors/bank_declined",
  "title": "Banka işlemi reddetti",
  "status": 422,
  "code": "bank_declined",
  "detail": "Yetersiz bakiye (banka kodu: 51)",
  "provider_error_code": "51"
}

{
  "type": "https://docs.payven.com.tr/errors/rate_limit_exceeded",
  "title": "İstek limiti aşıldı",
  "status": 429,
  "code": "rate_limit_exceeded"
}

{
  "type": "https://docs.payven.com.tr/errors/internal_server_error",
  "title": "Sunucu hatası",
  "status": 500,
  "code": "internal_server_error"
}

{
  "type": "https://docs.payven.com.tr/errors/connector_unavailable",
  "title": "Konnektör erişilemez",
  "status": 503,
  "code": "connector_unavailable"
}

POST

api

payments

init

cURL

curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: order-1001" \
  -d '{ ...payload... }'

const res = await fetch(
  "https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Idempotency-Key": "order-1001",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ /* payload */ }),
  },
);
const data = await res.json();

import httpx
res = httpx.post(
    "https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Idempotency-Key": "order-1001",
    },
    json={ ... },
)
data = res.json()

var req = new HttpRequestMessage(HttpMethod.Post, "https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
req.Headers.Add("Idempotency-Key", "order-1001");
// Content = JsonContent.Create(payload);
var resp = await http.SendAsync(req);

req, _ := http.NewRequest("POST", "https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init", nil)
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Idempotency-Key", "order-1001")
// req.Body = bytes.NewReader(payloadJSON)
resp, _ := http.DefaultClient.Do(req)

$ch = curl_init("https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $accessToken",
    "Idempotency-Key: order-1001",
  ],
  CURLOPT_POSTFIELDS => json_encode(\$payload),
]);
$data = json_decode(curl_exec($ch), true);

HttpResponse<String> response = Unirest.post("https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": {\n    \"amount\": 15000,\n    \"currency\": \"TRY\"\n  },\n  \"installment\": 1,\n  \"card\": {\n    \"holder_name\": \"<string>\",\n    \"number\": \"<string>\",\n    \"expire_month\": \"<string>\",\n    \"expire_year\": \"<string>\",\n    \"cvv\": \"<string>\"\n  },\n  \"callback_url\": \"https://example.com/3ds/return\",\n  \"external_id\": \"ORDER-1001\",\n  \"basket_id\": \"BASKET-2026-001\",\n  \"description\": \"<string>\",\n  \"buyer\": {\n    \"id\": \"cust-001\",\n    \"name\": \"Ahmet\",\n    \"surname\": \"Yılmaz\",\n    \"email\": \"musteri@example.com\",\n    \"phone\": \"+905551112233\",\n    \"ip_address\": \"85.105.10.10\",\n    \"identity_number\": \"12345678901\"\n  },\n  \"billing_address\": {\n    \"contact_name\": \"Ahmet Yılmaz\",\n    \"city\": \"İstanbul\",\n    \"country\": \"TR\",\n    \"address\": \"Maslak Mh. ...\",\n    \"postal_code\": \"34485\"\n  },\n  \"shipping_address\": {\n    \"contact_name\": \"Ahmet Yılmaz\",\n    \"city\": \"İstanbul\",\n    \"country\": \"TR\",\n    \"address\": \"Maslak Mh. ...\",\n    \"postal_code\": \"34485\"\n  },\n  \"basket_items\": [\n    {\n      \"name\": \"Kablosuz kulaklık\",\n      \"price\": 7500,\n      \"quantity\": 2,\n      \"id\": \"SKU-001\"\n    }\n  ],\n  \"cancel_url\": \"https://example.com/checkout/cancel\",\n  \"return_url\": \"<string>\",\n  \"operation_type\": \"sale\",\n  \"extra_properties\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://vpos-sandbox.payven.com.tr/api/v1/payments/3d/init")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": {\n    \"amount\": 15000,\n    \"currency\": \"TRY\"\n  },\n  \"installment\": 1,\n  \"card\": {\n    \"holder_name\": \"<string>\",\n    \"number\": \"<string>\",\n    \"expire_month\": \"<string>\",\n    \"expire_year\": \"<string>\",\n    \"cvv\": \"<string>\"\n  },\n  \"callback_url\": \"https://example.com/3ds/return\",\n  \"external_id\": \"ORDER-1001\",\n  \"basket_id\": \"BASKET-2026-001\",\n  \"description\": \"<string>\",\n  \"buyer\": {\n    \"id\": \"cust-001\",\n    \"name\": \"Ahmet\",\n    \"surname\": \"Yılmaz\",\n    \"email\": \"musteri@example.com\",\n    \"phone\": \"+905551112233\",\n    \"ip_address\": \"85.105.10.10\",\n    \"identity_number\": \"12345678901\"\n  },\n  \"billing_address\": {\n    \"contact_name\": \"Ahmet Yılmaz\",\n    \"city\": \"İstanbul\",\n    \"country\": \"TR\",\n    \"address\": \"Maslak Mh. ...\",\n    \"postal_code\": \"34485\"\n  },\n  \"shipping_address\": {\n    \"contact_name\": \"Ahmet Yılmaz\",\n    \"city\": \"İstanbul\",\n    \"country\": \"TR\",\n    \"address\": \"Maslak Mh. ...\",\n    \"postal_code\": \"34485\"\n  },\n  \"basket_items\": [\n    {\n      \"name\": \"Kablosuz kulaklık\",\n      \"price\": 7500,\n      \"quantity\": 2,\n      \"id\": \"SKU-001\"\n    }\n  ],\n  \"cancel_url\": \"https://example.com/checkout/cancel\",\n  \"return_url\": \"<string>\",\n  \"operation_type\": \"sale\",\n  \"extra_properties\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status": "completed",
  "is_success": true,
  "message": "İşlem başarıyla tamamlandı",
  "error_code": "bank_declined",
  "provider_error_code": "51",
  "extra_properties": {}
}

{
  "type": "https://docs.payven.com.tr/errors/bad_request",
  "title": "Geçersiz istek",
  "status": 400,
  "code": "bad_request",
  "detail": "amount.amount alanı zorunlu.",
  "correlation_id": "9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8"
}

{
  "type": "https://docs.payven.com.tr/errors/invalid_token",
  "title": "Geçersiz token",
  "status": 401,
  "code": "invalid_token",
  "detail": "Access token geçersiz veya süresi dolmuş — refresh edin."
}

{
  "type": "https://docs.payven.com.tr/errors/forbidden",
  "title": "Yetki yok",
  "status": 403,
  "code": "forbidden",
  "detail": "Bu rol bu kaynağı göremez."
}

{
  "type": "https://docs.payven.com.tr/errors/idempotency_key_in_use",
  "title": "Idempotency-Key çakışması",
  "status": 409,
  "code": "idempotency_key_in_use",
  "detail": "Bu Idempotency-Key daha önce farklı bir istek gövdesi ile kullanıldı."
}

{
  "type": "https://docs.payven.com.tr/errors/bank_declined",
  "title": "Banka işlemi reddetti",
  "status": 422,
  "code": "bank_declined",
  "detail": "Yetersiz bakiye (banka kodu: 51)",
  "provider_error_code": "51"
}

{
  "type": "https://docs.payven.com.tr/errors/rate_limit_exceeded",
  "title": "İstek limiti aşıldı",
  "status": 429,
  "code": "rate_limit_exceeded"
}

{
  "type": "https://docs.payven.com.tr/errors/internal_server_error",
  "title": "Sunucu hatası",
  "status": 500,
  "code": "internal_server_error"
}

{
  "type": "https://docs.payven.com.tr/errors/connector_unavailable",
  "title": "Konnektör erişilemez",
  "status": 503,
  "code": "connector_unavailable"
}

Authorizations

Authorization

string

header

required

Identity servisinden alinan Keycloak JWT. Format: Authorization: Bearer <token>. Token alma: POST /api/v1/auth/{slug}/token

Body

application/json

3D Secure ödeme başlatma isteği. CreatePaymentRequest ile aynı alanlara ek olarak callback/return/cancel URL'leri taşır.

amount

object | null

required

İşlem tutarı (kuruş + currency).

Show child attributes

installment

integer<int32>

required

Taksit sayısı. 1 = peşin.

Example:

1

card

object | null

required

Kart bilgileri.

Show child attributes

callback_url

string | null

required

Zorunlu. 3DS doğrulaması sonrası bankanın kullanıcıyı geri yönlendireceği HTTPS URL'iniz. Buradan gelen transaction_id ile /payments/3d/complete çağrılır.

Example:

"https://example.com/3ds/return"

external_id

string | null

Sizin sipariş kimliğiniz.

Example:

"ORDER-1001"

basket_id

string | null

Sepet kimliği.

Example:

"BASKET-2026-001"

description

string | null

buyer

object | null

Müşteri bilgileri — fraud sinyalleri ve banka risk skoru için.

Show child attributes

billing_address

object | null

Adres bilgisi (fatura veya teslimat).

Show child attributes

shipping_address

object | null

Adres bilgisi (fatura veya teslimat).

Show child attributes

basket_items

object[] | null

Show child attributes

cancel_url

string | null

Müşteri 3DS akışını iptal ederse yönlendirileceği URL.

Example:

"https://example.com/checkout/cancel"

return_url

string | null

Sonuç sayfasına yönlendirme için (success/fail unified). callback_url farklı sebeple kullanılır.

operation_type

enum<string>

sale (varsayılan) veya pre_auth.

Available options:

Sale,

PreAuth,

PostAuth,

Void,

Refund,

Recurring

Example:

"sale"

extra_properties

object | null

Konnektör-spesifik özel alanlar.

Show child attributes

Response

Option 1
Option 2

Yazma operasyonlarından (POST /payments, /refund, /void, /capture) dönen sonuç.

transaction_id

string<uuid>

required

Payven tarafından atanan benzersiz işlem kimliği. Sorgulama / aksiyon endpoint'lerinde URL parametresi olarak kullanılır.

Example:

"8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6"

status

string | null

İşlemin mevcut durumu: pending, pending_3ds, authorized, completed, failed, voided, refunded, partially_refunded.

Example:

"completed"

is_success

boolean

Operasyon başarılı mı? Geçiş döneminde tutuluyor — yeni kodlarda HTTP status kodunu konuşturun (2xx başarı, 4xx/5xx hata).

Example:

true

message

string | null

İnsan-okur durum mesajı.

Example:

"İşlem başarıyla tamamlandı"

error_code

string | null

Yalnızca başarısız işlemlerde dolar — Payven canonical hata kodu.

Example:

"bank_declined"

provider_error_code

string | null

Yalnızca başarısız işlemlerde dolar — bankanın orijinal yanıt kodu.

Example:

"51"

extra_properties

object | null

Banka-spesifik ek alanlar: auth_code, host_reference, provider_transaction_id, processed_at vb.

Show child attributes

Sanal POS

Para Transferi

Identity

Fraud

Authorizations

Body

Response