CP.VPOS .NET Library

repository·master·Indexed 41 days ago

https://github.com/cempehlivan/cp.vpos

A .NET library providing a unified abstraction layer for integrating Turkish Virtual POS (Sanal POS) providers, including major banks (Akbank, Garanti, İş Bankası) and payment institutions like Iyzico and Sipay. It supports 3D Secure payment flows and is compatible with .NET Framework, .NET Core, and .NET MAUI.

Tokens
4.7K
Snippets
5
Records
7
Agent score
2%

What's inside CP.VPOS

  1. Overview of CP.VPOS

    master

    CP.VPOS is a .NET library designed to simplify Virtual POS (Sanal POS) integrations in Turkey. It allows developers to interact with multiple banks and payment institutions using a single codebase, eliminating the need to write custom integration logic for every individual provider.

    Key features include:

    • Unified Codebase: One interface for multiple banks.
    • Simplified Workflows: Automated handling of transaction steps.
    • 3D Secure Support: Built-in support for 3D Secure payment flows.
    • Wide Coverage: Supports major banks (Akbank, Garanti, İş Bankası, etc.) and payment providers (Iyzico, Sipay, etc.).
    • Cross-Platform: Compatible with .NET Framework, .NET Core, and .NET MAUI.
  2. How 3D Secure sales work

    master

    To initiate a 3D Secure transaction, set payment3D.confirm = true and provide a payment3D.returnURL (the URL where the bank will post the response).

    When calling VPOSClient.Sale, check the statu field in the response:

    • If statu is RedirectURL: The message field contains the URL you must redirect the client to.
    • If statu is RedirectHTML: The message field contains HTML code that you should render/execute on the client's page to trigger the redirect.

    After the user completes the 3D verification at the bank, the bank will send a form POST request to your specified returnURL.

    // Example SaleRequest for 3D Secure
    SaleRequest saleRequest = new SaleRequest
    {
    	// ... other properties
    	payment3D = new Payment3D
    	{
    		confirm = true,
    		returnURL = "https://localhost/Payment/VirtualPOS3DResponse"
    	},
        // ...
    };
    
    var resp = VPOSClient.Sale(saleRequest, _qnbPayTest);
  3. Install CP.VPOS via NuGet

    master

    You can add the CP.VPOS library to your .NET project using the NuGet Package Manager or the dotnet CLI. This library provides a unified interface for integrating various Turkish Virtual POS (Sanal POS) providers.

    # Using Package Manager
    Install-Package CP.VPOS
    
    # Using Dotnet CLI
    dotnet add package CP.VPOS
  4. Complete a 3D Secure sale (Step 2)

    master

    Once the bank redirects the user back to your returnURL via a form POST (or GET), you must process the response to finalize the transaction.

    1. Capture the request body from the incoming request (convert the form/query parameters into a Dictionary<string, object>).
    2. Call VPOSClient.Sale3DResponse using a Sale3DResponseRequest containing that dictionary and your VirtualPOSAuth credentials.
    3. The method returns the final SaleResponse.
    public class PaymentController
    {
        public async Task<IActionResult> VirtualPOS3DResponse()
        {
            Dictionary<string, object>? pairs = null;
    
            // Capture parameters from GET or POST
            if (Request.Method == "GET")
                pairs = Request.Query.Keys.ToDictionary(k => k, v => (object)Request.Query[v]);
            else
                pairs = Request.Form.Keys.ToDictionary(k => k, v => (object)Request.Form[v]);   
    
            // Finalize the transaction
            SaleResponse response = VPOSClient.Sale3DResponse(new Sale3DResponseRequest
            {
                responseArray = pairs
            }, _qnbPayTest);
            
            // Handle 'response' as needed
        }
    }
  5. Configure API credentials with VirtualPOSAuth

    master

    To use a specific Virtual POS, you must instantiate the VirtualPOSAuth class with the appropriate credentials provided by your bank or payment institution.

    Common Fields

    FieldTypeDescription
    bankCodestringThe 4-digit bank code. It is recommended to use the CP.VPOS.Services.BankService enum (e.g., CP.VPOS.Services.BankService.Akbank) to avoid errors.
    merchantIDstringYour merchant/firm code.
    merchantUserstringYour API username.
    merchantPasswordstringYour API password.
    merchantStorekeystringRequired by some banks for 3D Secure operations.
    testPlatformbooleanSet to true to use the Virtual POS test environment.

    Note: The mapping of these fields (e.g., what constitutes a merchantID vs a merchantUser) varies significantly between banks. Always refer to the specific bank's requirements in the documentation table.

  6. Perform a direct sale without 3D Secure

    master

    To perform a direct transaction without 3D Secure verification, set payment3D.confirm = false in your SaleRequest. This will attempt to process the payment immediately and return the final result directly from the VPOSClient.Sale method.

    VirtualPOSAuth _qnbPayTest = new VirtualPOSAuth
    {
        bankCode = CP.VPOS.Services.BankService.QNBpay,
        merchantID = "20158",
        merchantUser = "07fb70f9d8de575f32baa6518e38c5d6",
        merchantPassword = "61d97b2cac247069495be4b16f8604db",
        merchantStorekey = "$2y$10$N9IJkgazXMUwCzpn7NJrZePy3v.dIFOQUyW4yGfT3eWry6m.KxanK",
        testPlatform = true
    };
    
    CustomerInfo customerInfo = new CustomerInfo
    {
    	taxNumber = "1111111111",
    	emailAddress = "test@test.com",
    	name = "cem",
    	surname = "pehlivan",
    	phoneNumber = "1111111111",
    	addressDesc = "adres",
    	cityName = "istanbul",
    	country = CP.VPOS.Enums.Country.TUR,
    	postCode = "34000",
    	taxOffice = "maltepe",
    	townName = "maltepe"
    };
    
    SaleRequest saleRequest = new SaleRequest
    {
    	invoiceInfo = customerInfo,
    	shippingInfo = customerInfo,
    	saleInfo = new SaleInfo
    	{
    		cardNameSurname = "test kart",
    		cardNumber = "4022780520669303",
    		cardExpiryDateMonth = 1,
    		cardExpiryDateYear = 2050,
    		cardCVV = "988",
    		amount = (decimal)10,
    		currency = CP.VPOS.Enums.Currency.TRY,
    		installment = 1,
    	},
    	payment3D = new Payment3D
    	{
    		confirm = false
    	},
    	customerIPAddress = "1.1.1.1",
    	orderNumber = Convert.ToInt32((DateTime.Now - new DateTime(1970, 1, 1)).TotalSeconds).ToString("X")
    };
    
    var resp = VPOSClient.Sale(saleRequest, _qnbPayTest);
  7. Reference: VirtualPOSAuth field mappings by provider

    master

    The following table maps the VirtualPOSAuth fields to the specific credentials required by different providers. Use this to ensure you are passing the correct values to the VirtualPOSAuth object.

    | Sanal POS | bankCode | merchantID | merchantUser | merchantPassword | merchantStorekey |
    | --------- | -------- | ---------- | ------------ | --------------- | ---------------- |
    | Akbank | CP.VPOS.Services.BankService.Akbank | İş Yeri No | Güvenli İşyeri Numarası (merchantSafeId) | Terminal Safe ID | Güvenlik Anahtarı (Secret Key) |
    | Akbank Nestpay | CP.VPOS.Services.BankService.AkbankNestpay | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Alternatif Bank | CP.VPOS.Services.BankService.AlternatifBank | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Anadolubank | CP.VPOS.Services.BankService.Anadolubank | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Denizbank | CP.VPOS.Services.BankService.Denizbank | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | QNB Finansbank | CP.VPOS.Services.BankService.QNBFinansbank | Üye İşyeri Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | Üye İşyeri Şifre |
    | Finansbank Nestpay | CP.VPOS.Services.BankService.FinansbankNestpay | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Garanti BBVA | CP.VPOS.Services.BankService.GarantiBBVA | Firma Kodu | Terminal No | `PROVAUT` kullanıcısı şifresi | 3D secure anahtarı |
    | Halkbank | CP.VPOS.Services.BankService.Halkbank | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | ING Bank | CP.VPOS.Services.BankService.INGBank | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | İş Bankası | CP.VPOS.Services.BankService.IsBankasi | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Şekerbank | CP.VPOS.Services.BankService.Sekerbank | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Türk Ekonomi Bankası | CP.VPOS.Services.BankService.TurkEkonomiBankasi | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Türkiye Finans | CP.VPOS.Services.BankService.TurkiyeFinans | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Vakıfbank | CP.VPOS.Services.BankService.Vakifbank | Üye İşyeri Numarası | POS No | Api Şifresi | |
    | Yapı Kredı Bankası | CP.VPOS.Services.BankService.YapiKrediBankasi | Firma Kodu | Terminal No | Pos Net ID | ENCKEY |
    | Ziraat Bankası | CP.VPOS.Services.BankService.ZiraatBankasi | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Cardplus | CP.VPOS.Services.BankService.Cardplus | Mağaza Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | 3D Storekey (Üye İş Yeri Anahtarı) |
    | Paratika | CP.VPOS.Services.BankService.Paratika | Firma Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | |
    | Payten - MSU | CP.VPOS.Services.BankService.Payten | Firma Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | |
    | Iyzico | CP.VPOS.Services.BankService.Iyzico | Üye İşyeri Numarası | API Anahtarı | Güvenlik Anahtarı | |
    | Sipay | CP.VPOS.Services.BankService.Sipay | Üye İşyeri ID | Uygulama Anahtarı | Uygulama Parolası | Üye İşyeri Anahtarı |
    | QNBpay | CP.VPOS.Services.BankService.QNBpay | Üye İşyeri ID | Uygulama Anahtarı | Uygulama Parolası | Üye İşyeri Anahtarı |
    | ParamPos | CP.VPOS.Services.BankService.ParamPos | Terminal No (Client Code) | Kullanıcı Adı | Şifre | Anahtar (Guid) |
    | PayBull | CP.VPOS.Services.BankService.PayBull | Üye İşyeri ID | Uygulama Anahtarı | Uygulama Parolası | Üye İşyeri Anahtarı |
    | Parolapara | CP.VPOS.Services.BankService.Parolapara | Üye İşyeri ID | Uygulama Anahtarı | Uygulama Parolası | Üye İşyeri Anahtarı |
    | IQmoney | CP.VPOS.Services.BankService.IQmoney | Üye İşyeri ID | Uygulama Anahtarı | Uygulama Parolası | Üye İşyeri Anahtarı |
    | Ahlpay | CP.VPOS.Services.BankService.Ahlpay | member Id | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | Üye işyeri API Key (hashPassword) |
    | Moka | CP.VPOS.Services.BankService.Moka | Bayi Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | |
    | Vepara | CP.VPOS.Services.BankService.Vepara | Üye İşyeri ID | Uygulama Anahtarı | Uygulama Parolası | Üye İşyeri Anahtarı |
    | ZiraatPay | CP.VPOS.Services.BankService.ZiraatPay | Firma Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | |
    | VakıfPayS | CP.VPOS.Services.BankService.VakifPayS | Firma Kodu | Api Kullanıcısı Adı | Api Kullanıcısı Şifre | |
    | Tami | CP.VPOS.Services.BankService.Tami | Üye İşyeri No | Terminal No | `KidValue` + "|" + `KValue` | Secret Key |
    | HalkÖde | CP.VPOS.Services.BankService.HalkOde | Üye İşyeri ID | Uygulama Anahtarı | Uygulama Parolası | Üye İşyeri Anahtarı |
    | Kuveyt Türk | CP.VPOS.Services.BankService.KuveytTurk | MerchantId | UserName | Password | CustomerId |
    | Vakıf Katılım | CP.VPOS.Services.BankService.VakifKatilim | MerchantId | UserName | Password | CustomerId |
    | PayNKolay | CP.VPOS.Services.BankService.PayNKolay | sx (Token) | sx list | sx iptal | Merchant Secret Key |
    | Paynet | CP.VPOS.Services.BankService.Paynet | Bayi Kodu | Publishable Key | Secret Key | |