> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orkesta.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Ödeme Oluştur

> Kart ile ödeme işlemi oluşturur

## 💳 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`

<Info>
  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.
</Info>

<Warning>
  **⚠️ Ö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
</Warning>

## Request Body

```json theme={null}
{
  "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"
  },
  "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.                                                         |
| `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

```json theme={null}
{
    "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

```bash theme={null}
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
    }
  }'
```

<Check>
  **Ö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
</Check>