94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# 📡 Pay2Gateway API v1 Kullanım Rehberi
|
||
|
||
Pay2Gateway API, firmaların (merchants) kendi sistemlerini bizim ödeme geçidimize entegre etmelerini sağlar. Tüm istekler JSON formatında yapılmalı ve geçerli bir API anahtarı içermelidir.
|
||
|
||
## 🔑 Kimlik Doğrulama (Authentication)
|
||
Tüm API isteklerinde `x-api-key` header'ı zorunludur. API anahtarınızı Merchant Panel -> Ayarlar kısmından alabilirsiniz.
|
||
|
||
**Örnek Header:**
|
||
```http
|
||
x-api-key: gwa_live_xxxxxxxxxxxx
|
||
Content-Type: application/json
|
||
```
|
||
|
||
---
|
||
|
||
## 🛒 1. Ödeme Oturumu Oluşturma (Checkout Session)
|
||
Bir müşteri ödeme yapmak istediğinde, sunucunuzdan bu endpoint'e istek atarak bir ödeme oturumu oluşturun.
|
||
|
||
- **Endpoint:** `POST /api/v1/checkout`
|
||
- **Açıklama:** Yeni bir işlem başlatır ve müşteriyi yönlendirebileceğiniz bir URL döndürür.
|
||
|
||
### İstek Gövdesi (Request Body)
|
||
| Parametre | Tip | Zorunlu mu? | Açıklama |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `amount` | Float | Evet | Tahsil edilecek tutar. |
|
||
| `currency` | String | Hayır | Para birimi (Varsayılan: `TRY`). |
|
||
| `order_id` | String | Evet | Kendi sisteminizdeki sipariş numarası. |
|
||
| `customer_name` | String | Hayır | Müşterinin adı. |
|
||
| `customer_phone` | String | Hayır | Müşterinin telefon numarası. |
|
||
| `callback_url` | String | Hayır | Ödeme sonrası sunucunuza bildirim atılacak URL. |
|
||
| `success_url` | String | Hayır | Başarılı ödeme sonrası kullanıcının döneceği URL. |
|
||
| `cancel_url` | String | Hayır | İptal edilen ödeme sonrası kullanıcının döneceği URL. |
|
||
|
||
**Örnek İstek:**
|
||
```json
|
||
{
|
||
"amount": 1250.50,
|
||
"currency": "TRY",
|
||
"order_id": "SİPARİŞ_102",
|
||
"customer_name": "Ahmet Yılmaz",
|
||
"callback_url": "https://siteniz.com/api/webhooks/pay2gateway",
|
||
"success_url": "https://siteniz.com/payment/success",
|
||
"cancel_url": "https://siteniz.com/payment/cancel"
|
||
}
|
||
```
|
||
|
||
### Yanıt (Response)
|
||
Başarılı bir istek sonucunda `checkout_url` döndürülür. Müşterinizi bu adrese yönlendirmeniz yeterlidir.
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "uuid-islem-id",
|
||
"checkout_url": "https://pay2gateway.com/checkout?session_id=uuid-islem-id",
|
||
"status": "pending",
|
||
"wallets": {
|
||
"EVM": "0x...",
|
||
"SOLANA": "...",
|
||
"TRON": "...",
|
||
"BITCOIN": "..."
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔔 2. Webhook Bildirimleri
|
||
Ödeme tamamlandığında veya blockchain üzerinde onaylandığında, `callback_url` adresine bir `POST` isteği gönderilir.
|
||
|
||
**Webhook Gövdesi:**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"amount": 1250.50,
|
||
"currency": "TRY",
|
||
"ref_id": "SİPARİŞ_102",
|
||
"tx_hash": "0xabc123...",
|
||
"network": "POLYGON",
|
||
"token": "USDT"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🛡️ Güvenlik Notları
|
||
- **API Key:** API anahtarınızı asla frontend kodlarınızda (JavaScript/React) paylaşmayın. Sadece sunucu tarafında kullanın.
|
||
- **İşlem Doğrulama:** Webhook geldiğinde tutarı ve sipariş ID'sini kendi veritabanınızla karşılaştırın.
|
||
- **Test Modu:** Test yapmak için admin panelinden `MOCK_PAYMENTS` ayarını aktif edebilirsiniz.
|
||
|
||
---
|
||
⭐ **Pay2Gateway Support** - Teknik destek için `support@ayris.dev` üzerinden bize ulaşabilirsiniz.
|