# Solifyn Payments - Developer & API Documentation

Welcome to Solifyn. Solifyn is a developer-first payment gateway, merchant of record, and software licensing platform. It provides APIs and SDKs to manage products, customers, checkout sessions, subscriptions, and issue/verify software license keys.

## API Specification & Authentication
All API requests must be made over HTTPS to the API server (default local development port: `http://localhost:8000`).

### Authentication
Solifyn APIs authenticate requests using a Bearer token. Pass your API key in the `Authorization` header of all requests:
```http
Authorization: Bearer <YOUR_API_KEY>
```

---

## Core Modules & Endpoints

### 1. Products (`/v1/products`)
Manage products offered to customers. Products can have one-time or recurring pricing, usage-based billing, tax categories, and optional digital delivery or license key attachment.
- **POST** `/v1/products` - Create Product
- **GET** `/v1/products` - List Products
- **GET** `/v1/products/{id}` - Retrieve Product
- **PATCH** `/v1/products/{id}` - Update Product
- **DELETE** `/v1/products/{id}` - Archive Product
- **POST** `/v1/products/{id}/unarchive` - Unarchive Product

#### Product Add-ons (`/v1/products/{id}/addons`)
- **GET** `/v1/products/all-addons/list` - List All Add-ons
- **POST** `/v1/products/{id}/addons` - Create Product Add-on
- **GET** `/v1/products/{id}/addons` - List Product Add-ons
- **GET** `/v1/products/{id}/addons/{addonId}` - Retrieve Add-on Details
- **PATCH** `/v1/products/{id}/addons/{addonId}` - Update Add-on
- **DELETE** `/v1/products/{id}/addons/{addonId}` - Delete Add-on

---

### 2. License Keys (`/v1/licenses`)
Issue and validate license keys for your software products.
- **POST** `/v1/licenses` - Create License Key
- **GET** `/v1/licenses` - List License Keys
- **GET** `/v1/licenses/{id}` - Retrieve License Key
- **PATCH** `/v1/licenses/{id}` - Update License Key
- **POST** `/v1/licenses/{id}/toggle` - Toggle License Key Status (Enable/Disable)

#### Client Validation & Activation (Public Endpoint)
These endpoints are used within client software using a license key for verification and activation of device instances:
- **POST** `/v1/licenses/verify` - Validate License Key
- **POST** `/v1/licenses/activate` - Activate Instance
- **POST** `/v1/licenses/deactivate/{instanceId}` - Deactivate Instance
- **GET** `/v1/licenses/instances/{licenseId}` - Retrieve Active Instances
- **GET** `/v1/licenses/{id}/instances` - List License Instances (Admin)
- **GET** `/v1/licenses/{id}/instances/{instanceId}` - Retrieve Instance Details (Admin)
- **PATCH** `/v1/licenses/{id}/instances/{instanceId}` - Update Instance (Admin)
- **DELETE** `/v1/licenses/instances/{instanceId}` - Force Delete Instance (Admin)

---

### 3. Checkouts & Checkout Links (`/v1/checkout`)
Generate secure payment checkout sessions and shareable payment links.
- **POST** `/v1/checkout/create` - Create Checkout Session
- **POST** `/v1/checkout/collection/create` - Create Collection Checkout Session
- **GET** `/v1/checkout/session/{id}` - Get Checkout Session Details
- **GET** `/v1/checkout/price-preview` - Get Converted Price Preview
- **GET** `/v1/checkout/supported-currencies` - Get Supported Currencies
- **POST** `/v1/checkout-links` - Create Checkout Link
- **GET** `/v1/checkout-links` - List Checkout Links
- **GET** `/v1/checkout-links/{id}` - Retrieve Checkout Link
- **PATCH** `/v1/checkout-links/{id}` - Update Checkout Link
- **DELETE** `/v1/checkout-links/{id}` - Delete Checkout Link

---

### 4. Customers (`/v1/customers`)
Manage customer records for subscriptions, billing, and order histories.
- **POST** `/v1/customers` - Create Customer
- **GET** `/v1/customers` - List Customers
- **GET** `/v1/customers/{id}` - Retrieve Customer Details
- **PATCH** `/v1/customers/{id}` - Update Customer Details
- **POST** `/v1/customers/{id}/share` - Generate Shared Invite Link

---

### 5. Collections (`/v1/collections`)
Group multiple products together into collections for organized checkouts and portals.
- **POST** `/v1/collections` - Create Collection
- **GET** `/v1/collections` - List Collections
- **GET** `/v1/collections/{id}` - Retrieve Collection Details
- **PATCH** `/v1/collections/{id}` - Update Collection
- **DELETE** `/v1/collections/{id}` - Archive Collection
- **POST** `/v1/collections/{id}/unarchive` - Unarchive Collection
- **GET** `/v1/collections/archived` - List Archived Collections
- **POST** `/v1/collections/{id}/products` - Add Products to Collection
- **PATCH** `/v1/collections/{id}/products/{productId}` - Update Collection Product configuration
- **DELETE** `/v1/collections/{id}/products/{productId}` - Remove Product from Collection

---

### 6. Subscriptions (`/v1/subscriptions`)
Handle recurring subscriptions and customer billing periods.
- **GET** `/v1/subscriptions` - List Subscriptions
- **GET** `/v1/subscriptions/{id}` - Retrieve Subscription Details
- **POST** `/v1/subscriptions/{subscriptionId}/{action}` - Execute Subscription Action (pause, resume, cancel)

---

### 7. Discounts (`/v1/discounts`)
Apply coupon codes and fixed/percentage discounts to checkout sessions.
- **POST** `/v1/discounts` - Create Discount
- **GET** `/v1/discounts` - List Discounts
- **GET** `/v1/discounts/{id}` - Retrieve Discount Details
- **PATCH** `/v1/discounts/{id}` - Update Discount
- **DELETE** `/v1/discounts/{id}` - Delete Discount
- **GET** `/v1/discounts/validate` - Validate Code

---

### 8. Meters & Usage Events (`/v1/meters`)
Ingest event data for usage-based billing and metered SaaS components.
- **POST** `/v1/meters` - Create Meter
- **GET** `/v1/meters` - List Meters
- **GET** `/v1/meters/{id}` - Retrieve Meter Details
- **PATCH** `/v1/meters/{id}` - Update Meter
- **POST** `/v1/meters/ingest` - Ingest Usage Events
- **GET** `/v1/meters/{id}/events` - List Ingested Events
- **GET** `/v1/meters/{id}/quantities` - Get Current Quantities/Costs

---

### 9. Balances & Reports (`/v1/balances`)
Access financial ledger balances and generate CSV exports.
- **GET** `/v1/balances` - Find Ledger Balances
- **GET** `/v1/balances/summary` - Get Financial Balance Summary
- **GET** `/v1/balances/report` - Generate Report CSV

---

### 10. Webhooks & Developer Settings (`/v1/developer`)
Register HTTP endpoints to receive webhook event notifications.
- **POST** `/v1/developer/webhooks` - Create Webhook Endpoint
- **GET** `/v1/developer/webhooks` - List Webhook Endpoints
- **PATCH** `/v1/developer/webhooks/{id}` - Update Webhook Endpoint
- **DELETE** `/v1/developer/webhooks/{id}` - Delete Webhook Endpoint
- **GET** `/v1/developer/webhooks/{id}/deliveries` - Retrieve Webhook Delivery Logs
- **GET** `/v1/developer/webhooks/app-portal` - Retrieve App Portal URL
- **POST** `/v1/developer/api-keys` - Generate Developer API Key
- **GET** `/v1/developer/api-keys` - List Developer API Keys
- **DELETE** `/v1/developer/api-keys/{id}` - Revoke API Key

---

### 11. Operational Webhooks (`/v1/operational-webhook/endpoint`)
Manage custom endpoints to receive operational alerts (e.g. standard webhook failures or automatically disabled endpoints).
- **GET** `/v1/operational-webhook/endpoint` - List Operational Webhook Endpoints
- **POST** `/v1/operational-webhook/endpoint` - Create Operational Webhook Endpoint
- **GET** `/v1/operational-webhook/endpoint/{id}` - Retrieve Operational Webhook Endpoint
- **PUT** `/v1/operational-webhook/endpoint/{id}` - Update Operational Webhook Endpoint
- **DELETE** `/v1/operational-webhook/endpoint/{id}` - Delete Operational Webhook Endpoint
- **GET** `/v1/operational-webhook/endpoint/{id}/headers` - Retrieve Custom Headers
- **PUT** `/v1/operational-webhook/endpoint/{id}/headers` - Update Custom Headers
- **GET** `/v1/operational-webhook/endpoint/{id}/secret` - Retrieve Endpoint Signing Secret
- **POST** `/v1/operational-webhook/endpoint/{id}/secret/rotate` - Rotate Signing Secret

---

## SDK Integration

Official SDKs are available for multiple programming languages.

### TypeScript SDK (NPM: `solifyn`)
```typescript
import { Solifyn } from 'solifyn';

const solifyn = new Solifyn({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.solifyn.com' // Optional
});

// Example: Retrieve a product
const product = await solifyn.products.get('prod_123');
```

### Python SDK
```python
import solifyn

configuration = solifyn.Configuration(
    host = "https://api.solifyn.com",
    access_token = "YOUR_API_KEY"
)

with solifyn.ApiClient(configuration) as api_client:
    products_api = solifyn.ProductsApi(api_client)
    products = products_api.products_list()
```

### Go SDK
```go
package main

import (
	"context"
	"fmt"
	solifyn "github.com/solifyn/solifyn-go"
)

func main() {
	cfg := solifyn.NewConfiguration()
	cfg.Host = "https://api.solifyn.com"
	client := solifyn.NewAPIClient(cfg)

	auth := context.WithValue(context.Background(), solifyn.ContextAccessToken, "YOUR_API_KEY")
	products, resp, err := client.ProductsAPI.ProductsList(auth).Execute()
}
```

### PHP SDK
```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = Solifyn\Client\Configuration::getDefaultConfiguration()
    ->setHost('https://api.solifyn.com')
    ->setAccessToken('YOUR_API_KEY');

$apiInstance = new Solifyn\Client\Api\ProductsApi(
    new GuzzleHttp\Client(),
    $config
);

try {
    $result = $apiInstance->productsList();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception: ', $e->getMessage(), PHP_EOL;
}
```

### Java SDK
```java
import com.solifyn.ApiClient;
import com.solifyn.Configuration;
import com.solifyn.auth.HttpBearerAuth;
import com.solifyn.api.ProductsApi;

public class Main {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.solifyn.com");

        HttpBearerAuth ApiKeyAuth = (HttpBearerAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setBearerToken("YOUR_API_KEY");

        ProductsApi apiInstance = new ProductsApi(defaultClient);
        try {
            Object result = apiInstance.productsList(null, null, null, null, null, null, null);
            System.out.println(result);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

### Ruby SDK
```ruby
require 'solifyn'

Solifyn.configure do |config|
  config.host = 'https://api.solifyn.com'
  config.access_token = 'YOUR_API_KEY'
end

api_instance = Solifyn::ProductsApi.new

begin
  result = api_instance.products_list
  p result
rescue Solifyn::ApiError => e
  puts "Exception when calling ProductsApi->products_list: #{e}"
end
```

### C# SDK
```csharp
using System;
using System.Diagnostics;
using Solifyn.Api;
using Solifyn.Client;

namespace Example
{
    public class Example
    {
        public static void Main()
        {
            Configuration config = new Configuration();
            config.BasePath = "https://api.solifyn.com";
            config.AccessToken = "YOUR_API_KEY";

            var apiInstance = new ProductsApi(config);

            try
            {
                var result = apiInstance.ProductsList();
                Console.WriteLine(result);
            }
            catch (ApiException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}
```

### Kotlin SDK
```kotlin
import com.solifyn.infrastructure.ApiClient
import com.solifyn.api.ProductsApi

fun main() {
    val client = ApiClient(baseUrl = "https://api.solifyn.com")
    client.setBearerToken("YOUR_API_KEY")

    val productsApi = ProductsApi(client)
    val products = productsApi.productsList()
    println(products)
}
```