Para Transferi

Bağlantınız transfer destekliyorsa bağlı banka hesabınızdan bir IBAN'a para gönderebilirsiniz. Bir bağlantının transfer destekleyip desteklemediğini Bağlantılar ucundaki capabilities alanından okursunuz: listede OUTGOING_TRANSFER varsa bu bağlantının hesaplarından transfer yapılabilir.

API anahtarıyla gönderilen transferde e-posta doğrulama kodu istenmez. Onay; anahtarınızın yetkisi, isteğin imzası ve isteğin IP izin listesindeki bir adresten gelmesidir. Transfer oluşturulduğu anda SUBMITTED durumuna geçer ve bankaya iletilmek üzere sıraya alınır. Transferin hangi yoldan gideceğini (hesaplarınız arası, aynı banka içi, FAST ya da EFT) banka belirler.

Uçlar

Bütün uçların yetkisi bank-connect:transfer'dır. Ortamı anahtarınız belirler; istekte environment gönderilmez.

Gövdeli isteği imzalama

Okuma uçlarının imzası API'ye Giriş sayfasındaki gibidir. POST isteklerinde gövdenin SHA-256 özeti Digest başlığında gönderilir ve kanonik dizinin son satırı olur. Bu sayfadaki cURL örnekleri aşağıdaki kabuk fonksiyonunu kullanır:

# lunixi-sign.sh — Kullanım: source lunixi-sign.sh; lunixi_sign POST "/api/v1/bank-connect/transfers" "$BODY"
LUNIXI_KEY_ID="mk_test_..."
LUNIXI_KEY_FILE="lunixi-signing.key"
 
lunixi_sign() {
  local method="$1" req_path="$2" body="$3"
  DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  NONCE=$(openssl rand -hex 16)
  if [ -n "$body" ]; then
    DIGEST="SHA-256=$(printf '%s' "$body" | openssl dgst -sha256 -binary | base64)"
    printf '%s\n%s\nX-Date:%s\nX-Nonce:%s\nDigest:%s' "$method" "$req_path" "$DATE" "$NONCE" "$DIGEST" > canonical.txt
  else
    DIGEST=""
    printf '%s\n%s\nX-Date:%s\nX-Nonce:%s' "$method" "$req_path" "$DATE" "$NONCE" > canonical.txt
  fi
  SIGNATURE=$(openssl pkeyutl -sign -inkey "$LUNIXI_KEY_FILE" -rawin -in canonical.txt | base64 | tr -d '\n')
}

PHP örnekleri PHP SDK'nın 0.22.0 ve üstü sürümünü kullanır; $bankConnect->transfers() bu sayfadaki uçları çağırır ve her isteği imzalar.

Ödeme amaçları

GET /api/v1/bank-connect/transfer-purposes?connectionId={connectionId}

Bankanın bu bağlantıda kabul ettiği ödeme amacı kodlarını döner. Transferde paymentPurpose alanına bu kodlardan birini yazabilirsiniz; alanı göndermezseniz bankanın varsayılanı kullanılır.

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "items": [
      { "code": "OTHER", "name": "Diğer", "order": 1 },
      { "code": "RENT", "name": "Kira", "order": 2 }
    ]
  },
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Kodlar bankaya göre değişir; listeyi sabit kodlamayın, bu uçtan okuyun.

Transfer oluşturma

POST /api/v1/bank-connect/transfers

Gövdede başka bir alan (environment, merchantId …) gönderilirse istek 400 VALIDATION_ERROR alır.

source lunixi-sign.sh
REQ_PATH="/api/v1/bank-connect/transfers"
BODY='{"accountId":"00000000-0000-0000-0000-000000000100","receiverIban":"TR000000000000000000000000","receiverName":"Örnek Tedarik A.Ş.","amountMinor":150075,"description":"Fatura 2026-0042"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: payout-2026-0042" \
  --data-raw "$BODY"

Örnekteki IBAN yer tutucudur; kontrol hanesi geçerli bir IBAN gönderin.

Başarılı yanıt 201 döner:

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "transfer": {
      "id": "00000000-0000-0000-0000-000000002000",
      "connectionId": "00000000-0000-0000-0000-000000000010",
      "accountId": "00000000-0000-0000-0000-000000000100",
      "environment": "live",
      "status": "SUBMITTED",
      "rail": null,
      "amountMinor": 150075,
      "currency": "TRY",
      "sourceIbanMasked": "TR00 **** **** **** **** **00 00",
      "receiverIbanMasked": "TR00 **** **** **** **** **00 00",
      "receiverNameMasked": "Ö**** T****** A.Ş.",
      "receiverBankCode": "0000",
      "paymentPurpose": null,
      "description": "Fatura 2026-0042",
      "idempotencyKey": "payout-2026-0042",
      "failureCode": null,
      "outcomeUnknown": false,
      "initiatedVia": "API",
      "sanctionStatus": "NOT_SCREENED",
      "bankTransactionId": null,
      "bankState": null,
      "createdAt": "2026-01-01T07:00:00.000Z",
      "submittedAt": "2026-01-01T07:00:00.000Z",
      "completedAt": null,
      "failedAt": null,
      "returnedAt": null,
      "canceledAt": null,
      "otpExpiresAt": null
    },
    "stepUp": null,
    "replayed": false
  },
  "statusCode": 201,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Idempotency-Key

Aynı transferin iki kez gönderilmemesi için her transfer isteği bir Idempotency-Key taşır. Anahtar; organizasyonunuz ve ortam içinde tekildir.

• Anahtarı kendi sisteminizdeki ödeme kaydından türetin (ör. payout-<ödeme kimliğiniz>). Böylece süreciniz yeniden başlasa da aynı ödeme için aynı anahtarı gönderirsiniz.
• Zaman aşımı ya da ağ hatası aldığınızda isteği aynı anahtar ve aynı gövdeyle yeniden gönderin. Transfer oluştuysa mevcut transfer döner; oluşmadıysa şimdi oluşur.
• SDK'lar anahtarı siz vermezseniz kendisi üretir ve kendi yeniden denemelerinde aynı anahtarı kullanır. Kullanılan anahtar yanıttaki transfer.idempotencyKey alanındadır.

Transferi izleme

Transferin sonucu iki yoldan gelir:

• Webhook: bank_transfer.created, bank_transfer.completed, bank_transfer.failed ve bank_transfer.returned olayları. → Webhook Olayları › Transfer olayları
• Sorgu: GET /api/v1/bank-connect/transfers/{transferId}. Webhook'u kaçırdıysanız ya da endpoint'iniz yoksa transferi bu uçtan izleyin.

Durumların anlamı ve olası geçişler: Kavramlar › Transfer durumları.

Tek transfer

GET /api/v1/bank-connect/transfers/{transferId} tek bir transferi döner; data transfer nesnesinin kendisidir. Bilinmeyen, başka bir organizasyona ya da diğer ortama ait transfer 404 bank_connect.transfer.not_found döner.

source lunixi-sign.sh
REQ_PATH="/api/v1/bank-connect/transfers/00000000-0000-0000-0000-000000002000"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

Transferleri listeleme

GET /api/v1/bank-connect/transfers transferleri en yeniden eskiye listeler. Panelden ve API'den başlatılan transferler birlikte listelenir (initiatedVia).

Sayfalama kuralları okuma uçlarıyla aynıdır. → API'ye Giriş › Sayfalama

Sonucu doğrulanamayan transfer

Bankadan kesin cevap alınamadığında (ör. banka zamanında yanıt vermediğinde) transfer SUBMITTED durumunda kalır ve outcomeUnknown true olur. Bu durumda:

• Transferi yeniden göndermeyin. Para bankada çıkmış olabilir; yeni bir transfer çift ödemeye yol açabilir.
• Lunixi sonucu bankayla doğrular. Transfer sonuçlandığında durumu COMPLETED ya da FAILED olur ve ilgili webhook gönderilir.
• Banka kontrolünde transferin gerçekleşmediği anlaşılırsa failureCode bank_connect.transfer.failed_after_bank_check olur. Bu durumda aynı ödemeyi yeni bir Idempotency-Key ile yeniden gönderebilirsiniz.

Transfer nesnesi

Transfer, döviz teklifi ve döviz işlemi yanıtlarında değeri olmayan alanlar null olarak döner; alan yanıttan çıkarılmaz. Bu, okuma uçlarındaki "değer yoksa alan yoktur" kuralından farklıdır.

IBAN ve alıcı adı yalnız maskeli döner; tam IBAN ve tam ad hiçbir yanıtta yoktur. → Kavramlar › Maskeleme

Hatalar

Banka transferi reddederse istek yine 201 döner; transfer sonradan FAILED olur ve sebep failureCode alanındadır. → Hata Kodları › Transfer sonuç kodları