save-card

POST /api/{team}/gateway/save-card

Müşterinin kartını ödeme yapmadan, ödeme hesabının sağlayıcısında saklar ve kayıtlı kart token'ını döndürür. Müşteri, ödeme uçlarındaki gibi kaydedilir ya da güncellenir. Kullanım: Kayıtlı Kartlar.

Çalışma alanının planı kayıtlı kartları kapsamıyorsa istek 403 ile reddedilir.

Kimlik doğrulama

X-Api-Key, X-Signature, Content-Type: application/json. Ayrıntılar: Kimlik Doğrulama ve İmza.

İstek

{
  "saved_card": {
    "channel_token": "6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14"
  },
  "customer": {
    "channel_reference": "musteri-88",
    "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": "Türkiye"
  },
  "card": {
    "holder_name": "AHMET YILMAZ",
    "number": "5400360000000003",
    "expiry_month": "12",
    "expiry_year": "2030"
  }
}

saved_card

Alan	Tip	Zorunlu	Açıklama
channel_token	string (UUID)	evet	Çalışma alanınıza ait kanalın token'ı.
payment_provider_token	string (UUID)	hayır	Kartın saklanacağı ödeme hesabı. Gönderilmezse varsayılan hesap. Hesabın kart saklamayı desteklemesi gerekir.

customer

Zorunlu. Alanlar: customer nesnesi.

card

Alan	Tip	Zorunlu	Açıklama
holder_name	string	evet	En çok 255 karakter.
number	string	evet	12–19 karakter.
expiry_month	string	evet	2 karakter.
expiry_year	string	evet	4 karakter.
security_code	string	hayır	3–4 karakter. Bazı sağlayıcılar kart saklarken kullanır; gateway saklamaz.

SDK örnekleri

PHP

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

$kept = $client->saveCard(new SaveCard(
    customer: $customer, // Customer nesnesi, bkz. secure-payment
    card: new Card(
        holderName: 'AHMET YILMAZ',
        number: '5400360000000003',
        securityCode: '000',
        expiryMonth: '12',
        expiryYear: '2030',
    ),
));

if ($kept->result->successful) {
    $savedCardToken = $kept->savedCard->token;
}

Node.js

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

if (kept.result.successful) {
    const savedCardToken = kept.savedCard!.token;
}

Python

from odemehub.request import Card, SaveCard

kept = client.save_card(SaveCard(
    customer=customer,
    card=Card(
        holder_name="AHMET YILMAZ",
        number="5400360000000003",
        security_code="000",
        expiry_month="12",
        expiry_year="2030",
    ),
))

if kept.result.successful:
    saved_card_token = kept.saved_card.token

Java

import com.odemehub.request.Card;
import com.odemehub.request.SaveCard;

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

if (kept.getResult().isSuccessful()) {
    String savedCardToken = kept.getSavedCard().getToken();
}

cURL

BODY='{"saved_card":{"channel_token":"6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14"},"customer":{"channel_reference":"musteri-88","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":"Türkiye"},"card":{"holder_name":"AHMET YILMAZ","number":"5400360000000003","expiry_month":"12","expiry_year":"2030"}}'
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://odeme.gurmehub.com/api/$ODEMEHUB_TEAM/gateway/save-card" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt

{
  "result": {
    "successful": true,
    "message": null
  },
  "saved_card": {
    "token": "7d3e9a10-2b4c-4f6e-8a1b-c2d3e4f5a6b7",
    "payment_provider_token": "1c9e8f7a-6b5d-4c3e-2a1f-0e9d8c7b6a54",
    "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-09-29T10:15:00.000000Z"
  },
  "customer": {
    "channel_reference": "musteri-88"
  }
}

Alan	Tip	Açıklama
result.successful	boolean	true: kart saklandı. false: sağlayıcı kartı saklamadı.
result.message	string | null	successful false ise nedeni.
saved_card	object | null	Saklanan kart (kart nesnesi); saklanamadıysa null.
customer.channel_reference	string	Müşterinin channel_reference değeri.

Müşterinin ilk kayıtlı kartı varsayılan kart olur (is_default: true).

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 ya da planı kayıtlı kartları kapsamıyor.
422	Doğrulama hatası.

Hatalar

Alan	Mesaj
saved_card.payment_provider_token	Bu ödeme hesabı kart saklamayı desteklemiyor.
saved_card.payment_provider_token	Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.