Payoneer Checkout

Gereken bilgiler

Payoneer Checkout portalı → Integration → API access:

• merchant_id: API username (merchant code). Tüm mağazalarınız için aynıdır.
• secret_key: Payment token. GENERATE TOKEN ile üretilir; canlı ve test ortamı için ayrı token gerekir, token yalnız üretildiği anda görünür.
• merchant_key: Store code (aynı sayfadaki Store codes sekmesi). Payoneer buna division der; her mağazanın kodu farklıdır.

Panelinizde Ayarlar → Ödemeler → Yöntem ekle → Payoneer Checkout seçin, üç değeri girin.

Sandbox: Payoneer portalında ortam anahtarı test konumundayken üretilen token'ı girip sandbox (test) modu kutusunu işaretleyin; panel istekleri api.sandbox.oscato.com'a gönderir. Canlıya geçerken portalda anahtarı live'a çevirin, canlı token üretin, kutuyu kaldırın (api.live.oscato.com).

Bildirim ve dönüş adresleri her ödemeye otomatik eklenir; Payoneer portalında ayrıca bir ayar gerekmez. Adres kalıpları:

https://<panel-alan-adınız>/payments/payoneer/callback   (sunucu bildirimi)
https://<panel-alan-adınız>/payments/payoneer/return     (müşterinin dönüşü)

Bildirim adresi HTTPS olmak ve gerçek bir IP'ye çözülmek zorundadır; alan adınız henüz bize yönlenmediyse ödeme başlatılamaz.

Akış

1. Müşteri tutarı girer, Payoneer'i seçer. Telefon zorunlu değildir; varsa gönderilir.
2. Panel Payoneer'e bir LIST oturumu açar (POST /api/lists, Basic auth: merchant code + payment token). Sipariş numaramız transactionId alanına, mağaza kodu division alanına yazılır; tutar ana birimde (100.50) gider.
3. Müşteri Payoneer'in barındırdığı ödeme sayfasına (redirect.url, v6) tam sayfa yönlendirilir; kart bilgisi, 3D Secure ve cüzdanlar orada, sizin sunucunuza kart verisi hiç uğramaz.
4. Ödeme bitince müşteri returnUrl/cancelUrl ile panele döner. Bu dönüş yalnız yönlendirir, bakiye yüklemez.
5. Payoneer aynı anda sunucumuza bir bildirim gönderir (varsayılan: POST, JSON). Bildirim imzalı değildir; panel önce LIST açarken bildirim adresine eklediği gizli token'ı (payment token ile HMAC) kontrol eder, sonra bildirimdeki longId ile kendi kimlik bilgileriyle GET /api/charges/{longId} çağırır. Bakiye yalnız bu yanıttaki duruma göre yüklenir; bildirimin gövdesindeki durum ve tutar hiç kullanılmaz.
6. Yanıttaki identification.transactionId bizim ödememiz değilse bildirim yok sayılır.

Aynı notificationId ile gelen ikinci teslimat yok sayılır; bakiye iki kez yüklenmez. Doğrulanan her bildirime panel 200 OK döner. Token'ı eksik/yanlış olan ya da payment / session dışındaki (customer, account) bildirimler 400 alır; Payoneer 2xx almadığı bildirimi 24 saat boyunca yeniden dener, bu zararsızdır.

Durumlar

Payoneer'in status.code / status.reason çifti şöyle eşlenir:

Payoneer	Panel
charged / debited, charged / closed	tamamlandı, bakiye yüklenir
charged / fraud_suspected	beklemede (hold); Payoneer'in kararına göre Admin → Ödemeler'den tamamlayın
preauthorized, pending	beklemede; ön provizyon sizin tarafınızdan kapatılınca gelen charged bildirimi bakiyeyi yükler
failed, declined, rejected, aborted, canceled	başarısız; resultInfo ödeme notuna yazılır
expired (ödeme ya da oturum)	süresi doldu
paid_out, charged_back, information_requested	tamamlanmış ödemeye dokunmaz; iade ve ters ibrazı Payoneer portalından takip edin

Oturum (entity=session) bildirimlerinde yalnız expired / canceled / rejected / failed ödemeyi kapatır; listed ve ended beklemede bırakır.

Para birimleri

Panel, ödemeyi panel para biriminde başlatır ve bir liste dayatmaz. Payoneer'in kabul ettiği işlem para birimleri Payoneer belgesindeki Supported currencies sayfasında tutulur; Payoneer bakiyesine yerleşim USD, EUR, GBP, HKD ve JPY ile yapılır. Kabul edilmeyen bir birimde Payoneer LIST isteğini 422 ile reddeder; ödeme başlamaz ve Payoneer'in resultInfo mesajı hata olarak yükselir.

Müşteri alanları

Payoneer country ve fatura adresi ister; panel bunları bilmez. Ülke, yöntemin extra.country değeri varsa oradan, yoksa panel para biriminden türetilir (TRY → TR, EUR → DE, GBP → GB …, tanınmayan birimde US). Bu yalnız Payoneer'in hangi ödeme yöntemlerini göstereceğini belirler. Fatura adresi sabit yer tutucudur (N/A, posta kodu 00000); ad-soyad kullanıcı adından türetilir.

Sık sorunlar

• "Payoneer: kimlik doğrulama başarısız" (HTTP 401): merchant code ya da payment token yanlış, ya da test token'ı canlı modda (veya tersi) kullanılıyor. Token ortama özeldir.
• LIST 422 ile reddediliyor, mesaj division/store'tan söz ediyor: store code yanlış ya da başka bir mağazanın kodu. API access → Store codes'tan kopyalayın.
• Ödeme başarılı ama bakiye yok: Admin → Ödemeler'de kaydın notuna bakın. Payoneer portalı → Store transactions'ta işlemin charged/debited olduğunu doğrulayın; bildirim teslim edilemediyse Payoneer 24 saat boyunca yeniden dener. Bildirimlerin POST olarak gönderildiğinden emin olun (GET bildirimi panelin callback adresi tarafından kabul edilmez).
• Sandbox'ta kart reddediliyor: Payoneer'in test kartlarını kullanın (4242 4242 4242 4242, herhangi CVC, gelecekte bir tarih); gerçek kart sandbox'ta çalışmaz.