> ## 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.

# Saklı Kart Kayıt Başlat

> 3D Secure doğrulama ile saklı kart kaydı işlemini başlatır

## 🔐 Saklı Kart Kayıt Başlat (Store Card 3D Init)

3D Secure güvenlik protokolü ile kart saklama işlemini başlatır. Kullanıcıya banka tarafından gönderilen HTML form döndürülür.

**`POST`** `https://api-test.fincraft.com.tr/api/v1/payments/store-card/3d/init`

<Warning>
  **İşlem Akışı**

  * Kullanıcının kartından doğrulama amaçlı **1 TL** çekilir.
  * İşlem tamamlandıktan sonra çekilen **1 TL otomatik olarak iade** edilir.
  * Başarılı işlem sonucunda `token` değeri complete response içerisinde döner ve saklı kart olarak kullanılabilir.
  * Saklı kart ile ödeme sırasında `card` alanında sadece `cardToken` gönderilerek işlem tamamlanabilir.
</Warning>

<Info>
  **Dikkat**: Kullanılacak PSP'nin **CVV'siz ödeme** kabul ediyor olması gerekmektedir.
</Info>

## Request Body

```json theme={null}
{
  "correlationId": "string",
  "referenceId": "uuid",
  "clientIpAddress": "192.168.1.1",
  "callbackUrl": "https://example.com/callback",
  "currency": "TRY",
  "card": {
    "cardHolderName": "John Doe",
    "cardNumber": "1234567890123456",
    "expireMonth": "12",
    "expireYear": "26",
    "cvc": "123",
    "userKey": "string"
  }
}
```

## 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 işlem için benzersiz referans numarası. |
| `clientIpAddress` | String | Evet | @NotNull | Müşterinin gerçek IP adresi. |
| `callbackUrl` | String | Evet | @NotBlank, @URL | 3D Secure doğrulama tamamlandıktan sonra kullanıcının yönlendirileceği URL. HTTPS olmalıdır. |
| `currency` | Currency | Evet | @NotNull | Para birimi. TRY, USD, EUR. |
| `card` | CardDTO | Evet | @Valid | Kart bilgileri. |

## CardDTO Parametreleri

| Parametre | Tip | Zorunlu | Validation | Açıklama |
| - | - | - | - | - |
| `cardHolderName` | String | Evet | @NotBlank | Kart üzerine yazılı olan kart sahibinin tam adı. |
| `cardNumber` | String | Evet | @NotBlank | Kart numarası. |
| `expireYear` | String | Evet | @NotBlank | 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. |
| `userKey` | String | Evet | @NotBlank | Saklı kartın ilişkilendirileceği kullanıcı anahtarı. |

## Response Body (HTML Form)

```html theme={null}
<!DOCTYPE html>
<html>
<head>
    <title>3D Secure Doğrulama</title>
</head>
<body>
    <form id="3dsForm" method="POST" action="https://3dsecure.bank.com/verify">
        <input type="hidden" name="MD" value="merchant_data" />
        <input type="hidden" name="PaReq" value="payment_request" />
        <input type="hidden" name="TermUrl" value="https://api.fincraft.com.tr/callback" />
    </form>
    <script>
        document.getElementById('3dsForm').submit();
    </script>
</body>
</html>
```

## cURL Örneği

```bash theme={null}
curl -X POST https://api-test.fincraft.com.tr/api/v1/payments/store-card/3d/init \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "correlationId": "{{conversation_id}}",
    "referenceId": "{{$guid}}",
    "clientIpAddress": "176.55.80.107",
    "callbackUrl": "https://deneme.com",
    "currency": "TRY",
    "card": {
      "cardHolderName": "Alper Tunç Erdur",
      "cardNumber": "1000000000000016",
      "expireMonth": "12",
      "expireYear": "26",
      "cvc": "000",
      "userKey": "MuammerTest3"
    }
  }'
```

<Check>
  **Önemli Notlar**

  * `userKey` alanı zorunludur ve saklı kartın kullanıcı ile eşleşmesini sağlar.
  * Callback URL mutlaka HTTPS olmalıdır.
  * Doğrulama tamamlandıktan sonra [Saklı Kart Kayıt Tamamla](/fincraft/sakli-kart/sakli-kart-tamamla) endpoint'i çağrılmalıdır.
  * Başarısız doğrulamalarda işlem otomatik iptal edilir.
</Check>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.