Gerçek müşteri kaydı.
Sabit işlem tutarı.
Doğrulanmış sonuç.

Merchant kodu: xxxxpays. Entegrasyon, müşteriyi ArvonaPay kontrollerinden geçirir ve etkin mağazadaki sabit tutarlı ödeme bağlantısına yönlendirir.

Karşı taraftan gereken bilgiler

1. API isteklerini gönderen sunucunun sabit çıkış IPv4/IPv6 adresleri. Müşterinin cihaz IP’si izin listesine alınmaz. Tam IP adresi gerekir; CIDR veya joker karakter kabul edilmez.
2. Ödeme sonuçlarını kabul edecek herkese açık HTTPS callback adresi; 443 portu ve geçerli TLS sertifikası.
3. İşlem para birimi, min/max tutar ve beklenen hacim; kur ve komisyon koşulları ArvonaPay tarafından firma profilinde tanımlanır. İlk mağaza testi AED üzerinden yapılır.

IP ve callback tanımlandıktan sonra merchant etkinleştirilir ve sunucu tarafında kullanılacak avp_test_… anahtarı sağlanır. Gerekli kapsamlar: payments:create ve payments:read. Callback imza sırrı API anahtarından ayrıdır. Portal kullanıcı hesabı gerekiyorsa ayrıca açılır.

İstekten bildirime.

1. xxxxpays kendi veritabanındaki gerçek müşteri kaydından işlem isteği oluşturur.
2. ArvonaPay API anahtarı, merchant etkinliği ve izinli sunucu IP adresini kontrol eder.
3. Müşteri alanları, risk/engel listesi, tutar/limit ve kur koşulları değerlendirilir.
4. İşlem, ArvonaPay tarafında etkin ve uygun mağazaya bağlanır. Bu sürümde bağlı mağaza Dynostech / Trainexa LLC; mağaza para birimi AED’dir.
5. Mağaza ürün eşleştirir, gerekli sipariş indirimini hesaplar ve ödeme bağlantısını hazırlar.
6. xxxxpays sorgudan gelen bağlantıyı müşteriye açar.
7. Sunucudan doğrulanmış sonuç ArvonaPay tarafından imzalı callback ile xxxxpays’e gönderilir.

ArvonaPay’de şu an tek bağlı mağaza vardır. Yeni mağazalar kendi adaptörü ve kabul testleri tamamlanınca eklenir. Merchant ürün, araç veya ECU bilgisi göndermez.

Bilgiler xxxxpays kaydından gelir.

Rastgele ad, e-posta veya kullanıcı adı üretmeyin. Eksik zorunlu alanlar otomatik doldurulmaz; istek reddedilir. Bu alanlar merchant kaydının beyanıdır; bir resmî kimlik doğrulama servisi çağrısı değildir. Müşteri bilgileri şifreli saklanır, yetkili işlem ayrıntısında görünür; toplu listelere veya callback gövdesine eklenmez.

Sabit tutarla işlem açın.

POST https://api.arvonapay.com/v1/store-payments
Authorization: Bearer <XXXXPAYS_SANDBOX_API_KEY>
Idempotency-Key: xxxxpays-order-0001
Content-Type: application/json

{
  "reference": "xxxxpays-order-0001",
  "amount": "300.00",
  "currency": "AED",
  "customer": {
    "username": "{{customer_username}}",
    "firstName": "{{customer_first_name}}",
    "lastName": "{{customer_last_name}}",
    "email": "{{customer_email}}"
  }
}

{{customer_…}} değerleri yer tutucudur; gerçek entegrasyonda xxxxpays müşteri kaydındaki karşılıklarıyla değiştirilir. Tutar ondalık metin olarak gönderilir. Referans firma içinde benzersizdir. Merchant kimliği API anahtarından belirlenir; gövdede merchantId gönderilmez.

Idempotency-Key: 8–128 karakter; harf, rakam ve - _ . :. Ağ hatasında aynı gövde ve aynı anahtarla tekrar edin. Aynı anahtarla farklı içerik 409 IDEMPOTENCY_CONFLICT döndürür. Aynı referans için yeni anahtar üretip yeni işlem açmayın.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "reference": "xxxxpays-order-0001",
  "amount": "300.00",
  "currency": "AED",
  "status": "PENDING",
  "environment": "sandbox",
  "checkout": {
    "state": "QUEUED",
    "chargeAmount": "300.00",
    "chargeCurrency": "AED",
    "url": null,
    "livePayment": false
  }
}

Yanıt kısaltılmış şema örneğidir; gerçek işlem kimliği ve zaman alanları sunucudan alınır.

Bağlantı hazır olunca yönlendirin.

GET https://api.arvonapay.com/v1/payments/{id}
Authorization: Bearer <XXXXPAYS_SANDBOX_API_KEY>

İşlemi 3–5 saniye arayla sorgulayın. checkout.state=READY ve boş olmayan checkout.url geldiğinde müşteriyi bu URL’ye yönlendirin. URL’yi tahmin etmeyin veya kendiniz üretmeyin; yalnız API yanıtındaki değeri kullanın. Bağlantı işlem yetkisi taşır, herkese açık sayfalara veya günlüklere konmaz.

Ödeme sonucunda üst düzey status esas alınır; checkout.state mağaza hazırlığını ve sonucunu açıklar. Tarayıcıdan dönüş veya sayfanın açılması tek başına başarı kanıtı değildir. Mağaza akışında genel /v1/sandbox/payments/{id}/complete ucu kullanılamaz; sonuç mağaza ekranındaki test onayından gelmelidir.

İşlem tutarı korunur.

Ürün liste toplamı   306.00 AED
Hesaplanan indirim     6.00 AED
Nihai işlem tutarı   300.00 AED

Önce tam tutarlı ürün veya paket aranır. Tam eşleşme yoksa gerçek katalog ürünlerinin toplamı ile sabit hedef arasındaki fark, en fazla %20 sınırında gerçek sipariş indirimi olarak hesaplanır. Çark bu indirimi gösterir. Ürün fiyatları yükseltilmez ve merchant tutarına ikinci indirim uygulanmaz. Sınırlar içinde ürün bulunamazsa işlem başarısız olur.

Merchant TRY gibi başka para birimi kullanacaksa önceden firma fiyatlandırma profilinde AED tahsilat birimi ve günün kuru tanımlanır. Özgün tutar ve para birimi callback’te korunur. Örnek: 3.750 TRY → 300 AED; mağazada 300 AED eşleşir, merchant kaydı ve bildirimi 3.750 TRY kalır.

Sonucu imzayla doğrulayın.

Sonuç, firma ayarına tanımlanan HTTPS URL’ye POST application/json olarak gönderilir. Adres işlem gövdesinden alınmaz.

X-Arvona-Event-Id: <event-id>
X-Arvona-Timestamp: <Unix saniyesi>
X-Arvona-Signature: <küçük harf hex HMAC-SHA256>

{
  "id": "22222222-2222-4222-8222-222222222222",
  "type": "payment.succeeded",
  "createdAt": "2026-10-19T20:00:00.000Z",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "reference": "xxxxpays-order-0001",
    "amount": "300.00",
    "currency": "AED",
    "status": "SUCCEEDED",
    "environment": "sandbox"
  }
}

Örnek kısaltılmıştır; data tam ödeme nesnesidir. Bildirim türleri: payment.succeeded, payment.failed, payment.expired. İmza ham HTTP gövdesi üzerinden doğrulanır; JSON’u yeniden serileştirmeyin.

HMAC-SHA256(callback_secret, timestamp + "." + rawBody)

import {createHmac, timingSafeEqual} from 'node:crypto';
export function verifyCallback(rawBody, headers, secret) {
  const time = headers['x-arvona-timestamp'];
  const signature = headers['x-arvona-signature'];
  if (!/^\d{10}$/.test(time || '') || !/^[a-f0-9]{64}$/.test(signature || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(time)) > 300) return false;
  const expected = createHmac('sha256', secret).update(time + '.').update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}

1. İmzayı, ±5 dakika zaman aralığını ve header/body olay kimliğinin aynı olduğunu doğrulayın.
2. Merchant referansını, özgün tutarı, para birimini ve sandbox ortamını kendi kaydınızla karşılaştırın.
3. Olay kimliğini benzersiz kaydedin; sipariş güncellemesiyle aynı veritabanı işleminde tamamlayın.
4. Kalıcı kayıt tamamlandığında HTTP 200 dönün. Daha önce işlenmiş olaya da 200 dönün.
5. Gönderim zaman aşımı 5 saniye; 2xx dışı cevaplar tekrar edilir. En fazla 8 deneme, 30 saniyeden 1 saate artan bekleme. Her denemede timestamp/imza yenilenir, olay kimliği korunur.

Callback endpoint’iniz imza doğrulaması sonrasında kısa yanıt vermelidir; örneğin {"received":true}. Ağ kesintilerinde bildirim birden çok kez gelebilir. İmza doğrulama ile tekil olay kontrolü birlikte uygulanır.

Kontrol edilecek durumlar.

Hata yanıtındaki error.requestId değerini destek incelemesi için saklayın. Kart/PAN, CVV ve T.C. kimlik numarası bu entegrasyonun alanları değildir.

Bağlantı açılmadan önce.

1. İzinli IP + doğru API anahtarıyla başarılı istek.
2. İzin dışı IP’den aynı anahtarın 403 dönmesi.
3. Eksik müşteri alanlarının reddi; gönderilen müşteri kaydının korunması.
4. Aynı isteğin eşzamanlı tekrarında tek ödeme ve tek mağaza işi.
5. 306 − 6 = 300 AED eşleşmesi ve çark tutarının korunması.
6. Başarılı, başarısız ve süresi dolan test işlemleri.
7. Yanlış callback imzasının reddi; aynı olayın ikinci kez işlenmemesi.
8. Callback alıcısı 5xx verdiğinde tekrar ve ardından 200 teslimatı.
9. Başka merchant’ın işlem kimliğine erişimin engellenmesi.

Genel entegrasyon rehberi · Çalışan OpenAPI sözleşmesi