Skip to main content
DCC (Dynamic Currency Conversion), yabancı kart sahibine kendi kart para biriminde işlem tutarını gösteren akıştır. Müşteri TRY veya kart para birimi (USD, EUR, GBP) arasında seçim yapar.
DCC özelliği organizasyonunuzun banka anlaşmasında etkin olmalıdır ve DCC’yi destekleyen konnektör üzerinden işlem geçmelidir. Etkinlik durumu için destek ekibinize danışın.

​
Akış

​
1. İlk istek (TRY tutarıyla)

Standart POST /payments veya POST /payments/3d/init isteği yapın. Payven yabancı BIN tespit eder ve DCC teklifi varsa yanıtta extra_properties içinde döner: 
{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status":         "processing",
  "extra_properties": {
    "dcc_offered":              "true",
    "dcc_alternative_currency": "USD",
    "dcc_alternative_amount":   "480",
    "dcc_exchange_rate":        "31.25",
    "dcc_markup_percent":       "3.5",
    "dcc_offer_expires_at":     "2026-05-03T12:40:00.000+00:00",
    "processed_at":             "2026-05-03T12:35:00.123+00:00"
  }
}
status alanı DCC akışına özel bir değer almaz — ana ödeme akışındaki processing/authorized durumunu yansıtır. DCC teklifinin var olduğunu extra_properties.dcc_offered: "true" flag’inden ve dcc_* alanlarının varlığından anlayın.
AlanAçıklama
dcc_alternative_currencyKart para birimi (USD, EUR, GBP)
dcc_alternative_amountBu para biriminde gösterilecek tutar (kart cinsi alt birimi: cent / penny)
dcc_exchange_rateUygulanacak çapraz kur
dcc_markup_percentBanka tarafından eklenen marj (% olarak)
dcc_offer_expires_atTeklifin geçerlilik süresi (genellikle 5 dakika)

​
2. Müşteriye seçim sun

Müşteriye iki seçeneği şeffaf şekilde gösterin (PCI-DSS DCC kuralı zorunluluğu): 
☐ Türk Lirası ile öde:    150,00 ₺
☐ Kart para biriminizle:    4,80 USD  (kur: 31,25 — %3,5 marj dahil)
PCI-DSS DCC kuralı: Müşteriye iki seçenek sunulmalı, varsayılan TRY olmalı, kur ve markup açıkça belirtilmelidir. Aksi durumda kart şeması cezai yaptırım uygulayabilir.

​
3. Seçimi onayla

POST /api/v1/payments/{transaction_id}/dcc/confirm

curl -X POST https://vpos.payven.com.tr/api/v1/payments/8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6/dcc/confirm \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: order-1001-dcc-confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "accept_dcc": true
  }'
AlanTipAçıklama
accept_dccbooltrue → kart para birimi ile öde; false → orijinal TRY ile öde

​
Final yanıt

{
  "transaction_id": "8e3f5c12-...",
  "status":         "completed",
  "extra_properties": {
    "processed_at":          "2026-05-03T12:38:01.234+00:00",
    "auth_code":             "123456",
    "host_reference":        "PAYVEN-REF-789",
    "dcc_charged_currency":  "USD",
    "dcc_charged_amount":    "480",
    "dcc_original_amount":   "15000",
    "dcc_original_currency": "TRY",
    "dcc_exchange_rate":     "31.25"
  }
}

​
Kurallar

Müşteri kararı zorunludur. Default seçenek TRY olmalı; müşteri açıkça kart para birimini seçmeli.
Kuru ve markup’ı net göster. Müşteriye uygulanan kur ve marj kartlı işlemde mutlaka görünür olmalı.
Teklif süresi kısadır. Genellikle 5 dakika. Süresi dolmuş teklifle confirm 422 dcc_offer_expired döner.
Yerel kart için DCC önerilmez. Türk bankası kartında DCC otomatik kapalıdır — extra_properties içinde DCC alanları gelmez.

​
Hata response’ları

HTTPcodeAnlam
404payment_not_foundİşlem bulunamadı
422dcc_not_availableOrganizasyonunuz veya kart için DCC etkin değil
422dcc_offer_expiredTeklif süresi doldu — yeni POST /payments ile baştan başlayın
422dcc_invalid_stateİşlem dcc_pending durumunda değil
Hata yanıtı RFC 9457 problem+json formatındadır.

​
Konnektör desteği

DCC, banka konnektörüne özgü bir özelliktir — her banka desteklemez. Aktif olduğu konnektörler için konsoldan Konnektörler ekranına bakın veya destek ekibimize ulaşın.