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

# Genel Bilgiler

Bu rehber, Fincraft Payment API ile test ortamında ilk entegrasyonunuzu tamamlamanız için gereken adımları içerir. Kimlik doğrulama tamamlandıktan sonra ödeme, sorgulama ve iptal/iade endpoint'lerine geçebilirsiniz.

|                      |                                    |
| -------------------- | ---------------------------------- |
| **Test Base URL**    | `https://api-test.fincraft.com.tr` |
| **API prefix**       | `/api/v1`                          |
| **Kimlik doğrulama** | Bearer Token                       |
| **Content-Type**     | `application/json`                 |
| **Encoding**         | `UTF-8`                            |

<Note>
  Test ortamı gerçek para hareketi gerçekleştirmez. Canlı ortama geçmeden önce tüm akışları `api-test.fincraft.com.tr` üzerinden doğrulayın.
</Note>

## Kimlik doğrulama

API erişimi için önce `POST /auth/login` ile Bearer Token alınır. İstekte **API Key** ve **API Secret** kullanılır.

<Steps>
  <Step title="API Key ve Secret'ı birleştirin">
    Değerleri `apiKey:apiSecret` formatında birleştirin.

    ```text theme={null}
    API_KEY:API_SECRET
    ```
  </Step>

  <Step title="Base64 encode edin">
    ```bash theme={null}
    echo -n "apiKeyBilginiz:apiSecretBilginiz" | base64
    ```
  </Step>

  <Step title="Login isteği gönderin">
    ```bash theme={null}
    curl -X POST https://api-test.fincraft.com.tr/auth/login \
      -H "Authorization: Basic BASE64_ENCODED_VALUE" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json"
    ```
  </Step>

  <Step title="accessToken ile istek atın">
    ```http theme={null}
    Authorization: Bearer ACCESS_TOKEN
    Content-Type: application/json
    ```
  </Step>
</Steps>

### Login yanıtı

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

| Parametre     | Tip    | Açıklama                                            |
| ------------- | ------ | --------------------------------------------------- |
| `accessToken` | String | Sonraki tüm API isteklerinde kullanılacak JWT token |

<Tip>
  Detaylı kimlik doğrulama adımları ve hata senaryoları için [Kimlik Doğrulama](/api-reference/authentication) sayfasına bakın.
</Tip>

## İlk ödeme isteği

Token aldıktan sonra non-secure ödeme akışıyla test ödemesi oluşturabilirsiniz:

```bash theme={null}
curl -X POST https://api-test.fincraft.com.tr/api/v1/payments/card \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100,
    "finalAmount": 100,
    "walletAmount": 0,
    "installment": 1,
    "clientIpAddress": "192.168.1.1",
    "currency": "TRY",
    "transactionType": "AUTH",
    "card": {
      "cardHolderName": "Test Kullanıcı",
      "cardNumber": "5218487962459752",
      "expireMonth": "09",
      "expireYear": "28",
      "cvc": "000"
    },
    "products": [
      {
        "name": "Test Ürün",
        "externalId": "PROD-001",
        "price": 100
      }
    ]
  }'
```

<Warning>
  Test kart numaraları ve senaryolar için [Test Kartları](/fincraft/genel/test-kartlari) sayfasını kullanın. Gerçek kart bilgisi test ortamında göndermeyin.
</Warning>

## HTTP durum kodları

| Kod   | Açıklama                              |
| ----- | ------------------------------------- |
| `200` | İstek başarılı                        |
| `400` | Geçersiz istek veya validasyon hatası |
| `401` | Kimlik doğrulama başarısız            |
| `403` | Erişim reddedildi                     |
| `404` | Kayıt bulunamadı                      |
| `500` | Sunucu hatası                         |

## Kimlik doğrulama hataları

| Durum                         | Olası neden                                |
| ----------------------------- | ------------------------------------------ |
| `401 Unauthorized`            | API Key veya Secret hatalı                 |
| Geçersiz Authorization header | Basic encode formatı hatalı                |
| Bearer token eksik            | Ödeme isteğinde token gönderilmedi         |
| Token süresi doldu            | Yeniden `POST /auth/login` çağrısı gerekir |

## Güvenlik önerileri

* API Secret değerini frontend kodunda veya public repolarda saklamayın
* Kimlik bilgilerini ortam değişkeni veya secret manager üzerinden yönetin
* `accessToken` değerini loglara yazmayın
* Canlı ortamda yalnızca HTTPS kullanın

```text theme={null}
```

## Sonraki adımlar

<CardGroup cols={2}>
  <Card title="Non-Secure Ödeme" icon="credit-card" href="/fincraft/non-secure/odeme-olustur">
    Kart ile doğrudan ödeme oluşturma endpoint'i.
  </Card>

  <Card title="3D Secure" icon="shield-check" href="/fincraft/3d-secure/3d-odeme-baslat">
    3D Secure başlatma ve tamamlama akışı.
  </Card>

  <Card title="İşlem Sorgulama" icon="search" href="/fincraft/sorgulamalar/order-id-getir">
    Order ID veya Reference ID ile ödeme detayı.
  </Card>

  <Card title="Hata Kodları" icon="circle-alert" href="/fincraft/genel/hata-kodlari">
    Tüm sistem ve banka hata kodları.
  </Card>
</CardGroup>