Cüzdanla Öde — Payment

paymentMethod: "WALLET" ile POST /payments/direct/payment, alıcının cüzdanından ödeme alır. Alıcı telefonuna gelen tek seferlik kodla ödemeyi onaylar; kodu siz confirm ile gönderirsiniz. Bu sayfa cüzdanla ödemenin bütün istek alanlarını, yanıtını, onayını ve hatalarını gösterir; bütün yöntemlerde ortak olan aksiyon, confirm ve hata kodu kuralları Payment sayfasındadır.

Hesabınızda kullanılabilen cüzdanlar GET /payments/methods yanıtında WALLET satırının providers listesindedir. İşletmenizin kendi cüzdan programı bağlıysa o da bu listede, programınızın adı ve logosuyla yer alır.

Nasıl çalışır

Sağlayıcıyı seçme

Cüzdanda sağlayıcıyı alıcı seçer: WALLET satırında providerSelectionMode BUYER'dır. Platform alıcı adına cüzdan seçmez.

• Tek cüzdan bağlıysa wallet.providerCode gönderilmesi gerekmez; o cüzdan kullanılır. Yöntem satırında providerSelection OPTIONAL'dır.
• Birden fazla cüzdan bağlıysa WALLET satırının providers[] listesini (displayName, logoUrl) alıcıya gösterin ve seçtiği cüzdanın providerCode'unu wallet.providerCode ile gönderin. Yöntem satırında providerSelection REQUIRED'dır. Kodu göndermezseniz istek 400 payment.provider.required alır; bağlı kodlar details.boundProviderCodes içindedir.
• Gönderdiğiniz kod hesabınızda bu yönteme bağlı değilse istek 422 payment.provider.not_available alır.
• Seçilen cüzdan ödemeye sabitlenir: hata olursa başka cüzdana, başka yönteme ya da karta geçilmez.

Seçim modları ve providerSelection ile ilişkisi: Yöntemleri Listeleme › Sağlayıcı seçimi.

İstek

POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment
Content-Type: application/json

İstek Step-Up kimlik doğrulaması (Bearer token ve Ed25519 imza başlıkları; bkz. Kimlik Doğrulama) ve zorunlu Idempotency-Key başlığı (en fazla 200 karakter) taşır; kurallar Payment — Idempotency ile aynıdır.

Yöntem alanları

Gövdede yalnız wallet bloğu bulunur: başka bir yöntemin bloğu ya da card, force3D, installment, installmentQuoteToken gönderilirse istek 400 VALIDATION_ERROR alır.

Sipariş alanları

Tutar yalnız amount ile gönderilir; kaldırılan tutar alanları 400 payment.amount.field_removed alır. Tanımlı olmayan bir alan gönderirseniz istek 400 VALIDATION_ERROR ile reddedilir.

Cüzdanla ödemede customerId alıcıyı tanımlar ve işletmenin cüzdan programında önerilir; bkz. Alıcı kimliği. buyer.gsmNumber, wallet.gsmNumber gönderilmezse kullanılır.

buyer

buyer opsiyoneldir. Gönderirseniz aşağıdaki "Evet" alanlarının hepsi dolu olmalıdır. Checkout Formu intent'inde (POST /payments/intents, POST /payments/marketplace/intents) bu zorunluluk yoktur: alanların hepsi isteğe bağlıdır, gönderdiğiniz alanların tipi ve uzunluğu doğrulanır.

Zorunluluk kuralı, customerId ile farkı ve hata alan yolları: Alıcı Bilgileri.

Adres

shippingAddress ve billingAddress aynı yapıdadır. Nesneyi gönderirseniz beş alan da zorunludur.

İki adresin farkı ve hata alan yolları: Adres Bilgileri.

basketItems[]

Kalemlerin price toplamı amount'a eşit olmalıdır; eşit değilse istek 400 VALIDATION_ERROR ile reddedilir. Vade farkı kalemlere yazılmaz.

Örnek istek

# Step-Up imza başlıklarının nasıl hesaplandığı için Kimlik Doğrulama sayfasına bakın.
curl -X POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment \
  -H "Authorization: Bearer at_test_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: mk_test_sk_..." \
  -H "X-Date: 2026-10-11T09:00:00.000Z" \
  -H "X-Nonce: 4a7e1c92-3b5d-4f60-8e2a-9c1d7b3e5f08" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORDER-1004-1" \
  -d '{
    "paymentMethod": "WALLET",
    "orderId": "ORDER-1004",
    "amount": 12500,
    "currency": "TRY",
    "customerId": "CUST-2",
    "wallet": { "providerCode": "<providerCode>", "gsmNumber": "+905321234567" }
  }'

Alıcı kimliği

İşletmenizin cüzdan programıyla ödemede cüzdan iki bilgiyle bulunur:

• customerId: Alıcıyı cüzdan programınızdaki müşteri kaydıyla eşler. Gönderdiğinizde telefon yalnız doğrulama için kullanılır; telefon o müşterinin kayıtlı numarasıyla eşleşmezse istek reddedilir.
• wallet.gsmNumber: Telefon her durumda gereklidir. Doğrulama kodu bu numaraya gider; kod, ödeyen kişinin cüzdanın sahibi olduğunu kanıtlar. Alan gönderilmezse buyer.gsmNumber kullanılır. İkisi de yoksa ya da numaranın biçimi bozuksa istek 400 payment.method.block_invalid alır ve details.field wallet.gsmNumber olur.

Alıcının kimliği yalnız customerId alanından okunur. metadata.customerId tek başına gönderilirse ya da customerId'den farklıysa istek 400 payment.method.customer_identity_conflict alır.

Yanıt ve aksiyon

{
  "status": "partial",
  "code": "CUSTOMER_ACTION_REQUIRED",
  "message": "…",
  "data": {
    "paymentId": "3a8d5f1c-6b2e-4c9a-8e7d-1f0b2c3d4e5f",
    "orderId": "ORDER-1004",
    "status": "INITIATED",
    "paymentMethod": "WALLET",
    "providerCode": "<providerCode>",
    "action": {
      "id": "act_8e1f2a3b4c5d6e7f8091a2b3c4d5e6f7",
      "type": "OTP",
      "expiresAt": "2026-10-11T09:03:00.000Z",
      "otp": { "maskedTarget": "53****67" },
      "charge": {
        "amount": 12500,
        "feeTotal": 250,
        "taxTotal": 50,
        "buyerTotalCharge": 12800,
        "currency": "TRY"
      },
      "maskedBusinessName": "Ör*** Ma*****"
    }
  },
  "statusCode": 202,
  "requestId": "…"
}

İşletmenizin cüzdan programıyla ödemede ödeme, kod onaylanana kadar INITIATED durumunda kalır.

Onay

{ "otp": "123456" }

POST /payments/{paymentId}/actions/{actionId}/confirm ile gönderin; kimlik doğrulama ve sonuç tablosu Payment — confirm ile aynıdır.

• Yanlış kod 422 payment.action.input_rejected alır; aksiyon açık kalır ve kalan hak details.attemptsRemaining içindedir. İşletmenizin cüzdan programında hak 3'tür.
• İşletmenizin cüzdan programında kod yeniden gönderilemez: resend 422 payment.action.resend_not_supported alır. Kodun süresi dolarsa yeni bir ödeme başlatın.

Sonuç

İşletmenizin cüzdan programıyla ödemede:

• Ret yanıtında data.status INITIATED kalabilir; para hareket etmemiştir ve payment.failed gönderilmez. Yeniden denemek için yeni bir Idempotency-Key ile yeni ödeme başlatın. Tamamlanmayan ödeme kaydı 24 saat sonra EXPIRED olur.
• Aksiyonun süresi onay gönderilmeden dolarsa aksiyon kapanır, ödeme INITIATED kalır.

Sık görülen cüzdan kodları:

Ön provizyon

Bir cüzdanın ön provizyonu destekleyip desteklemediği GET /payments/methods yanıtındaki preauth alanındadır. Desteklemeyen cüzdanla preauth: true gönderilirse istek ödeme başlamadan 422 payment.preauth.unsupported_for_method alır. İşletmenizin cüzdan programı ön provizyonu desteklemez.

Hatalar

Diğer kodlar: Payment — Hata kodları.

Webhook'lar

Olayların data'sında paymentMethod: "WALLET" ve cüzdanın providerCode'u bulunur. Bkz. Webhook'lar.

Sonraki adımlar

• Payment — ortak istek, yanıt ve hata kodları
• Yöntemleri Listeleme — bağlı cüzdanlar ve sağlayıcı seçimi
• Checkout Formu — Payment — cüzdanla ödemenin formdaki akışı