Paymore PF (Payment Facilitator) Entegrasyon Rehberi

1. Amaç ve Kapsam

Bu doküman, bir PF’in (Payment Facilitator) Paymore ile entegre olabilmesi için gerekli iş akışlarını, request/response sözleşmelerini, alan dönüşümlerini ve hata davranışlarını açıklar.

2. Genel Mimari

3. Mesaj Yönleri

4. Kimlik Doğrulama

Her iki yöndeki servis çağrılarında HTTP Basic Authentication kullanılır. Tüm trafik HTTPS üzerinden gerçekleştirilmelidir.

Authorization: Basic <base64(kullaniciAdi:sifre)>
Content-Type: application/json

5. Firma Onboarding

Paymore, başvuruyu aldıktan sonra anlık olarak bir data.id döndürür. Bu değer başvurunun sisteme alındığını gösterir; onay durumunu göstermez.

5.1 Minimum Geçerli Request

{
  "taxPayerType": 2,
  "type": 2,
  "taxNumber": "1234567890",
  "merchantName": "Örnek Otomat Ticaret A.Ş.",
  "merchantShortName": "Örnek Otomat",
  "firstName": "Ahmet",
  "familyName": "Yılmaz",
  "invoiceTitle": "Örnek Otomat Ticaret A.Ş.",
  "invoiceEMail": "muhasebe@ornekotomat.com.tr",
  "invoicePhone": "5551234567",
  "integratorShortName": "PAYMORE",
  "allowOfflineSales": false,
  "invoiceAddress": {
    "countryName": "Türkiye",
    "cityName": "İstanbul",
    "districtName": "Kadıköy",
    "neighborhoodName": "Caferağa",
    "addressDetail": "Örnek Sokak No:1 D:2"
  },
  "adminUser": {
    "fullName": "Ahmet Yılmaz",
    "email": "ahmet.yilmaz@ornekotomat.com.tr",
    "phone": "5551234567"
  }
}

5.2 Tam Request

{
  "taxPayerType": 2,
  "type": 2,
  "taxNumber": "1234567890",
  "merchantName": "Örnek Otomat Ticaret A.Ş.",
  "merchantShortName": "Örnek Otomat",
  "firstName": "Ahmet",
  "familyName": "Yılmaz",
  "invoiceTitle": "Örnek Otomat Ticaret A.Ş.",
  "invoiceEMail": "muhasebe@ornekotomat.com.tr",
  "invoicePhone": "5551234567",
  "mersisNo": "1234567890123456",
  "taxOfficeCode": "123456",
  "integratorShortName": "PAYMORE",
  "allowOfflineSales": false,
  "invoiceAddress": {
    "countryName": "Türkiye",
    "cityName": "İstanbul",
    "districtName": "Kadıköy",
    "neighborhoodName": "Caferağa",
    "addressDetail": "Örnek Sokak No:1 D:2"
  },
  "adminUser": {
    "fullName": "Ahmet Yılmaz",
    "email": "ahmet.yilmaz@ornekotomat.com.tr",
    "phone": "5551234567"
  }
}

5.3 Response Örnekleri

{
  "success": true,
  "data": { "id": "64f1c2a1e4b0a1b2c3d4e5f6" },
  "message": "Merchant application has been received successfully."
}

{
  "success": false,
  "data": null,
  "message": "An error occured."
}

{
  "success": false,
  "data": null,
  "message": "Unauthorized"
}

{
  "success": false,
  "data": null,
  "message": "Bu vergi numarasıyla eşleşen birden fazla firma kaydı bulundu, manuel inceleme gerekiyor."
}

6. Onboarding Alanları

6.1 Üst Seviye Alanlar

6.2 invoiceAddress Alanları

6.3 adminUser Alanları

7. Onboarding Alan Eşleştirmeleri

8. Onay Süreci ve Firma Yaşam Döngüsü

9. Satış Bildirimi

9.1 Başarılı İşlem Request’i

{
  "id": 564107581,
  "createDate": "2026-08-01T14:22:10.481Z",
  "batchId": 12,
  "stan": 345,
  "transactionAmount": 88.5,
  "finalAmount": 88.5,
  "loyaltyAmount": 0,
  "installmentCount": 1,
  "finalInstallmentCount": 1,
  "cardNo": "411111******1111",
  "authorizationCode": "A1B2C3",
  "failMessage": null,
  "acquirerBKMCode": "0015",
  "merchantId": "64f1c2a1e4b0a1b2c3d4e5f6",
  "statusId": 2,
  "operationTypeId": 1,
  "cardType": "C",
  "acquirerReference": 564107581,
  "rrn": "123456789012",
  "isCancellation": false
}

9.2 Başarısız / İptal İşlem Request’i

{
  "id": 564107582,
  "createDate": "2026-08-01T14:25:03.112Z",
  "transactionAmount": 45.0,
  "finalAmount": 45.0,
  "loyaltyAmount": 0,
  "installmentCount": 1,
  "finalInstallmentCount": 1,
  "cardNo": "411111******1111",
  "failMessage": null,
  "merchantId": "64f1c2a1e4b0a1b2c3d4e5f6",
  "statusId": 3,
  "operationTypeId": 2,
  "acquirerReference": 564107582,
  "isCancellation": true
}

9.3 PF Response Örnekleri

{ "responseCode": "00" }

{ "responseCode": "05" }

10. Satış Alan Eşleştirmeleri

11. Retry ve Idempotency

Başarısız satış bildirimleri tekrar gönderilebilir. Başarılı işlemler idempotency kontrolü ile korunur ve ikinci kez gönderilmez.

12. Hata Senaryoları

13. Sequence Diagramları

13.1 Firma Onboarding

PF                         Paymore                    Operasyon
|                             |                           |
|-- Onboarding Request ------>|                           |
|<-- 200 + data.id -----------|                           |
|                             |-- İnceleme Kuyruğu ------>|
|                             |<-- Onay / Revizyon -------|
|                             |-- Firma Aktif ------------|

13.2 Satış Bildirimi

POS                        Paymore                         PF
|                             |                           |
|-- Ödeme Sonucu ------------>|                           |
|                             |-- Satış Request --------->|
|                             |<-- responseCode ----------|
|                             |-- Sonuç Kaydı ------------|

14. API Özeti

15. Entegrasyon Kontrol Listesi

• ☐ Test ve canlı ortam URL’leri tanımlandı
• ☐ Her iki yön için Basic Auth bilgileri tanımlandı
• ☐ Onboarding request alanları eşleştirildi
• ☐ data.id değeri saklanıyor
• ☐ Onay sonrası merchant kimliği korunuyor
• ☐ PF webhook URL’i Paymore’a iletildi
• ☐ Satış endpoint’i hazırlandı
• ☐ responseCode="00" başarı davranışı uygulandı
• ☐ Retry davranışı uygulandı
• ☐ Duplicate başarılı işlem koruması test edildi
• ☐ Uçtan uca test firması ve test işlemi tamamlandı