create-saved-card

POST /api/{team}/gateway/create-saved-card

Ödeme almadan kartı ödeme hesabında saklar. Kart, customer.reference ile adlandırılan müşterinin altında, çalışma alanının o anki modunda (test ya da canlı) saklanır. Kart saklandığında müşteri bu referansla kaydedilir ya da mevcut müşterinin boş olmayan gönderilen alanları güncellenir; saklanan kart müşterinin varsayılan kartı olur. Ödeme sırasında kart saklamak için ödeme isteğinde card.should_save: true gönderilir. Akış: Kayıtlı Kartlar rehberi.

Ön koşullar

• Çalışma alanının planı kayıtlı kartları kapsamalı ve Kayıtlı Kartlar modülü açık olmalıdır; değilse 403.
• Ödeme hesabı kart saklamalıdır; saklamıyorsa 422.

Kimlik doğrulama

X-Api-Key, X-Timestamp, X-Signature, Content-Type: application/json. Ayrıntılar: Kimlik Doğrulama ve İmza. Uç, ödeme sınırına (dakikada 60) tabidir.

İstek

{
  "saved_card": {
  },
  "customer": {
    "reference": "musteri-88",
    "billing_address": {
      "firstname": "Ahmet",
      "lastname": "Yılmaz",
      "email": "[email protected]",
      "phone": "05551112233",
      "address": "Kızılırmak Mah. Dumlupınar Blv. No:3",
      "district": "Çankaya",
      "province": "Ankara",
      "country": "TR"
    }
  },
  "card": {
    "holder_name": "AHMET YILMAZ",
    "number": "5400360000000003",
    "expiry_month": "12",
    "expiry_year": "2030",
    "security_code": "000"
  }
}

Alan	Tip	Zorunlu	Açıklama
saved_card	object	hayır	Yalnızca payment_provider_token taşır; gönderilmeyebilir.
saved_card.payment_provider_token	string (UUID)	hayır	Kartın saklanacağı ödeme hesabı. Gönderilmezse varsayılan hesap.
customer.reference	string	evet	Müşterinin sizin sisteminizdeki referansı. En çok 255 karakter.
customer.billing_address	object	evet	Sekiz kişi alanının (firstname … country) tamamı zorunlu. Alanlar: customer nesnesi.
card.holder_name	string	evet	Kart sahibinin adı. En çok 255 karakter.
card.number	string	evet	Kart numarası. Rakam ve boşluk; boşluklar çıkarıldıktan sonra 12–19 hane.
card.expiry_month	string	evet	"01"–"12".
card.expiry_year	string	evet	4 rakam.
card.security_code	string	hayır	3–4 rakam. Kartı saklarken güvenlik kodu isteyen sağlayıcılar için gönderilir; saklanmaz.

SDK örnekleri

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak. $customer / customer nesnesi secure-payment örneğindeki gibidir.

PHP

use Gurmehub\Odemehub\Request\{Card, CreateSavedCard};

$saved = $client->createSavedCard(new CreateSavedCard(
    customer: $customer,
    card: new Card(holderName: 'AHMET YILMAZ', number: '5400360000000003', expiryMonth: '12', expiryYear: '2030', securityCode: '000'),
));

$saved->savedCard?->token;   // saklanamadıysa null; nedeni $saved->result->message

Node.js

const saved = await client.createSavedCard({
    customer,
    card: { holderName: 'AHMET YILMAZ', number: '5400360000000003', expiryMonth: '12', expiryYear: '2030', securityCode: '000' },
});

saved.savedCard?.token;   // saklanamadıysa null; nedeni saved.result.message

Python

from odemehub.request import Card, CreateSavedCard

saved = client.create_saved_card(CreateSavedCard(
    customer=customer,
    card=Card(holder_name="AHMET YILMAZ", number="5400360000000003", expiry_month="12", expiry_year="2030", security_code="000"),
))

saved.saved_card   # saklanamadıysa None; nedeni saved.result.message

Java

import com.odemehub.request.Card;
import com.odemehub.request.CreateSavedCard;

var saved = client.createSavedCard(CreateSavedCard.builder()
    .customer(customer)
    .card(Card.builder().holderName("AHMET YILMAZ").number("5400360000000003").expiryMonth("12").expiryYear("2030").securityCode("000").build())
    .build());

saved.getSavedCard();   // saklanamadıysa null; nedeni saved.getResult().getMessage()

cURL

URI_PATH="/api/$ODEMEHUB_TEAM/gateway/create-saved-card"
BODY='{"customer":{"reference":"musteri-88","billing_address":{"firstname":"Ahmet","lastname":"Yılmaz","email":"[email protected]","phone":"05551112233","address":"Kızılırmak Mah. Dumlupınar Blv. No:3","district":"Çankaya","province":"Ankara","country":"TR"}},"card":{"holder_name":"AHMET YILMAZ","number":"5400360000000003","expiry_month":"12","expiry_year":"2030","security_code":"000"}}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://sandbox.odemehub.com$URI_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt

{
  "result": { "successful": true, "message": null },
  "saved_card": {
    "token": "2d4f6a8c-0e1b-4c3d-9f5e-7a9b1c3d5e6f",
    "payment_provider_token": "8e0a2c4b-6d1f-4e3a-b5c7-9d1e3f5a7b2c",
    "holder_name": "AHMET YILMAZ",
    "scheme": "mastercard",
    "first_digits": "54003600",
    "last_four_digit": "0003",
    "expiry_month": "12",
    "expiry_year": "2030",
    "is_default": true,
    "created_at": "2026-10-02T09:40:00.000000Z"
  },
  "customer": {
    "reference": "musteri-88"
  }
}

Sağlayıcı kartı saklamazsa yanıt yine 200'dür: result.successful false, result.message nedeni, saved_card null.

Alanlar: Kart nesnesi. customer.reference kartın saklandığı müşteri referansıdır.

HTTP durum kodları

Kod	Durum
200	İstek işlendi; sonuç result.successful içinde.
401	API anahtarı ya da imza geçersiz.
403	Çalışma alanı işlem yapamıyor, planı kayıtlı kartları kapsamıyor ya da Kayıtlı Kartlar modülü kapalı.
422	Doğrulama hatası.
429	İstek sınırı aşıldı.

Hatalar

Alan	Mesaj
saved_card.payment_provider_token	Bu ödeme hesabı kart saklamayı desteklemiyor. / Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.
customer.reference	Müşteri referansı (customer.reference) zorunludur.
card.number	Kart numarası yalnızca rakamlardan oluşmalıdır. / Kart numarası 12 ile 19 hane arasında olmalıdır. / Kart numarası geçersiz; lütfen kontrol edin.
card.expiry_month	Son kullanma ayı 01 ile 12 arasında iki haneli olmalıdır (ör. 05).
card.expiry_year	Son kullanma yılı dört haneli olmalıdır (ör. 2030).