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ümelerGurmehub\Odemehub\Enum, istisnalarGurmehub\Odemehub\Exceptionad 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 alannullolur. - Tek bir kaydı adlandıran istek alanı her zaman
token'dır. Bir alanı boşaltmak içinUpdate*isteklerindeclear: ['description']verilir.
Müşteri ve kart
use Gurmehub\Odemehub\Request\{Address, Card, PaymentCustomer};
$billingAddress = new Address(
firstname: 'Ahmet', lastname: 'Yılmaz',
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;teamyok) iş ortağının anahtarıyla/api/partner/uçlarını çağırır:createTeam(),retrieveTeams()(sayfalı),updateTeamModules(),deleteTeam(). YanıtlarPartnerTeamDetails,PartnerTeamList(Pagination) veDeletedTeam; çalışma alanıPartnerTeam(slug,name,timezone,isTest,modules,gatewayUrl,apiKey,apiSecret,createdAt).teamClient($team)açılan çalışma alanınınClient'ını kurar. Bkz. İş Ortakları. - Yalnızca iş ortağı çalışma alanlarına açık uçlar (
Clientüzerinde; başka çalışma alanındaForbiddenException):retrieveProviders(),createPaymentProvider(),retrievePaymentProviders(),updatePaymentProvider(),deletePaymentProvider(),createWebhookEndpoint(),retrieveWebhookEndpoints(),updateWebhookEndpoint(),deleteWebhookEndpoint(),updateTeam(),retrieveCheckoutDesign(),updateCheckoutDesign()(clear: ['logo', 'terms_url']kaldırır) vecreateLogo()(CreateLogo::fromBytes()). YanıtlarProviderList(Provider,ProviderField),PaymentProviderDetails,PaymentProviderList(PaymentProvider),DeletedPaymentProvider,WebhookEndpointDetails,WebhookEndpointList(WebhookEndpoint),DeletedWebhookEndpoint,TeamDetails(Team),CheckoutDesignDetails(CheckoutDesign) veLogoDetails. 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; istekteRequest\MaxInstallments, yanıttaResponse\MaxInstallments) veCreateOrder,UpdateOrder,CreateSubscription,UpdateSubscription,CreatePaymentLink,UpdatePaymentLinkisteklerindemaxInstallmentsparametresi;Order,SubscriptionvePaymentLinkyanıtlarındamaxInstallments(yoksanull). 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ıtlarBankList,BankAccountDetails,BankAccountList,DeletedBankAccount,BankTransactionList(Pagination,BankTransaction). Bankanın reddettiği kimlik bilgisi istisna değildir:result->successfulfalse,bankAccountnull. Bkz. Banka Hareketleri. - Sorgularda sayfalama: altı sorgu isteği
pageveperPage(en çok 250) alır; fabrika metotlarıyla kurulan isteğewithPage($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ı varsapaginationtoplamı 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::$imagehttp ya da https,NotFoundExceptionyalnı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:
RefundStatuskaldı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'dabillingAddressartık?Address, varsayılanınull; verilmezse gövdeye yazılmaz. Ödemedenew PaymentCustomer()customer'ı gövdeden tamamen çıkarır. Varsayılan Ödeyen açıksaRegularPayment,SecurePaymentveCreateSavedCardeksik ya da hiç verilmemiş fatura adresiyle gider; eksikler varsayılan ödeyenden tamamlanır. Ayar kapalıyken sekiz kişi alanı yine zorunludur ve eksiklerValidationException(422) alır.CreateSavedCard'dareferencezorunlu kalır. 403anlatımı:ForbiddenExceptionaçı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::$shouldSaveaçı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
Optionsaçıklaması entegrasyonuhttps://sandbox.odemehub.comüzerinde kurar; canlıya çıkarkenbaseUrlhttps://app.odemehub.comolur. Bkz. Ortamlar ve Adresler. Request\PaymentCustomer: ödemenin ve kart saklamanın müşterisi. YalnızcabillingAddress(zorunlu) vereferencetaşı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,SecurePaymentveCreateSavedCardCustomerdeğilPaymentCustomeralır. Gateway ödemede ve kart saklamada gönderim adresini422ile reddeder;shippingAddresstaşıyabilenCustomerbu isteklerden çıktı.new Customer(reference: …, billingAddress: …)yazan ödeme kodunew PaymentCustomer(billingAddress: …, reference: …)olur.CreateOrderveCreateSubscriptionCustomeralmaya devam eder.
1.0.3'teki değişiklikler
Eklenenler:
- Müşteri kilidi ve müşteriye e-posta:
CreateOrder,UpdateOrder,CreateSubscriptionveUpdateSubscriptionlocksCustomerveemailsCustomeralır.OrderveSubscriptionyanıtlarırequiresShipping,locksCustomerveemailsCustomertaşır. Bkz.create-orderve E-postalar.
Kırıcı değişiklikler:
- Ödeme linkinde
emailsPayer→emailsCustomer.CreatePaymentLink,UpdatePaymentLinkvePaymentLinkyanıtında alanın adı değişti; gateway eskiemails_payeradını kabul etmez. UpdateOrderveUpdateSubscriptionyapıcısında yeni alanlarclear'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()veRetrieveLinkPayments(byToken(),byReference()ileLINKPAY{n},between(),latest()). YanıtLinkPaymentList; herLinkPaymentpaymentLink(token,reference), kalemler, tutarlar,discount,customer,transactionveisPaid()taşır. Yeni enum:Enum\LinkPaymentStatus(Open,Paid). Bkz.retrieve-link-payments. linkPaymentToken:PaymentTransaction,TransactionveWebhooklinkte alınan ödemede link ödemesinin token'ını verir.- Ödeme linki alanları:
CreatePaymentLinkveUpdatePaymentLinkamountType,itemName,predefinedAmounts,taxRate,taxMode,currencyType,currenciesveemailsPayer(1.0.3'teemailsCustomeroldu) alır;PaymentLinkyanıtı aynı alanları taşır. Yeni enum'lar:Enum\AmountType,Enum\CurrencyType,Enum\TaxMode.UpdatePaymentLinkclearlistesiitem_name,predefined_amounts,tax_ratevecurrenciesalanlarını da boşaltır. discount:Order,SubscriptionveLinkPaymentödeme sayfasında girilen kuponuDiscount(code,amount) olarak taşır; kupon yoksanull. Webhook gövdesinde yoktur.
Küçük kırıcı değişiklikler:
create*her çağrıda yeni kayıt açar.createOrder(),createSubscription()vecreatePaymentLink()aynıreferenceile çağrılsa da yeni kayıt ve yeni token döner; önceki kayıt güncellenmez,422dönmez. Yanıttaki token'ı saklayın, değişiklik içinupdate*()kullanın. Bkz. Aynı referansla tekrarlanancreate-*istekleri.CreatePaymentLinkyapıcısındacurrencyilk parametredir,itemsisteğe bağlıdır (yalnızcaFixedtipte gerekir). İsimli argümanla yazılmış kod etkilenmez; konumsal argümanlaitems, currencysırasında çağıran kod isimli argümana geçmelidir.UpdatePaymentLinkyapıcısında yeni alanlarclear'dan önce gelir.clear'ı konumsal argümanla geçen kod isimli argümana geçmelidir.PaymentLink::$subtotal,$taxAmountve$amountartık?string: tutarı ödeyenin belirlediği linktenullgelir (eskiden boş dize).- Link güncellemesi sonuçlanmamış ödemesi olan linkte reddedilmez; bu engel yalnızca
updateOrder()veupdateSubscription()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-Timestampbaş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:
Customerartıkreference,billingAddressveshippingAddress(Address) taşır; firma bilgisi fatura adresindekicompanyTitle,taxNumber,taxOfficealanlarıdır. - Yanıtlar iç içe: Ödeme bilgisi
$payment->transactionaltında (status,paymentStatus,amount… dahil), iade$refund->refundaltında. Sabit kümeli alanlar enum'dur. - Kayıtlı kartlar müşteri referansıyla bulunur;
RetrieveSavedCardse-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ı.
OptionsartıkchannelTokenalmaz; isteklerdechannelTokenyoktur. Referans alanlarıchannelReferenceyerinereferenceadını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlardachannelTokenyoktur. Geri dönüşte tarayıcıchannel_referencedeğilreferencePOST eder. - Sorgular tek uçta. Her kaynakta tek sorgu metodu vardır:
retrievePayments(),retrieveOrders(),retrieveSubscriptions(),retrievePaymentLinks(),retrieveSavedCards(). İstekbyToken(),byReference(),between()ya dalatest()ile kurulur; yanıt her zaman listedir, bulunamayan kayıt 404 değil boş listedir. - Gönderim: sipariş ve abonelik
requiresShippingile ö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:
taxRateisteğe bağlı (boşsa vergisiz); yenisaveAsProduct. - Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur.
NamedCustomerreferencevebillingAddressalanları boş olabilir. - Ödeme linki:
retrievePaymentLinks()her linkte son 50 denemeyi vetransactionsCount'uPaymentLinküzerinde verir;PaymentLinkDetailsyalnızca linki taşır. - Kayıtlı kart: listede her kart kendi
customer'ını taşır;SavedCardList::$customerkalktı. Ödeme yanıtındakiTransaction::$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.