iyzipay-go

iyzipay-go is the comprehensive Go client library for the İyzico Payment Gateway. Built for performance, security, and developer experience, it provides 100% parity with the official İyzico Node.js SDK while leveraging Go's powerful type system and concurrency primitives.

🚀 Key Features

• 100% API Parity: Every endpoint available in the İyzico ecosystem is ready to use.
• Subscription V2 Support: Full lifecycle management for products, pricing plans, and subscriptions.
• Type-Safe Models: Deeply nested request/response structures with precise JSON mapping.
• Dual Auth Engine: Built-in support for both legacy IYZWS (v1) and modern IYZWSv2 authentication.
• Flexible Unmarshal: Robust response handling that gracefully manages İyzico's dynamic API response types.
• Production Ready: Correctly handles PKI string generation, signature verification, and path parameters.
• Zero Dependencies: Pure Go implementation using only the standard library.

📦 Installation

go get github.com/parevo-lab/iyzipay-go

🏁 Initialization

import "github.com/parevo-lab/iyzipay-go"

// Explicit configuration
client := iyzipay.NewClient(&iyzipay.Config{
    APIKey:    "your-api-key",
    SecretKey: "your-secret-key",
    BaseURL:   iyzipay.SandboxURL, // or iyzipay.ProductionURL
})

// Or via Environment Variables (IYZIPAY_API_KEY, IYZIPAY_SECRET_KEY, IYZIPAY_BASE_URL)
client := iyzipay.NewClientFromEnv()

💳 Core Usage Examples

1. Simple Payment

request := &iyzipay.PaymentRequest{
    Locale:         iyzipay.LocaleTR,
    Price:          "1.0",
    PaidPrice:      "1.1",
    Currency:       iyzipay.CurrencyTRY,
    Installment:    1,
    PaymentCard:    &iyzipay.PaymentCard{...},
    Buyer:          &iyzipay.Buyer{...},
    ShippingAddress: &iyzipay.Address{...},
    BillingAddress:  &iyzipay.Address{...},
    BasketItems:     []iyzipay.BasketItem{{...}},
}

response, err := client.Payment.Create(ctx, request)

2. Subscription V2 (Full Lifecycle)

// Create a Pricing Plan
planRequest := &iyzipay.SubscriptionPricingPlanRequest{
    Name:            "Premium Plan",
    Price:           "50.0",
    CurrencyCode:    iyzipay.CurrencyTRY,
    PaymentInterval: iyzipay.SubscriptionPricingPlanIntervalMonthly,
    PaymentIntervalCount: 1,
}
plan, err := client.Subscription.CreatePricingPlan(ctx, planRequest)

// Upgrade an existing Subscription
upgradeRequest := &iyzipay.UpgradeSubscriptionRequest{
    SubscriptionReferenceCode: "sub-123",
    NewPricingPlanReferenceCode: "plan-456",
    UpgradePeriod: iyzipay.SubscriptionUpgradePeriodNow,
}
res, err := client.Subscription.Upgrade(ctx, upgradeRequest)

3. Checkout Form (Hosted UI)

request := &iyzipay.CheckoutFormInitializeRequest{
    CallbackURL: "https://your-site.com/callback",
    Price:       "100.0",
    // ... other details
}

response, err := client.CheckoutForm.Initialize(ctx, request)
if response.Status == iyzipay.StatusSuccess {
    // Redirect user to response.PaymentPageURL
}

🛠 Advanced Features

Path Parameter Management

The SDK automatically handles RESTful path parameters for Subscriptions and Onboarding. You don't need to manually construct URLs:

// The SDK replaces {customerReferenceCode} in the background
client.Subscription.RetrieveCustomer(ctx, &iyzipay.SubscriptionCustomerPathRequest{
    CustomerReferenceCode: "cust-999",
})

Response Verification

Verify the integrity of responses using the built-in HMAC verification:

isValid := iyzipay.VerifyResponseSignature(response, client.GetConfig().SecretKey)

📊 API Service Coverage

Service	Category	Description
Payment	Core	Standard, Pre-Auth, Post-Auth and Basic payments
Threeds	Security	Full 3D Secure initialization and authentication
Subscription	Recurring	V2 Subscription, Plan, Product, and Customer management
CheckoutForm	UI	Hosted payment page initialization and retrieval
Card	Storage	Card storage, deletion, and retrieval
Reporting	Finance	Payout and settlement transaction reporting
SubMerchant	Marketplace	Marketplace onboarding and management
Refund/Cancel	Operations	Full and partial refunds, payment cancellations

🧪 Testing

The SDK is backed by a comprehensive test suite covering PKI generation, hashing, and model validation.

go test ./...

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

Made with ❤️ by Parevo Lab