Ana içeriğe geç

PHP SDK

Kurulum​

PHP 8.2 ve üzeri gerekir; HTTP için Guzzle kullanılır.

composer require odemehub/php-sdk

Bu sayfa 1.0.8 sürümünü anlatır. Önceki sürümlerden geçiş için: 1.0.8, 1.0.7, 1.0.6, 1.0.5, 1.0.4, 1.0.3, 1.0.2. 1.0.0 bugünkü gateway'le çalışmaz; geçiş için: 1.0.1'deki kırıcı değişiklikler.

İstemci​

use Gurmehub\Odemehub\Client;
use Gurmehub\Odemehub\Options;

$client = new Client(new Options(
baseUrl: 'https://sandbox.odemehub.com',
team: getenv('ODEMEHUB_TEAM'), // Çalışma Alanı Kimliği
apiKey: getenv('ODEMEHUB_API_KEY'),
apiSecret: getenv('ODEMEHUB_API_SECRET'),
));

Client ikinci parametre olarak bir GuzzleHttp\ClientInterface alır; verilmezse 60 saniye zaman aşımlı bir Guzzle istemcisi kullanılır.

  • Her uç için uçla aynı adı taşıyan bir metot vardır: create-order → createOrder(), retrieve-saved-cards → retrieveSavedCards(). Liste: SDK'lar.
  • İstek sınıfları Gurmehub\Odemehub\Request, yanıt sınıfları Gurmehub\Odemehub\Response, sabit kümeler Gurmehub\Odemehub\Enum, istisnalar Gurmehub\Odemehub\Exception ad alanındadır.
  • Yanıtlar API JSON'unu birebir izler: $payment->transaction->token, $details->order->checkoutUrl. Sabit kümeli alanlar (currency, status, period …) enum'dur; SDK'nın bilmediği bir değer gelirse alan null olur.
  • Tek bir kaydı adlandıran istek alanı her zaman token'dır. Bir alanı boşaltmak için Update* isteklerinde clear: ['description'] verilir.

Müşteri ve kart​

use Gurmehub\Odemehub\Request\{Address, Card, PaymentCustomer};

$billingAddress = new 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',
// companyTitle: '...', taxNumber: '...', taxOffice: '...',
);

$customer = new PaymentCustomer(billingAddress: $billingAddress, reference: 'musteri-88');

$card = new Card(
holderName: 'AHMET YILMAZ',
number: '5400360000000003',
expiryMonth: '12',
expiryYear: '2030',
securityCode: '000',
shouldSave: false,
);

Ödeme ve kart saklama istekleri PaymentCustomer alır; gönderim adresi yoktur. Fatura adresi zorunludur; Varsayılan Ödeyen açıksa billingAddress'i ya da alanlarından bazılarını vermeyebilirsiniz, eksikler varsayılan ödeyenden tamamlanır. Ödemede new PaymentCustomer() customer'ı gövdeden tamamen çıkarır; CreateSavedCard'da reference yine zorunludur. Sipariş ve abonelik Customer alır; orada billingAddress ve shippingAddress isteğe bağlıdır.

Card nesnesi var_dump ve benzeri çıktılarda kart numarasını ve güvenlik kodunu ***** olarak gösterir.

Regular ödeme​

use Gurmehub\Odemehub\Request\RegularPayment;

$payment = $client->regularPayment(new RegularPayment(
reference: 'SIP-10231',
amount: '450.00',
installmentNumber: 1,
ip: $_SERVER['REMOTE_ADDR'],
customer: $customer,
card: $card,
));

if ($payment->result->successful) {
$payment->transaction->token; // iade, iptal ve sorgu için
$payment->transaction->paymentStatus; // Enum\PaymentStatus::Paid
}

3D Secure ödeme​

use Gurmehub\Odemehub\Request\{RetrievePayments, SecurePayment};

$payment = $client->securePayment(new SecurePayment(
reference: 'SIP-10231',
amount: '450.00',
installmentNumber: 1,
ip: $_SERVER['REMOTE_ADDR'],
customer: $customer,
callbackUrl: 'https://magazam.com/odeme/donus',
card: $card,
));

if ($payment->redirectUrl !== null) {
header('Location: '.$payment->redirectUrl);
}

// callback_url işleyicisinde:
$outcome = $client->retrievePayments(RetrievePayments::byToken($_POST['transaction_token']))->payments[0] ?? null;
$outcome?->isSuccessful();

Sipariş, ödeme linki, abonelik, kayıtlı kart​

use Gurmehub\Odemehub\Request\{CreateOrder, Customer, Item, MaxInstallments};

$created = $client->createOrder(new CreateOrder(
reference: 'SIP-10233',
successUrl: 'https://magazam.com/tesekkurler',
items: [new Item(name: 'Kahve makinesi', unitAmount: '450.00', quantity: 1, taxRate: '20')],
customer: new Customer(reference: 'musteri-88', billingAddress: $billingAddress),
requiresShipping: true, // ödeme sayfasında gönderim yöntemi seçilir, ücreti tutara eklenir
locksCustomer: true, // müşteri bilgisi sorulmaz, gönderildiği gibi gösterilir
emailsCustomer: true, // ödeme tamamlanınca fatura adresindeki e-postaya yazılır
maxInstallments: new MaxInstallments(individual: 1, commercial: 3), // bireysel kartta tek çekim, ticari kartta en çok 3 taksit
));

header('Location: '.$created->order->checkoutUrl);

locksCustomer: true eksiksiz fatura adresi ister; requiresShipping de açıksa gönderim adresi shippingAddress'ten, verilmezse fatura adresinden alınır. Aynı üç alan UpdateOrder, CreateSubscription ve UpdateSubscription'da da vardır; Order ve Subscription yanıtları üçünü de taşır. Ödeme linkinde yalnızca emailsCustomer vardır ve e-posta, ödeyenin ödeme sayfasında verdiği adrese gider.

Diğer örnekler uç sayfalarındadır: create-order, create-payment-link, retrieve-link-payments, create-subscription, create-saved-card ve rehberler.

İade ve iptal​

use Gurmehub\Odemehub\Request\{CancelPayment, RefundPayment};

$refund = $client->refundPayment(new RefundPayment(token: $transactionToken, amount: '100.00'));
$refund->refund->amount;

$client->cancelPayment(new CancelPayment(token: $transactionToken));

Hata yönetimi​

Gateway isteği reddederse istisna atılır; reddedilen ödeme, iade ya da kart saklama istisna değildir (result->successful false).

use Gurmehub\Odemehub\Exception\{
AuthenticationException, ForbiddenException, NotFoundException, OdemehubException,
RateLimitException, SignatureException, TransportException, UnexpectedResponseException, ValidationException,
};

try {
$payment = $client->regularPayment($request);
} catch (ValidationException $e) {
$e->errors['transaction.amount'][0] ?? null; // 422
} catch (AuthenticationException $e) {
// 401
} catch (ForbiddenException $e) {
// 403
} catch (NotFoundException $e) {
// 404
} catch (RateLimitException $e) {
$e->retryAfter; // 429; beklenecek saniye (Retry-After)
} catch (SignatureException $e) {
// yanıtın imzası tutmadı
} catch (TransportException $e) {
// gateway'e ulaşılamadı; sonuç bilinmiyor
} catch (UnexpectedResponseException $e) {
$e->status; // ör. 500
}

Hepsi OdemehubException sınıfından türer. Bkz. Hatalar.

1.0.8'deki değişiklikler​

Eklenenler:

  • İş ortağı istemcisi: PartnerClient (PartnerOptions: baseUrl, apiKey, apiSecret; team yok) iş ortağının anahtarıyla /api/partner/ uçlarını çağırır: createTeam(), retrieveTeams() (sayfalı), updateTeamModules(), deleteTeam(). Yanıtlar PartnerTeamDetails, PartnerTeamList (Pagination) ve DeletedTeam; çalışma alanı PartnerTeam (slug, name, timezone, isTest, modules, gatewayUrl, apiKey, apiSecret, createdAt). teamClient($team) açılan çalışma alanının Client'ını kurar. Bkz. İş Ortakları.
  • Yalnızca iş ortağı çalışma alanlarına açık uçlar (Client üzerinde; başka çalışma alanında ForbiddenException): retrieveProviders(), createPaymentProvider(), retrievePaymentProviders(), updatePaymentProvider(), deletePaymentProvider(), createWebhookEndpoint(), retrieveWebhookEndpoints(), updateWebhookEndpoint(), deleteWebhookEndpoint(), updateTeam(), retrieveCheckoutDesign(), updateCheckoutDesign() (clear: ['logo', 'terms_url'] kaldırır) ve createLogo() (CreateLogo::fromBytes()). Yanıtlar ProviderList (Provider, ProviderField), PaymentProviderDetails, PaymentProviderList (PaymentProvider), DeletedPaymentProvider, WebhookEndpointDetails, WebhookEndpointList (WebhookEndpoint), DeletedWebhookEndpoint, TeamDetails (Team), CheckoutDesignDetails (CheckoutDesign) ve LogoDetails. Bkz. yalnızca iş ortağı çalışma alanlarına açık uçlar.

Kırıcı değişiklik yok.

1.0.7'deki değişiklikler​

Eklenenler:

  • Taksit sınırı: MaxInstallments (individual, commercial; istekte Request\MaxInstallments, yanıtta Response\MaxInstallments) ve CreateOrder, UpdateOrder, CreateSubscription, UpdateSubscription, CreatePaymentLink, UpdatePaymentLink isteklerinde maxInstallments parametresi; Order, Subscription ve PaymentLink yanıtlarında maxInstallments (yoksa null). Güncellemede iki değeri boş new MaxInstallments() sınırı kaldırır. Bkz. Taksit sınırı.

1.0.6'daki değişiklikler​

Eklenenler:

  • Banka hareketleri: retrieveBanks(), createBankAccount(), retrieveBankAccounts(), updateBankAccount(), deleteBankAccount(), retrieveBankTransactions(); yanıtlar BankList, BankAccountDetails, BankAccountList, DeletedBankAccount, BankTransactionList (Pagination, BankTransaction). Bankanın reddettiği kimlik bilgisi istisna değildir: result->successful false, bankAccount null. Bkz. Banka Hareketleri.
  • Sorgularda sayfalama: altı sorgu isteği page ve perPage (en çok 250) alır; fabrika metotlarıyla kurulan isteğe withPage($page, $perPage) eklenir. Liste yanıtları pagination (Pagination, hasMorePages()) taşır. Sayfalama. Gateway'de davranış değişikliği: sayfa istemeyen sorgu artık bütün kayıtları değil ilk 250'yi döner; daha fazlası varsa pagination toplamı gösterir, kalanını sayfa sayfa isteyin. SDK tarafında var olan kod değişmeden çalışır.

Değişenler:

  • Açıklama düzeltmeleri: dönüş adresleri (canlıda herkese açık https, sandbox'ta http/localhost), Item::$image http ya da https, NotFoundException yalnızca token'lı güncelleme/silme/iade/iptalde, en çok 100 kalem, gönderim adresinde firma alanları 422. Kod değişmedi.

Kırıcı değişiklik:

  • RefundStatus kaldırıldı; gateway iade durumu döndürmediği için hiçbir yanıtta kullanılmıyordu. Bu enum'u kullanan kod derlenmez; kullanımı silin.

1.0.5'teki değişiklikler​

Eklenenler:

  • Varsayılan Ödeyen: fatura adresi isteğe bağlı. PaymentCustomer'da billingAddress artık ?Address, varsayılanı null; verilmezse gövdeye yazılmaz. Ödemede new PaymentCustomer() customer'ı gövdeden tamamen çıkarır. Varsayılan Ödeyen açıksa RegularPayment, SecurePayment ve CreateSavedCard eksik ya da hiç verilmemiş fatura adresiyle gider; eksikler varsayılan ödeyenden tamamlanır. Ayar kapalıyken sekiz kişi alanı yine zorunludur ve eksikler ValidationException (422) alır. CreateSavedCard'da reference zorunlu kalır.
  • 403 anlatımı: ForbiddenException açıklaması ve README'deki hata tablosu iki nedeni anlatır: çalışma alanının ödenmemiş bakiyesi ya da ucun modülünün kapalı olması. Card::$shouldSave açıklaması Kayıtlı Kartlar modülünü anar. Kod değişmedi; bkz. 403.

Kırıcı değişiklik yoktur; 1.0.4 kodu değişmeden çalışır.

1.0.4'teki değişiklikler​

Eklenenler:

  • Sandbox'la başlayan kurulum: README ve Options açıklaması entegrasyonu https://sandbox.odemehub.com üzerinde kurar; canlıya çıkarken baseUrl https://app.odemehub.com olur. Bkz. Ortamlar ve Adresler.
  • Request\PaymentCustomer: ödemenin ve kart saklamanın müşterisi. Yalnızca billingAddress (zorunlu) ve reference taşır.
  • Webhook anlatımı: README menüyü (Ödeme Ayarları → Webhook), bir adrese birden çok olay bağlanmasını ve olaydan 30 saniye sonraki ilk gönderimi anlatır. Bkz. Webhook.

Kırıcı değişiklik:

  • RegularPayment, SecurePayment ve CreateSavedCard Customer değil PaymentCustomer alır. Gateway ödemede ve kart saklamada gönderim adresini 422 ile reddeder; shippingAddress taşıyabilen Customer bu isteklerden çıktı. new Customer(reference: …, billingAddress: …) yazan ödeme kodu new PaymentCustomer(billingAddress: …, reference: …) olur. CreateOrder ve CreateSubscription Customer almaya devam eder.

1.0.3'teki değişiklikler​

Eklenenler:

  • Müşteri kilidi ve müşteriye e-posta: CreateOrder, UpdateOrder, CreateSubscription ve UpdateSubscription locksCustomer ve emailsCustomer alır. Order ve Subscription yanıtları requiresShipping, locksCustomer ve emailsCustomer taşır. Bkz. create-order ve E-postalar.

Kırıcı değişiklikler:

  • Ödeme linkinde emailsPayer → emailsCustomer. CreatePaymentLink, UpdatePaymentLink ve PaymentLink yanıtında alanın adı değişti; gateway eski emails_payer adını kabul etmez.
  • UpdateOrder ve UpdateSubscription yapıcısında yeni alanlar clear'dan önce gelir. clear'ı konumsal argümanla geçen kod isimli argümana geçmelidir.

1.0.2'deki değişiklikler​

Eklenenler:

  • Link ödemeleri: retrieveLinkPayments() ve RetrieveLinkPayments (byToken(), byReference() ile LINKPAY{n}, between(), latest()). Yanıt LinkPaymentList; her LinkPayment paymentLink (token, reference), kalemler, tutarlar, discount, customer, transaction ve isPaid() taşır. Yeni enum: Enum\LinkPaymentStatus (Open, Paid). Bkz. retrieve-link-payments.
  • linkPaymentToken: PaymentTransaction, Transaction ve Webhook linkte alınan ödemede link ödemesinin token'ını verir.
  • Ödeme linki alanları: CreatePaymentLink ve UpdatePaymentLink amountType, itemName, predefinedAmounts, taxRate, taxMode, currencyType, currencies ve emailsPayer (1.0.3'te emailsCustomer oldu) alır; PaymentLink yanıtı aynı alanları taşır. Yeni enum'lar: Enum\AmountType, Enum\CurrencyType, Enum\TaxMode. UpdatePaymentLink clear listesi item_name, predefined_amounts, tax_rate ve currencies alanlarını da boşaltır.
  • discount: Order, Subscription ve LinkPayment ödeme sayfasında girilen kuponu Discount (code, amount) olarak taşır; kupon yoksa null. Webhook gövdesinde yoktur.

Küçük kırıcı değişiklikler:

  • create* her çağrıda yeni kayıt açar. createOrder(), createSubscription() ve createPaymentLink() aynı reference ile çağrılsa da yeni kayıt ve yeni token döner; önceki kayıt güncellenmez, 422 dönmez. Yanıttaki token'ı saklayın, değişiklik için update*() kullanın. Bkz. Aynı referansla tekrarlanan create-* istekleri.
  • CreatePaymentLink yapıcısında currency ilk parametredir, items isteğe bağlıdır (yalnızca Fixed tipte gerekir). İsimli argümanla yazılmış kod etkilenmez; konumsal argümanla items, currency sırasında çağıran kod isimli argümana geçmelidir.
  • UpdatePaymentLink yapıcısında yeni alanlar clear'dan önce gelir. clear'ı konumsal argümanla geçen kod isimli argümana geçmelidir.
  • PaymentLink::$subtotal, $taxAmount ve $amount artık ?string: tutarı ödeyenin belirlediği linkte null gelir (eskiden boş dize).
  • Link güncellemesi sonuçlanmamış ödemesi olan linkte reddedilmez; bu engel yalnızca updateOrder() ve updateSubscription() için geçerlidir.

1.0.1'deki kırıcı değişiklikler​

1.0.1, SDK'yı geçidin bugünkü API'sine taşır ve 1.0.0 koduyla uyumlu değildir. 1.0.0'dan geçerken dikkat edilecekler:

  • İmza: İstekler X-Timestamp başlığıyla ve zaman damgası, metot, yol ve gövde üzerinden imzalanır; yanıtlar da aynı yöntemle doğrulanır. 1.0.0 bugünkü gateway'le konuşamaz.
  • Metotlar uç adını taşır: orderPayment() → createOrder(), subscriptionPayment() → createSubscription(), saveCard() → createSavedCard(), savedCards() → retrieveSavedCards(), defaultSavedCard() → updateSavedCard(), cancelSubscription() → updateSubscription(status: SubscriptionStatus::Cancelled), retrieveTransactions() → retrievePayments(). saveProduct() kalktı; kalemler isteğin içinde adı ve fiyatıyla gönderilir.
  • Yeni metotlar: ödeme linki uçları, bütün güncelleme uçları ve her kaynakta tek retrieve*() sorgusu.
  • Token: Tek kaydı adlandıran istek alanı her yerde token'dır (RefundPayment(token: ...)).
  • Müşteri: Customer artık reference, billingAddress ve shippingAddress (Address) taşır; firma bilgisi fatura adresindeki companyTitle, taxNumber, taxOffice alanlarıdır.
  • Yanıtlar iç içe: Ödeme bilgisi $payment->transaction altında (status, paymentStatus, amount … dahil), iade $refund->refund altında. Sabit kümeli alanlar enum'dur.
  • Kayıtlı kartlar müşteri referansıyla bulunur; RetrieveSavedCards e-posta almaz. deleteSavedCard() delete-saved-card/{token} adresine gider.
  • Hatalar: güncellenen, silinen, iade ya da iptal edilen kaydın token'ı bulunamazsa NotFoundException (404) atılır; eskiden bu durum 422 dönüyordu. Sorgular bulunamayan kayıtta boş liste döner. Yeni istisnalar: ForbiddenException (403), NotFoundException (404), RateLimitException (429, retryAfter).
  • Kanal kalktı. Options artık channelToken almaz; isteklerde channelToken yoktur. Referans alanları channelReference yerine reference adını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlarda channelToken yoktur. Geri dönüşte tarayıcı channel_reference değil reference POST eder.
  • Sorgular tek uçta. Her kaynakta tek sorgu metodu vardır: retrievePayments(), retrieveOrders(), retrieveSubscriptions(), retrievePaymentLinks(), retrieveSavedCards(). İstek byToken(), byReference(), between() ya da latest() ile kurulur; yanıt her zaman listedir, bulunamayan kayıt 404 değil boş listedir.
  • Gönderim: sipariş ve abonelik requiresShipping ile ödeme sayfasında gönderim adresi ister; gönderim yöntemleri panelde tanımlanır, istekte gönderilmez. Yanıtta yalnızca ödeyenin seçtiği yöntem (shippingMethod: reference, title, amount, taxRate) gelir.
  • Kalemler: taxRate isteğe bağlı (boşsa vergisiz); yeni saveAsProduct.
  • Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur. NamedCustomer reference ve billingAddress alanları boş olabilir.
  • Ödeme linki: retrievePaymentLinks() her linkte son 50 denemeyi ve transactionsCount'u PaymentLink üzerinde verir; PaymentLinkDetails yalnızca linki taşır.
  • Kayıtlı kart: listede her kart kendi customer'ını taşır; SavedCardList::$customer kalktı. Ödeme yanıtındaki Transaction::$savedCard, kartın saklanması istendiyse saklanan kartı verir.

Webhook'lar​

Tek okuyucu vardır: webhook($method, $path, $body, $timestamp, $signature) imzayı (X-Timestamp + X-Signature) doğrular ve Response\Webhook döner. Nesne yalnızca token taşır: orderToken, paymentLinkToken, linkPaymentToken, subscriptionToken, transactionToken. Kararı bu token'larla çağırdığınız retrieve yanıtına göre verin. Yalnızca imzayı doğrulamak için verifyWebhook() kullanılır.

Olaylar, adres tanımlama ve her dildeki örnek işleyici: Webhook.