SDK guide

AEGVEN provides TypeScript/JavaScript, C#/.NET, Python and Go clients for the same versioned public API. All clients register a FinancialObligation, obtain its secure hosted interaction, and operate on the same accepted records as the Web Console. The invoice source adapter is the currently enabled obligation type. AEGVEN does not collect or transfer funds.

Packages and installation

Download version 0.1.0 from the SDK installation page. Choose your language for installation commands and a registration example. Packages are available directly from AEGVEN; use the download URL or local file instructions below. Your onboarding contact provides organization access and confirms the API environment for your integration.

The Python, Go and C# SDKs use only their language standard libraries at runtime. Python includes generated TypedDict/Literal types and a py.typed marker. Go includes generated structs and distinct action payloads. C# includes generated records with JSON field mappings, required properties and distinct action records. Money is always an exact minor-unit string, including in responses. SDKs perform transport validation only; financial decisions remain in AEGVEN.

npm install ./aegven-sdk-0.1.0.tgz

# From your .NET application, point --source at the supplied artifact directory.
dotnet add package Aegven.Sdk --version 0.1.0 --source /path/to/artifacts

python3 -m venv .venv
.venv/bin/python -m pip install ./aegven_sdk-0.1.0-py3-none-any.whl

# Keep this source directory with your application.
mkdir -p vendor-src
tar -xzf aegven-go-0.1.0.tar.gz -C vendor-src
go mod edit -require=aegven.com/sdk/go@v0.1.0
go mod edit -replace=aegven.com/sdk/go=./vendor-src/aegven-go-0.1.0
go mod tidy

The Go source package uses the local module replacement shown above. Verify downloads against SHA-256 checksums and pin your SDK version. Review the API reference before upgrading.

Credentials and source registration

An organization administrator or developer signs into the Web Console with an individual account and creates a machine credential under Developers → API keys. Store its one-time secret in the integration server's secret manager. Configure AEGVEN_API_URL (including /api/v1) and AEGVEN_API_KEY on that server. The Python, Go and C# SDKs require HTTPS except for explicit localhost, 127.0.0.1, or ::1 development URLs. They do not follow redirects or use human login cookies.

Set SOURCE_RECORD_ID to your source system's stable identifier and AEGVEN_IDEMPOTENCY_KEY to a durably stored registration key. The following examples deliberately do not generate a fresh retry key. Persist the returned obligation ID and hosted URL on the original record; your existing communication process inserts the URL into its outgoing message. Treat that URL as a secret bearer capability. Do not put machine credentials or SDK clients in recipient browsers. Recipients continue using scoped secure links without accounts.

TypeScript / JavaScript

import { Aegven } from '@aegven/sdk';
const aegven = new Aegven({
  baseURL: process.env.AEGVEN_API_URL!,
  apiKey: process.env.AEGVEN_API_KEY!,
});
const created = await aegven.obligations.register(
  {
    obligation_type: 'invoice',
    external_reference: { namespace: 'your-system', id: 'source-1042' },
    debtor: { name: 'Recipient company', email: 'accounts@example.com' },
    business_context: { invoice_number: 'INV-1042', description: 'Services' },
    amount_minor: '125000',
    currency: 'CAD',
    deadline: '2027-12-31',
  },
  'register-source-1042',
);
const obligationID = created.obligation!.id;
const hostedURL = created.payment_request!.hosted_url;
// Persist both on your source record and insert hostedURL into your outgoing template.
// Dispatch through your existing mail outbox with a stable mail-message key.

Create the client in your server application using your HTTPS API URL. Store the returned obligation ID and hosted URL with your source record. TypeScript requests use a 15-second timeout per attempt and retry once on a transport failure or HTTP status 502 or above. Errors expose code, status and idempotencyKey on AegvenError. A timeout or an unreadable response does not establish whether the operation was accepted; recover using the original idempotency key.

Python

import os
from aegven import Aegven, models

client = Aegven(os.environ['AEGVEN_API_URL'], os.environ['AEGVEN_API_KEY'])
request: models.RegisterObligation = {
    'obligation_type': 'invoice',
    'external_reference': {'namespace': 'company-source', 'id': os.environ['SOURCE_RECORD_ID']},
    'debtor': {'name': 'Recipient company', 'email': 'accounts@example.invalid'},
    'amount_minor': '125000',
    'currency': 'CAD',
    'deadline': '2027-01-05',
    'business_context': {'invoice_number': 'REF-1042'},
}
created = client.register_obligation(request, os.environ['AEGVEN_IDEMPOTENCY_KEY'])
obligation = created.get('obligation')
obligation_id = obligation['id'] if obligation else created['invoice']['id']
payment_request = created.get('payment_request') or client.get_payment_request(obligation_id)
# Persist obligation_id and payment_request['hosted_url'] in your source record.

Python is synchronous. Its configurable timeout defaults to 15 seconds per blocking socket operation; there is no async client or in-flight cancellation API in this version. Use your worker's execution deadline when scheduling calls. The generated annotations aid static checking; they are not runtime schema validation.

C# / .NET

using Aegven;

using var client = new AegvenClient(
    Environment.GetEnvironmentVariable("AEGVEN_API_URL")!,
    Environment.GetEnvironmentVariable("AEGVEN_API_KEY")!);
var request = new RegisterObligation
{
    ObligationType = "invoice",
    ExternalReference = new() { Namespace = "company-source", Id = Environment.GetEnvironmentVariable("SOURCE_RECORD_ID")! },
    Debtor = new() { Name = "Recipient company", Email = "accounts@example.invalid" },
    AmountMinor = "125000", Currency = "CAD", Deadline = "2027-01-05",
    BusinessContext = new() { InvoiceNumber = "REF-1042" },
};
var created = await client.RegisterObligationAsync(request,
    Environment.GetEnvironmentVariable("AEGVEN_IDEMPOTENCY_KEY")!);
var obligationId = created.Obligation?.Id ?? created.Invoice.Id;
var paymentRequest = created.PaymentRequest ?? await client.GetPaymentRequestAsync(obligationId);
// Persist obligationId and paymentRequest.HostedUrl in your source record.

Reuse one AegvenClient for the integration service's lifetime and dispose it at shutdown. All operations accept an optional CancellationToken; the default HTTP timeout is 15 seconds per attempt. The constructor accepts a custom timeout. Canceling a call does not prove the server rolled back a mutation.

Go

package main

import (
    "context"
    "os"
    "time"

    aegven "aegven.com/sdk/go"
)

func main() {
    client, err := aegven.New(aegven.Options{
        BaseURL: os.Getenv("AEGVEN_API_URL"), APIKey: os.Getenv("AEGVEN_API_KEY"),
    })
    if err != nil { panic(err) }
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    created, err := client.RegisterObligation(ctx, aegven.RegisterObligation{
        ObligationType: "invoice",
        ExternalReference: aegven.ExternalReference{Namespace: "company-source", Id: os.Getenv("SOURCE_RECORD_ID")},
        Debtor: aegven.RegisterObligationDebtor{Name: "Recipient company", Email: "accounts@example.invalid"},
        AmountMinor: "125000", Currency: "CAD", Deadline: "2027-01-05",
        BusinessContext: aegven.BusinessContext{InvoiceNumber: "REF-1042"},
    }, os.Getenv("AEGVEN_IDEMPOTENCY_KEY"))
    if err != nil { panic(err) }
    var obligationID string
    if created.Obligation != nil {
        obligationID = created.Obligation.Id
    } else {
        obligationID = created.Invoice.Id // Compatibility with older accepted replays.
    }
    paymentRequest, err := client.GetPaymentRequest(ctx, obligationID)
    if err != nil { panic(err) }
    _ = paymentRequest // Persist HostedUrl together with obligationID.
}

Go clients can be shared across goroutines. Every call requires a context. The HTTP client defaults to a 15-second per-attempt timeout. A supplied Options.HTTPClient is copied and retains a positive timeout; cookies and redirects are disabled. Custom transports must preserve TLS verification and protect credentials. Neither cancellation nor deadline expiry proves a mutation was rejected.

Supported workflows

All 33 machine-authorized OpenAPI operations have named methods in the Python, Go and C# SDKs. Python uses snake_case, Go uses PascalCase, and C# uses PascalCase with Async.

Legacy invoice routes are retained for compatibility (create_invoice, get_invoice, list_invoices, prepare_delivery, apply_invoice_action, upload_invoice_document, download_invoice_document, with the same naming conventions in Go/C#). New integrations should start with canonical obligation methods. Registration replays accepted before canonical response additions may only contain invoice; its ID is the same obligation ID.

Mutation methods require an explicit 8–200 character printable idempotency key. Lists expose the API's existing pagination: obligations/invoices accept limit and offset; activity accepts offset. Use ListObligations(ctx, 50, 0) in Go. There is no hidden auto-pagination or financial status calculation. The API remains authoritative for supported actions, permissions and validation errors. Human sessions, member management and machine-key creation/rotation/revocation are intentionally not exposed through an API-key client. Use individual console access for those operations.

Documents take the original bytes, plain filename, media type, document kind and expected version. Uploads are buffered so retries use identical bytes and the same multipart boundary. Downloads and exports return bytes. Preserve the existing server limits and document authorization; this SDK does not introduce scanning, storage or public download access.

Safe retries and errors

Keep the request body and idempotency key durably together. The Python, Go and C# clients make at most two application-level attempts on transport/read failures or HTTP 502/503/504, reusing the exact encoded body and key. Other errors are returned immediately. No automatic business retry is performed for 409 or 422. A Go custom transport or the standard transport's connection recovery may have its own safe connection retry behavior.

Errors expose code, status, idempotency_key in Python; Code, Status, IdempotencyKey in Go/.NET. The exception types are AegvenError, *aegven.AegvenError and AegvenException. Their diagnostic messages exclude raw server/transport messages, request bodies and credentials. Preserve the original key externally even when your context/cancellation token fires. Do not enable HTTP-body logging on authenticated calls.

• ambiguous_network_result: the call may have committed. Query lookup_operation with the original key or replay the same request and key. Empty lookup results during in-flight processing do not establish that a call was rejected.
• idempotency_conflict: this key was used with different input. Recover the original request; do not silently change its meaning.
• version_conflict: fetch the current obligation and review the accepted history before issuing a new decision with a new key and current expected_version.
• duplicate_reference: investigate the namespaced source mapping rather than creating a second source identity.
• invalid_response: investigate the operation before retrying; a malformed reply does not establish rejection.
• HTTP 401/403: check machine credentials and authorization. HTTP 410 for a hosted request means expired/revoked access; registration replay does not renew the link.

Signing-secret rotation responses disclose a new secret once. A replay may contain metadata only. If the first response is lost, investigate the operation and deliberately issue another rotation with a new key to obtain an accessible secret. Keep that distinction from financial-operation replay recovery.

Webhooks and status meaning

Register an endpoint with RegisterWebhookRequest (url and a server-held signing secret of 32–256 characters). Run the test method and inspect deliveries plus readiness. AEGVEN signs both test and financial events and retries unsuccessful deliveries. Your receiver verifies each event before applying updates.

Read the exact HTTP body bytes and the Aegven-Signature header before parsing JSON. Verification helpers check HMAC-SHA256 in constant time and enforce a default/recommended five-minute past/future timestamp window:

from aegven import verify_webhook
valid = verify_webhook(raw_body, signature_header, signing_secret)

var valid = Webhooks.Verify(rawBody, signatureHeader, signingSecret);

valid := aegven.VerifyWebhook(rawBody, signatureHeader, signingSecret, time.Now(), 5*time.Minute)

Reject invalid signatures. After verification, durably deduplicate event IDs before applying source-system effects, then acknowledge promptly. Handle retries and out-of-order deliveries using canonical versions; fetch current state when necessary. Do not recreate signatures from parsed/re-serialized JSON. Test events use the generated IntegrationTestEvent shape (type: integration.test, resource_type: webhook_endpoint) and contain no obligation. Financial events use ObligationEvent.

A payer report is an unverified PaymentClaim; an external record is a PaymentObservation. Only accepted evidence and allocations affect reconciliation. Display the returned OBLIGATION_CAPTURED, PAYMENT_REQUESTED, PAYMENT_CLAIMED, PARTIALLY_RECONCILED and RECONCILED states faithfully. No SDK interprets “I paid” as settlement or calculates authoritative allocations.