Başlayın.
Doğrulayın.
Entegre edin.

ArvonaPay API’si ile test işlemi oluşturun, sonucunu sorgulayın ve imzalı bildirimleri kendi sunucunuzda karşılayın.

İlk isteğiniz

1. Yöneticinizden firma portalına davet alın ve hesabınızı etkinleştirin. Giriş şimdilik kullanıcı adı ve parolayla yapılır.
2. Geliştirici Merkezi’nde payments:create, payments:read ve test için sandbox:simulate kapsamlarını seçerek anahtar oluşturun.
3. Anahtarı yalnız kendi sunucunuzun gizli ayarlarında saklayın.
4. Test işlemi oluşturun; bekleyen işlemin sonucunu sandbox ucu ile simüle edin.

API sözleşmesi yükleniyor…

Örnek anahtarı gerçek sandbox anahtarınızla değiştirin. Referans firma içinde benzersiz olmalıdır.

Anahtarınız, firmanızın sınırıdır.

Her istek Authorization: Bearer avp_test_… başlığını kullanır. Anahtar yalnız bağlı olduğu firmanın kayıtlarına erişir. Başka firmanın işlem kimliğiyle yapılan sorgu 404 NOT_FOUND döner.

Anahtar 90 gün geçerlidir ve portal üzerinden iptal edilebilir. Firma pasifleştirilirse veya anahtar sahibinin erişimi değiştirilirse ilgili anahtarlar iptal edilir. Yeni anahtar oluşturmak eski anahtarı kendiliğinden iptal etmez.

İstek sınırları

Anahtar başına dakikada 300, IP başına dakikada 600 istek sınırı uygulanır. 429 aldığınızda Retry-After başlığına uyun ve artan bekleme süresi kullanın.

Aynı istek, aynı sonuç.

İşlem oluşturan ve sandbox sonucu kaydeden isteklerde Idempotency-Key zorunludur. Anahtar 8–128 karakter olmalı; harf, rakam ve - _ . : içerebilir. UUID kullanılması uygundur.

• Anahtar; firma, HTTP yöntemi, yol ve istek gövdesiyle eşleştirilir.
• Aynı anahtar ve aynı istek eşzamanlı gelse bile tek kayıt oluşur.
• Farklı içerikle aynı anahtar kullanılırsa 409 IDEMPOTENCY_CONFLICT döner.
• Tekrarlanan yanıtta Idempotency-Replayed: true başlığı bulunur.
• Ağ zaman aşımında yeni anahtar üretmeyin; aynı anahtar ve aynı gövdeyle tekrar deneyin.

Normal ödeme uçlarında ilk yanıt korunur. Mağaza ödeme ucunda aynı ödeme kimliği ve güncel checkout durumu döner. Güncel ödeme durumunu ayrıca sorgulayın. Anahtarları tekrar kullanmayın. Bu sürümde tekrar koruma kayıtları otomatik silinmez.

API uçları.

Aşağıdaki bilgiler çalışan API’nin sunduğu OpenAPI sözleşmesinden yüklenir.

Ödeme oluşturma alanları

Listeleme ve tarihler

page ve limit ile sayfalama yapılır; sayfa boyutu en fazla 100’dür. status, method, direction, currency, search, from ve to filtreleri kullanılabilir. Tarihler YYYY-MM-DD biçimindedir ve Dubai (UTC+4) takvim gününe göre uygulanır; bitiş günü dahildir. Yanıt zamanları UTC olarak verilir.

Müşteri bağlamı ve zaman aşımı.

Oluşturma isteğine isteğe bağlı customer nesnesi eklenebilir: id, email, phone, ip, country. Firma kuralları müşteri kimliğini veya iki harfli ülke kodunu zorunlu kılabilir. Telefon ülke koduyla, örneğin +905551234567 biçiminde gönderilir. PAN, CVV ve ulusal kimlik numarası gönderilmez.

{"customer":{"id":"customer-001","country":"TR"}}

Ülke ve IP entegrasyon firmasının beyanıdır; doğrulanmış konum veya VPN tespiti değildir. Engel listesi veya hız kuralında 403 RISK_REJECTED alınır. Sistem veya kanal yeni işleme kapalıysa 503 PAYMENT_INTAKE_PAUSED, genel tutar sınırı dışında 400 GLOBAL_AMOUNT_LIMIT döner.

expiresAt kabul süresinin sonunu gösterir. Varsayılan süreler havale yatırımı 60, gateway yatırımı 30, çekim onayı 1.440 dakikadır; firma politikası bunları değiştirebilir. Süresi dolan bekleyen işlem EXPIRED olur ve payment.expired olayı üretilir. Arka plan kontrolü 30 saniyede bir çalışır; bitişten sonra sonuçlandırma ve onay da reddedilir. Terminal işlem yeniden açılamaz. Eski sürümden gelen süre tanımsız işlemler otomatik sona erdirilmez.

xxxxpays için tutarı müşteri girer.

xxxxpays POST /v1/checkout-sessions ucuna yalnız referans ve customer.id (merchant UID), ad, soyad ve e-posta gönderir. Tutar veya para birimi gönderilmez. Müşteri, dönen customerCheckout.url bağlantısında tutarı ve para birimini seçer; ArvonaPay hesabını görüp onaylar.

Doğrulama yöntemi henüz belirlenmedi. Tutar onayı ödeme değildir; bu akışta mağazaya geçiş, tahsilat ve başarı bildirimi kapalıdır. Doğrulama durumu NOT_CONFIGURED kalır.

xxxxpays için güncel 1.5.0 rehberi →

/v1/store-payments eski doğrudan mağaza akışıdır; müşteri tutar girişi zorunlu xxxxpays için kullanılamaz. Diğer eski entegrasyonlarda mağaza ürün toplamı − hesaplanan indirim = sabit ödeme hedefi kuralı korunur.

Kur farkı ve komisyon nasıl tanımlanır?

1. Yönetici panelinde Finans Merkezi → Baz Kurlar bölümünden günün doğrudan kur çiftini girin. Değerler manuel tanımlanır; otomatik piyasa kuru servisi bağlı değildir. Ters çift gerekiyorsa ayrıca tanımlayın.
2. Kur Farkı & Komisyon → Fiyatlandırma ekle bölümünde firma, işlem para birimi, kanal ve yönü seçin.
3. Tahsilat ve mutabakat para birimini, kur farkını, risk tamponunu, yüzde/sabit komisyonu, bloke rezervi ve T+ vadesini girin. Havale tahsilatı işlemle aynı birimdedir; farklı birimde gateway tahsilatına kur farkı uygulanabilir.
4. Alt/üst işlem tutarını, günlük ve aylık limiti belirleyin. Gerekçe ile kaydedin. Boş günlük/aylık limit sınırsızdır. Bekleyen ve başarılı işlemler limit tüketir; başarısızlar tüketmez.
5. Hesaplamayı dene ile kontrol edin. Ardından test ödemesi oluşturup ayrıntıdaki sabitlenmiş hesabı ve kâr raporunu karşılaştırın. Sağlayıcı maliyet profilini ödeme oluşturmadan önce tanımlayın.

Efektif kur = baz kur × (1 + kur farkı / 100) × (1 + tampon / 100)
Tahsilat = işlem tutarı × efektif kur
Firma net yatırımı = tutar − komisyon − bloke rezerv
Firma çekim borcu = tutar + komisyon
Katkı kârı = komisyon karşılığı + kur geliri − sağlayıcı maliyeti

Tutarlar en küçük para biriminde tamsayıyla hesaplanır ve yarım değer yukarı yuvarlanır. Desteklenen TRY, EUR, USD, GBP, AED, SAR ve CHF iki ondalıklıdır. Firma para birimi ve sağlayıcı tahsilat para birimi etkin olmalıdır.

API yanıtındaki sabit kayıt

amount ve currency siparişin özgün tutarıdır. pricing.gateway tahsilat tutarını en küçük birimde, pricing.chargeCurrency tahsilat para birimini gösterir. Örneğin 112352, iki ondalıklı USD için 1.123,52 USD demektir. pricing.fee ve pricing.reserve özgün para birimindedir; pricing.settlementNet mutabakat para birimindedir. Oran alanları metin, ...Bps alanları baz puandır; 250 baz puan %2,50’dir.

İşlem oluşturulurken kur, profil sürümü ve hesaplanan tutarlar kaydedilir. Oran değişiklikleri geçmiş işlemleri yeniden hesaplamaz. Eski v0.1 işlemlerde pricing boş olabilir. Özel profil yoksa firmanın varsayılan komisyonu ve aynı para birimi kullanılır; fallback: true ile belirtilir. Son sürümü durdurulan profile sahip işlemler engellenir.

Gün sonu ve mutabakat

Vadesi gelen başarılı işlemler seçilip taslak oluşturulur. Aynı işlem aktif birden fazla mutabakata giremez. Taslağı farklı kullanıcı onaylar; gerçekleşen test tutarı ve referans kaydedilerek fark izlenir. İptal edilen taslak işlemleri serbest bırakır; geçmişi korunur. Bu akış banka transferi yapmaz.

Yeni hata durumları

Durum, tek bir anlam taşımalı.

Terminal durumlar başka bir sonuca çevrilemez. Aynı sonuca tekrar tamamlama çağrısı mevcut kaydı döndürür; tekrar defter veya olay oluşturmaz. Çekimi oluşturan kimlik onaylayamaz; API anahtarının sahibi de oluşturan kimlik olarak kaydedilir.

Sonucu güvenilir biçimde alın.

Firma portalındaki Geliştirici Merkezi’nden herkese açık bir HTTPS adresi tanımlayın. İmza sırrı yalnız yapılandırma sırasında gösterilir. Adresin güncellenmesi yeni imza sırrı üretir; alıcıyı da güncelleyin. Özel ağ, yerel adres, IP adresi ve 443 dışı portlara gönderim yapılmaz.

{
  "id": "event-uuid",
  "type": "payment.succeeded",
  "createdAt": "2026-10-19T12:00:00.000Z",
  "data": {
    "id": "payment-uuid",
    "reference": "order-0001",
    "amount": "1250.50",
    "currency": "TRY",
    "status": "SUCCEEDED",
    "environment": "sandbox"
  }
}

Örnek kısaltılmıştır. data tam Payment nesnesidir. Gövdeyi ham baytlarıyla doğrulayın; JSON’u yeniden serileştirmeyin.

Node.js ile imza doğrulama

import { createHmac, timingSafeEqual } from 'node:crypto';

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

Teslimat sözleşmesi

• İmzayı ve ±5 dakikalık zaman penceresini doğrulayın.
• Olay kimliğini veritabanınızda tekil kaydedin; iş etkisiyle aynı transaction içinde işleyin.
• Kayıt güvenle tamamlandıktan sonra 2xx döndürün. Daha önce işlenmiş olaya da 2xx verin.
• Zaman aşımı 5 saniyedir. 2xx dışı yanıtlar ve bağlantı hataları tekrar denenir.
• Artan bekleme süresi 30 saniyeden başlayıp 1 saate kadar çıkar; en fazla 8 deneme yapılır.
• HTTP yönlendirmeleri izlenmez. Alıcı yanıtı en fazla 64 KiB olmalıdır.

Bildirimler en az bir kez teslimat mantığıyla çalışır; ağ kesintilerinde aynı olay tekrar gelebilir. Bildirim adresi yoksa olay NOT_CONFIGURED olarak saklanır. Adres tanımlandıktan sonra Bildirim Merkezi’nden yeniden sıraya alınabilir.

Hataları kararınıza bağlayın.

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Aynı anahtar farklı bir istek için kullanılmış.",
    "requestId": "request-uuid"
  }
}

İlk entegrasyon kontrolünüz.

• Başarılı ve başarısız yatırım senaryoları.
• Çekim oluşturma, kendi talebini onaylayamama ve ayrı kullanıcı onayı.
• Aynı isteğin eşzamanlı tekrarında tek ödeme.
• Aynı anahtarla farklı tutarın 409 dönmesi.
• Başka firmanın kayıtlarına erişimin engellenmesi.
• İmzalı bildirim doğrulaması, zaman penceresi ve tekil olay kaydı.
• 2xx, 5xx, zaman aşımı ve yeniden deneme davranışları.
• TRY, EUR, USD ve GBP toplamlarının ayrı işlenmesi.
• Anahtar iptali ve firma pasifleştirme sonrası erişimin kapanması.

Canlıya geçiş ayrı bir karardır.

Bu sözleşme sandbox içindir. Canlı işlem, sağlayıcı adaptörleri ve yetkili ticari yapı doğrulandıktan; işlem, mutabakat, kurtarma ve güvenlik kabul testleri tamamlandıktan sonra ayrı bir sürümde açılabilir. Mevcut anahtarlar canlıya çevrilemez.

Bu sürüm kart verisi toplama, gerçek banka transferi, iade, chargeback, otomatik canlı takas veya TickPays geçmişini içe aktarma sunmaz. Gerçek bağlantılar mevcut TickPays sisteminde çalışmaya devam eder.