💳 Kart ile Ödeme (Card Payment)
Kredi kartı bilgileri ile güvenli ödeme işlemi oluşturur.POST https://api-test.fincraft.com.tr/api/v1/payments/card
Bu endpoint, kredi kartı bilgileri ile güvenli ödeme işlemi oluşturmak için kullanılır. Risk kontrolü yapılır ve banka entegrasyonu ile ödeme gerçekleştirilir.
⚠️ Önemli Güvenlik Notları
- Tüm kart bilgileri PCI DSS standartlarına uygun şekilde işlenir
- Kart numaraları hiçbir zaman loglanmaz veya saklanmaz
- SSL/TLS şifreleme zorunludur (HTTPS)
- IP adresi doğrulaması yapılır
- Fraud detection sistemleri aktif olarak çalışır
- 3D Secure desteği mevcuttur
Request Body
{
"correlationId": "string",
"referenceId": "uuid",
"amount": 100.50,
"finalAmount": 100.50,
"walletAmount": 0.0,
"installment": 1,
"clientIpAddress": "192.168.1.1",
"walletMemberId": "string",
"currency": "TRY",
"transactionType": "AUTH",
"card": {
"cardAlias": "string",
"cardHolderName": "John Doe",
"cardNumber": "1234567890123456",
"expireYear": "25",
"expireMonth": "12",
"cvc": "123"
},
"products": [
{
"name": "Ürün Adı",
"externalId": "string",
"price": 100.50,
"subMerchantPrice": 95.0,
"subMerchantMemberId": "string"
}
],
"additionalParams": {
"key": "value"
},
"bankOrderId": "string",
"additionalData": "{\"msisdn\":\"\"}",
"reward": {
"cardRewardAmount": 5,
"firmRewardAmount": null
}
}
Request Parametreleri
| Parametre | Tip | Zorunlu | Validation | Açıklama |
|---|---|---|---|---|
correlationId | String | Hayır | - | İşlem takibi için kullanılan benzersiz korelasyon ID’si. |
referenceId | UUID | Evet | @NotNull | Harici sistemlerden gelen ödeme işlemi için benzersiz referans numarası. |
amount | Double | Evet | @DecimalMin(0.01) | Kredi kartından çekilecek net tutar. |
finalAmount | Double | Evet | @DecimalMin(0.01) | Müşteriden alınacak toplam tutar. |
walletAmount | Double | Evet | @DecimalMin(0.0) | Müşteri cüzdanından kullanılacak tutar. |
installment | Integer | Hayır | @Min(1) | Taksit sayısı. 1 = peşin ödeme. |
clientIpAddress | String | Evet | @NotNull | Müşterinin gerçek IP adresi. |
walletMemberId | String | Hayır | - | Cüzdan kullanılacaksa, cüzdan sahibinin dış sistemdeki üye ID’si. |
currency | Currency | Evet | @NotNull | Para birimi. TRY, USD, EUR. |
transactionType | TransactionType | Hayır | - | İşlem türü. Default: AUTH |
card | CardDTO | Evet | @Valid | Kredi kartı bilgileri. |
products | List | Evet | @NotEmpty, @Valid | Satın alınan ürünlerin listesi. |
additionalParams | Map | Hayır | - | Ek parametreler. |
bankOrderId | String | Hayır | - | İzin verilen terminallere iletilecek banka sipariş numarası. Zorunlu değildir; gönderilmediği durumda otomatik olarak üretilir. |
additionalData | String | Hayır | - | Sağlayıcıya iletilecek ek veriler; JSON string beklenir. Örn (Paycell için): {"msisdn":""}. |
reward | RewardDTO | Hayır | - | Puan kullanım bilgileri. |
CardDTO Parametreleri
| Parametre | Tip | Zorunlu | Validation | Açıklama | |
|---|---|---|---|---|---|
cardAlias | String | Hayır | - | Kart için takma ad. | |
cardHolderName | String | Evet | @NotBlank | Kart üzerine yazılı olan kart sahibinin tam adı. | |
cardNumber | String | Evet | Kart numarası. | ||
expireYear | String | Evet | Son kullanma yılı (YY formatı). | ||
expireMonth | String | Evet | @Pattern(^(0[1-9] | 1[0-2])$) | Son kullanma ayı (01-12). |
cvc | String | Evet | @NotBlank | Kart güvenlik kodu. |
ProductDTO Parametreleri
| Parametre | Tip | Zorunlu | Validation | Açıklama |
|---|---|---|---|---|
name | String | Evet | @NotBlank | Ürün adı. |
externalId | String | Hayır | - | Harici sistemdeki ürün ID’si. |
price | Double | Evet | @DecimalMin(0.01) | Ürünün satış fiyatı. |
subMerchantPrice | Double | Hayır | @DecimalMin(0.0) | Alt bayinin alacağı tutar. |
subMerchantMemberId | String | Hayır | - | Alt bayi üye ID’si. |
Response Body
{
"message": "Ödeme başarıyla oluşturuldu",
"response": {
"cardDetails": {
"cardHolderName": "Muammer Şahin",
"cardNumber": "521848****9752",
"cardBrand": "BONUS",
"cardBank": "TFKB",
"cardSchema": "MASTERCARD"
},
"id": "25282QdQI07035347",
"createdDate": "2025-10-09 16:29:16",
"amount": 100.0,
"finalAmount": 100.0,
"walletAmount": 0.0,
"currency": "TRY",
"installment": 1,
"correlationId": "CONV-1760016535238",
"usedTerminalInfo": "ISBANK_CONFIG_1",
"reward": {
"cardRewardAmount": 5,
"firmRewardAmount": null
},
"referenceId": "54da6e5c-2fa3-480a-bd04-53716b01d688",
"source": "API",
"paymentStatus": "SUCCESS",
"transactionType": "AUTH",
"authCode": "P82141",
"hostReferenceNo": "528200439774",
"transactionId": "25282QdQI07035347",
"orderId": "f5acb745-8b97-4624-b919-0bec8a2b1c73",
"bankCardHolderName": "Muammer Şahin",
"bankCode": "010",
"products": [
{
"name": "Test Product",
"externalId": "PROD-002",
"price": 100.0,
"status": "PENDING",
"commissionRate": 0,
"id": "08df4f3b-1c61-42c7-b205-5054e6e78ab9"
}
],
"riskAssessment": "APPROVED"
}
}
cURL Örneği
curl -X POST https://api-test.fincraft.com.tr/api/v1/payments/card \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"correlationId": "{{conversation_id}}",
"referenceId": "{{$guid}}",
"amount": 100,
"finalAmount": 100,
"installment": 1,
"clientIpAddress": "192.168.1.1",
"currency": "TRY",
"transactionType": "AUTH",
"card": {
"cardHolderName": "Muammer Şahin",
"cardNumber": "5218487962459752",
"expireMonth": "09",
"expireYear": "28",
"cvc": "000"
},
"products": [
{
"name": "Test Product",
"externalId": "PROD-002",
"price": 100
}
],
"reward": {
"cardRewardAmount": 5,
"firmRewardAmount": null
}
}'
Önemli Notlar
- Kart numarası 13-19 haneli olmalıdır
- CVC kodu 3-4 haneli olmalıdır
- Taksit sayısı minimum 1 olmalıdır
- IP adresi geçerli bir IPv4 formatında olmalıdır
- Para birimi TRY, USD, EUR desteklenir
- Ürün listesi en az 1 ürün içermelidir
- Risk kontrolü geçmeyen işlemler otomatik reddedilir
- 3D Secure gerektiren kartlar için ayrı endpoint kullanılmalıdır