Payment Service — Abonelik ve Ödeme API'si

Base Routes: /api/subscriptions, /api/payments, /api/invoices, /api/payment-methods, /api/admin/billing
Service: Taz.SaaS.Payment.API

Tüm endpoint'ler Bearer Token (Auth) gerektirir. Domain-driven design ile Subscription, Payment, Invoice entity'leri yönetilir.

Subscriptions Controller — `/api/subscriptions`

1. Get Subscription Plans

HTTP Method: GET
Route: /api/subscriptions/plans
Auth: Required

Sistemdeki tüm abonelik paketlerini listeler (cached: Redis). CachedSubscriptionPlansQueryHandler ile cache-first.

Response (200 OK) — `SubscriptionPlanDto[]`

[
  {
    "id": "guid",
    "name": "string",
    "code": "string (e.g., STARTER)",
    "type": 1,
    "price": 99.00,
    "currency": "USD",
    "billingPeriod": 1,
    "features": {
      "maxAgents": 5,
      "maxKnowledgeBases": 3,
      "maxWidgetIntegrations": 1,
      "maxTokensPerMonth": 100000,
      "hasPrioritySupport": false,
      "hasDedicatedSupport": false,
      "customDomainEnabled": false,
      "aiAgentsEnabled": true,
      "riskAssessmentEnabled": false
    },
    "isTrialEligible": true,
    "trialDays": 30,
    "isActive": true,
    "createdAt": "datetime"
  }
]

2. Get Current Subscription

HTTP Method: GET
Route: /api/subscriptions/current
Auth: Required (Tenant owner or member)

Response (200 OK) — `CurrentSubscriptionDto`

{
  "subscriptionId": "guid",
  "planId": "guid",
  "planName": "string",
  "status": 1,
  "startDate": "datetime",
  "renewalDate": "datetime | null",
  "trialExpiresAt": "datetime | null",
  "isTrialActive": true,
  "billingPeriod": 1,
  "price": 99.00,
  "currency": "USD"
}

3. Create Subscription

HTTP Method: POST
Route: /api/subscriptions
Auth: Required (Tenant owner)

CreateSubscriptionCommand → StripePaymentService.CreateCheckoutSessionAsync() veya IyzicoPaymentService. Webhook ile tamamlanır.

Request Body

{
  "planId": "guid (required)",
  "billingPeriod": "int (required, 1=monthly, 2=yearly)",
  "trialDays": "int | null (optional)"
}

Response (201 Created) — `SubscriptionCreationResult`

{
  "subscriptionId": "guid",
  "checkoutUrl": "string (Stripe/Iyzico checkout URL)",
  "status": "PENDING"
}

Payments Controller — `/api/payments`

4. Process Payment

HTTP Method: POST
Route: /api/payments/process
Auth: Required

İşlem başlatır (ProcessPaymentCommandHandler → IPaymentProviderService.ProcessAsync()). Stripe veya Iyzico kullanılır.

Request Body

{
  "subscriptionId": "guid (required)",
  "amount": "decimal (required)",
  "currency": "string (required, ISO 4217)",
  "paymentMethodId": "guid | null (optional)",
  "description": "string | null"
}

Response (200 OK) — `PaymentProcessingResult`

{
  "paymentId": "guid",
  "status": "PENDING",
  "checkoutUrl": "string | null",
  "expiresAt": "datetime | null"
}

5. Get Payment History

HTTP Method: GET
Route: /api/payments/history?startDate={date}&endDate={date}&page={int}&pageSize={int}
Auth: Required

Query Parameters

Name	Type	Required	Default
startDate	date	No	null
endDate	date	No	null
statusFilter	int \| null	No	null
page	int	No	1
pageSize	int	No	20

Response (200 OK) — `PaginatedList<PaymentDto>`

{
  "items": [{
    "id": "guid",
    "tenantId": "guid",
    "subscriptionId": "guid | null",
    "invoiceId": "guid | null",
    "amount": 99.00,
    "currency": "USD",
    "status": 1,
    "provider": 1,
    "providerReferenceId": "string | null",
    "paidAt": "datetime | null",
    "createdAt": "datetime"
  }],
  "totalCount": 50,
  "totalPages": 3,
  "page": 1,
  "pageSize": 20
}

6. Refund Payment

HTTP Method: POST
Route: /api/payments/{paymentId}/refund
Auth: Required

Request Body

{
  "reason": "string (required)"
}

Payment Methods Controller — `/api/payment-methods`

7. List Payment Methods

HTTP Method: GET
Route: /api/payment-methods
Auth: Required

Response (200 OK) — `PaymentMethodDto[]`

[
  {
    "id": "guid",
    "provider": 1,
    "isDefault": true,
    "lastFourDigits": "string | null",
    "cardType": "string | null",
    "expiryMonth": "int | null",
    "expiryYear": "int | null",
    "createdAt": "datetime"
  }
]

8. Add Payment Method

HTTP Method: POST
Route: /api/payment-methods
Auth: Required

Request Body

{
  "provider": "int (required, Stripe=1, Iyzico=2)",
  "token": "string (required, payment provider token)"
}

Response (201 Created) — `PaymentMethodDto`

9. Set Default Payment Method

PUT /api/payment-methods/{paymentMethodId}/set-default
Auth: Required

10. Remove Payment Method

DELETE /api/payment-methods/{paymentMethodId}
Auth: Required

Invoices Controller — `/api/invoices`

11. List Invoices

HTTP Method: GET
Route: /api/invoices?page={int}&pageSize={int}
Auth: Required

Response (200 OK) — `PaginatedList<InvoiceDto>`

{
  "items": [{
    "id": "guid",
    "tenantId": "guid",
    "subscriptionPlanName": "string | null",
    "amount": 99.00,
    "currency": "USD",
    "status": 1,
    "dueDate": "datetime | null",
    "paidAt": "datetime | null",
    "pdfUrl": "string | null"
  }],
  "totalCount": 30,
  "totalPages": 2,
  "page": 1,
  "pageSize": 20
}

12. Get Invoice by Id

GET /api/invoices/{invoiceId:guid}
Auth: Required

Response (200 OK) — `InvoiceDetailDto`

{
  "id": "guid",
  "tenantId": "guid",
  "tenantName": "string",
  "subscriptionPlanName": "string | null",
  "amount": 99.00,
  "currency": "USD",
  "status": 1,
  "dueDate": "datetime | null",
  "paidAt": "datetime | null",
  "pdfUrl": "string | null",
  "items": [{
    "description": "string",
    "amount": 99.00,
    "quantity": 1
  }]
}

13. Get Invoice PDF

GET /api/invoices/{invoiceId:guid}/pdf
Auth: Required

Response: application/pdf binary stream.

Admin Billing Controller — `/api/admin/billing`

14. List All Subscriptions (Admin)

GET /api/admin/billing/subscriptions?statusFilter={int}&page={int}&pageSize={int}
Auth: Required (SystemAdmin)

Response — `PaginatedList<SubscriptionDto>`

{
  "items": [{
    "id": "guid",
    "tenantId": "guid",
    "tenantName": "string",
    "planName": "string",
    "status": 1,
    "price": 99.00,
    "renewalDate": "datetime | null"
  }],
  "totalCount": 42,
  "totalPages": 3,
  "page": 1,
  "pageSize": 20
}

15. Extend Trial

PUT /api/admin/billing/subscriptions/{tenantId}/extend-trial
Auth: Required (SystemAdmin)

Request Body

{
  "additionalDays": "int (required)"
}

Webhooks Controller — `/api/webhooks`

16. Stripe Webhook Handler

POST /api/webhooks/stripe
Auth: Webhook signature validation

Stripe event'leri için endpoint. StripeWebhookHandler ile checkout.completed, invoice.payment_succeeded vb. işlenir.

17. Iyzico Webhook Handler

POST /api/webhooks/iyzico
Auth: Webhook signature validation

Iyzico ödeme durumu callback'leri için endpoint.

Enums (Domain Types)

BillingPeriod

Value	Name
1	Monthly
2	Yearly

PaymentStatus

Value	Name
0	Pending
1	Paid
2	Failed
3	Refunded

InvoiceStatus

Value	Name
0	Draft
1	Issued
2	Paid
3	Overdue
4	Cancelled

SubscriptionStatus

Value	Name
0	Inactive
1	Active
2	Suspended
3	Trialing
4	Cancelled

Subscriptions Controller — /api/subscriptions​

1. Get Subscription Plans​

Response (200 OK) — SubscriptionPlanDto[]​

2. Get Current Subscription​

Response (200 OK) — CurrentSubscriptionDto​

3. Create Subscription​

Request Body​

Response (201 Created) — SubscriptionCreationResult​

Payments Controller — /api/payments​

4. Process Payment​

Request Body​

Response (200 OK) — PaymentProcessingResult​

5. Get Payment History​

Query Parameters​

Response (200 OK) — PaginatedList<PaymentDto>​

6. Refund Payment​

Request Body​

Payment Methods Controller — /api/payment-methods​

7. List Payment Methods​

Response (200 OK) — PaymentMethodDto[]​

8. Add Payment Method​

Request Body​

Response (201 Created) — PaymentMethodDto​

9. Set Default Payment Method​

10. Remove Payment Method​

Invoices Controller — /api/invoices​

11. List Invoices​

Response (200 OK) — PaginatedList<InvoiceDto>​

12. Get Invoice by Id​

Response (200 OK) — InvoiceDetailDto​

13. Get Invoice PDF​

Admin Billing Controller — /api/admin/billing​

14. List All Subscriptions (Admin)​

Response — PaginatedList<SubscriptionDto>​

15. Extend Trial​

Request Body​

Webhooks Controller — /api/webhooks​

16. Stripe Webhook Handler​

17. Iyzico Webhook Handler​

Enums (Domain Types)​

BillingPeriod​

PaymentStatus​

InvoiceStatus​

SubscriptionStatus​

Subscriptions Controller — `/api/subscriptions`

1. Get Subscription Plans

Response (200 OK) — `SubscriptionPlanDto[]`

2. Get Current Subscription

Response (200 OK) — `CurrentSubscriptionDto`

3. Create Subscription

Request Body

Response (201 Created) — `SubscriptionCreationResult`

Payments Controller — `/api/payments`

4. Process Payment

Request Body

Response (200 OK) — `PaymentProcessingResult`

5. Get Payment History

Query Parameters

Response (200 OK) — `PaginatedList<PaymentDto>`

6. Refund Payment

Request Body

Payment Methods Controller — `/api/payment-methods`

7. List Payment Methods

Response (200 OK) — `PaymentMethodDto[]`

8. Add Payment Method

Request Body

Response (201 Created) — `PaymentMethodDto`

9. Set Default Payment Method

10. Remove Payment Method

Invoices Controller — `/api/invoices`

11. List Invoices

Response (200 OK) — `PaginatedList<InvoiceDto>`

12. Get Invoice by Id

Response (200 OK) — `InvoiceDetailDto`

13. Get Invoice PDF

Admin Billing Controller — `/api/admin/billing`

14. List All Subscriptions (Admin)

Response — `PaginatedList<SubscriptionDto>`

15. Extend Trial

Request Body

Webhooks Controller — `/api/webhooks`

16. Stripe Webhook Handler

17. Iyzico Webhook Handler

Enums (Domain Types)

BillingPeriod

PaymentStatus

InvoiceStatus

SubscriptionStatus