Data Models - Payments & Charges
Payment ve Charge objelerinin public/conceptual alanları, normalized model ve provider raw data ayrımı.
Bu sayfa Payment ve Charge objelerinin public/conceptual modelini açıklar. Amaç private database schema'yı birebir expose etmek değil, merchant ve developer'ın hangi alanın hangi sorumluluğu taşıdığını anlamasını sağlamaktır.
HSRC Pay'de public integration modeli normalized alanlara dayanmalıdır. Raw provider response debug, trace veya iç operasyon için saklanabilir; merchant uygulaması kararlarını normalized field'lara göre vermelidir.
Model tasarım ilkeleri
- Payment business-level ödeme niyetidir.
- Charge provider-level attempt veya finansal işlem denemesidir.
- Provider raw data, public modelin yerine geçmez.
- Metadata merchant bağlamını taşır; secret, card data veya provider credential için kullanılmaz.
- Security/3DS alanları hassas kabul edilir ve maskelenmelidir.
- Backward compatibility için public field'lar stabil ve açıklanabilir tutulmalıdır.
Payment object
| Field | Type | Açıklama | Ne zaman dolar? | Merchant için önemi |
|---|---|---|---|---|
id | string | Payment kimliği | Create anında | Order/payment eşleştirme |
amount | integer | Minor unit tutar | Create anında | Finansal niyet |
currency | string | Para birimi | Create anında | Provider capability ve settlement bağlamı |
status | string | Payment lifecycle state | Lifecycle boyunca | Merchant order state |
customer_id | string/null | Customer ilişkisi | Varsa create | Müşteri takibi |
checkout_session_id | string/null | Hosted checkout ilişkisi | Checkout flow'da | Session-payment bağını kurar |
routing_origin | string/null | Son confirm routing kökeni | Confirm sonrası | merchant_direct, autopilot, vb. |
installments | number/null | Taksit sayısı | Create | Tek çekim için null veya 1 |
metadata | object | Merchant-defined context | Create/update | Order, tenant veya internal reference |
created_at / updated_at | timestamp | Zaman bilgileri | Sistem tarafından | Audit ve operasyon |
secure_mode, auto_capture ve next_action create/confirm sırasında kullanılır; confirm yanıtında confirmResult.paymentNextAction (redirect_user_to_url) platform yönlendirmesini taşır. Liste/detay DTO'da tüm iç alanlar her zaman görünmeyebilir; genişletme için include_* query flag'lerine bakın.
Charge object
| Field | Type | Açıklama | Provider ilişkisi | Notlar |
|---|---|---|---|---|
id | string | Charge attempt kimliği | Provider denemesiyle ilişkilidir | Bir Payment içinde birden fazla olabilir |
payment_id | string | Üst Payment ilişkisi | Aynı Payment altında attempt gruplar | Reporting için kritik |
attempt_no | integer/null | Deneme sırası | Routing plan indeksi | Trace için kullanılır |
status | string | Charge lifecycle state | Provider sonucuna göre güncellenir | Authorized/captured/declined ayrımı |
amount | integer | Denenen tutar | Provider request tutarı | Payment amount ile uyumlu olmalı |
authorized_amount | number | Authorize edilen tutar | Auth sonrası | Capture öncesi önemli |
captured_amount | number | Capture edilen tutar | Capture sonrası | Finansal kapanış |
refunded_amount | number | İade edilen toplam | Refund sonrası | Refund reporting |
payment_provider_id | string/null | Provider kimliği | Seçilen provider | Operasyonel izleme |
routing_plan_id | string/null | Routing plan ilişkisi | Candidate seçimi | Fallback analizi |
routing_origin | string/null | Routing kökeni | Routing engine | Operasyonel görünürlük |
security | object/null | 3DS/security subset | Orchestrator/adapter merge | Hassas alanlar maskelenmeli |
transaction | object/null | Normalized transaction subset | Orchestrator/adapter merge | Raw provider response değildir |
Payment vs Charge karşılaştırması
| Başlık | Payment | Charge |
|---|---|---|
| Seviye | Merchant/business | Provider/rail |
| Sayı | Genellikle order başına tek | Bir Payment için birden fazla olabilir |
| Amaç | Ödeme niyetini ve nihai state'i tutar | Attempt, authorization, capture ve provider trace tutar |
| Webhook etkisi | Merchant order state için ana kaynak | Operasyonel detay ve reconciliation |
| Routing etkisi | Payment aynı kalır | Fallback yeni charge attempt üretebilir |
State fields
Payment state merchant'ın order lifecycle'ını etkiler. Charge state provider attempt'in durumunu anlatır.
Örnek conceptual state aileleri:
- Payment:
CREATED,REQUIRES_PAYMENT_METHOD,REQUIRES_ACTION,PROCESSING,AUTHORIZED,SUCCEEDED,CANCELED,REFUNDED,EXPIRED - Charge:
CREATED,REQUIRES_ACTION,AUTHORIZED,REQUIRES_CAPTURE,PARTIALLY_CAPTURED,CAPTURED,CANCELED,FAILED,REFUNDED,EXPIRED,DECLINED
Payment'ta DECLINED yoktur; decline Charge DECLINED + Payment REQUIRES_PAYMENT_METHOD kombinasyonuyla okunur.
Güncel enum ve response sözleşmesi için API Reference esas alınmalıdır.
Amount/currency fields
Tutar alanları minor unit olarak tasarlanmalıdır. Payment amount iş hedefini, Charge amount provider attempt tutarını ifade eder.
Partial capture veya partial refund gibi operasyonlarda Charge üzerindeki capturedAmount ve refundedAmount alanları Payment üst seviye state'iyle birlikte yorumlanmalıdır.
Provider references
Provider reference alanları reconciliation ve support süreçleri için değerlidir. Ancak provider raw response'un tamamı merchant API contract'ı olarak düşünülmemelidir.
Provider-specific alanlar değişebilir; merchant uygulaması normalized status, kind, errCode, providerRef ve traceId gibi public alanlara dayanmalıdır.
Metadata
Metadata merchant'ın kendi bağlamını taşır:
- Order ID
- Tenant/workspace reference
- Campaign veya invoice reference
- Internal reporting key
Metadata içine card data, CVV, provider credential, secret, signature material veya sensitive PII koymayın.
Security/3DS fields
3DS, secure mode ve challenge sonrası oluşan güvenlik alanları provider'a göre değişebilir. Public modelde bu alanlar sınırlı, maskelenmiş ve normalized tutulmalıdır.
Örnek:
{
"security": {
"secureModeUsed": true,
"threeDSResult": "authenticated",
"liabilityShift": "unknown_or_provider_specific"
}
}Bu örnek conceptual'dır; gerçek provider security payload'larını veya hassas alanları public dokümana taşımayın.
Event payload ilişkisi
Webhook/event payload'ları Payment state değişikliklerini merchant backend'e taşır. Charge detayları event içinde özetlenebilir veya API üzerinden sorgulanabilir.
Merchant order state'i için Payment event'lerine güvenin; provider attempt analizi için Charge ve Routing trace alanlarını kullanın.
Örnek JSON
{
"object": "payment",
"id": "pay_123",
"amount": 100000,
"currency": "TRY",
"status": "SUCCEEDED",
"metadata": { "order_id": "ord_987" },
"charges": [
{
"object": "charge",
"id": "ch_1",
"payment_id": "pay_123",
"attempt_no": 1,
"status": "DECLINED",
"amount": 100000,
"routing_origin": "merchant_direct"
},
{
"object": "charge",
"id": "ch_2",
"payment_id": "pay_123",
"attempt_no": 2,
"status": "CAPTURED",
"amount": 100000,
"routing_origin": "fallback"
}
]
}Backward compatibility notları
- Public response alanları migration sırasında geriye uyumluluk gözetilerek evrilmelidir.
- Private database column isimleri public API contract'ı değildir.
- Merchant entegrasyonu raw provider response yerine normalized model üstüne kurulmalıdır.
- Yeni provider capability veya result family eklendiğinde docs ve SDK davranışı birlikte güncellenmelidir.