Quickstart

AEGVEN connects business financial obligations, recipient interactions and accepted evidence. AEGVEN does not collect or transfer funds. An invoice is the first enabled source adapter; the canonical record is a FinancialObligation.

Obtain access

Your AEGVEN onboarding contact provides organization access and confirms the API environment you should use. The Customer Console is available at app.aegven.com. Sign in to the console with your email and password. API keys are machine credentials and cannot sign you in. Recipients open scoped secure links without accounts.

An administrator may create a 48-hour invitation under Organization → Members & roles and share it through their approved secure channel. AEGVEN does not automatically send invitation email. New members choose a password; existing users accept with their current password. Administrators can change roles or disable members; these actions invalidate the affected sessions. A last active administrator cannot be removed.

Administrator and Developer can register obligations, upload issuer evidence, review supported observations, and manage integrations. Reviewer can inspect records and documents, with no mutations or hosted bearer-link retrieval. For account recovery, contact your AEGVEN onboarding contact.

Use the console immediately

1. Confirm your organization and individual role in the header.
2. Open Obligations → Manual registration. Enter a namespaced source ID, source invoice number, debtor, exact amount/currency and deadline. The signed-in organization is the creditor.
3. Open Manual email preparation to obtain the secure hosted interaction URL. Insert it into your existing outgoing communication, retaining the original document. Confirm sending only after your communication system accepts the message.
4. The recipient can acknowledge, provide an expected date, report payment, upload supporting documents and send messages without registering.
5. Inspect Interactions, Observations, Exceptions, Documents and Reconciliation. Payment reported is unverified. An issuer bank-observation document and separately recorded observation are required before explicit evidence acceptance. AEGVEN requires an exact reference, matching currency and bounded allocation; partial acceptance can leave an obligation partially reconciled.

Manual and automated registration use the same public commands and records. API integration is optional for manual use.

Install the versioned SDK

Choose TypeScript/JavaScript, Python, Go or C#/.NET on the SDK installation page. For TypeScript and JavaScript, use Node.js 22 or later:

npm install https://sdk.aegven.com/aegven-sdk-0.1.0.tgz

Explore requests, parameters and response schemas in the API reference. You can also download the OpenAPI specification for your own tooling.

Connect your source workflow

Create a named key under Developers → API keys. Copy the secret once into your integration server's secret store. A rotation creates a replacement; deploy it, check successful usage and then revoke the old credential. Never put API keys in browser code or outgoing mail.

Set AEGVEN_API_URL to your supplied origin plus /api/v1, and AEGVEN_API_KEY to the new key. Configure a webhook endpoint before generating events.

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.

Amounts are exact minor-unit decimal strings: CAD 1,250.00 is 125000, while JPY 1,250 is 1250. Do not use binary floating-point financial arithmetic. The API rejects unsupported currencies and adapters through the financial policy.

After your mail transport accepts the message, fetch the obligation version and submit sent with expected_version and a stable idempotency key. Source dispatch is a separate external effect from AEGVEN registration; persist the mapping and deduplicate your own mail send.

Signed webhooks and health

Register a URL and a random 32–256 character signing secret. Use a public HTTPS endpoint for your webhook receiver. Redirects and destinations that resolve to private or reserved addresses are rejected.

await aegven.registerWebhook(
  'https://your-system.example/events/aegven',
  process.env.AEGVEN_WEBHOOK_SECRET!,
  'register-webhook-v1',
);
const endpoints = await aegven.control.endpoints();
await aegven.control.testEndpoint(endpoints.items[0].id, 'test-webhook-v1');
const deliveries = await aegven.deliveries();

A test has type integration.test, resource type webhook_endpoint, and no obligation. It is signed and delivered using the same retry policy as financial events. Accept and deduplicate test envelopes without attempting to update a financial source record. Inspect Event deliveries for state, HTTP status and attempt history; HTTP 0 means no response was received. Failed deliveries can be explicitly retried. Response bodies are not retained. Configuration/signing changes require a new successful test for readiness.

import { verifyWebhook } from '@aegven/sdk/webhooks';
const valid = await verifyWebhook(rawBody, signatureHeader, process.env.AEGVEN_WEBHOOK_SECRET!);
// Reject invalid signatures before parsing or applying the JSON.

Verify the raw bytes, including the timestamp window. Persist event-ID deduplication and source-record updates atomically. Return 2xx after durable acceptance. Use namespace + source ID + obligation ID, never equal amount or recipient name alone. Ignore stale aggregate snapshot versions. Delivery is at least once with eight attempts and exponential backoff, and is not globally ordered.

Signing-secret rotation takes effect immediately for subsequent sends. Keep old and new receiver secrets during the short in-flight transition; update your receiver promptly. Old secrets cannot be recovered. A replayed key/secret creation response contains metadata only. If you lose the initial secret response, revoke the inaccessible key or rotate the signing secret again with a new request key.

Retries, uncertainty and status meanings

Every mutation takes an explicit idempotency key. Retry the exact body with the same key after a timeout. Do not use a fresh key to hide an ambiguous result. For accepted issuer operations, use:

const matches = await aegven.control.lookupOperation('register-source-1042');
// Or: await aegven.control.operation(created.operation_id);

Lookup returns accepted operation metadata and its obligation ID, never a stored bearer URL or secret. No match means no accepted operation was found at the query instant; it does not prove an in-flight request will fail. Replaying the original request remains the recovery path. Query the obligation/payment request with current authorization when you need its present state or active link.

• 409 idempotency_conflict: key reused with changed input; correct the caller.
• 409 version_conflict: fetch current state, reconsider the command and use its version with a new key.
• 409 duplicate_reference: namespaced source/observation or allocation already exists.
• 422 decision_rejected: financial policy rejected the command.
• 503 engine_unavailable: retry exact input/key; no partial decision is committed.
• 401: expired session or invalid/revoked credential; 403: role or origin restriction.
• 429 login_limited: wait for the 15-minute throttle window.

PAYMENT_CLAIMED means payment reported — unverified. An observation alone is not accepted settlement evidence. PARTIALLY_RECONCILED reflects accepted partial allocations. RECONCILED means accepted external evidence covers the obligation under the current review policy. These states do not claim that AEGVEN moved funds or performed automated bank verification.

Generic CSV bridge

Import / export offers a CSV template for aegven.obligations.v1. Exact ordered columns:

profile,obligation_type,external_namespace,external_id,source_reference,debtor_name,debtor_email,amount_minor,currency,deadline,description

Use profile aegven.obligations.v1, type invoice, exact minor-unit strings, uppercase currency, and ISO YYYY-MM-DD deadline. Description may be empty. Preview and accept take the same raw CSV and an explicit stable batch key through /imports/obligations/preview and /imports/obligations/accept (or SDK control.previewImport / control.acceptImport). Each batch is at most 50 rows / 512 KB. Headers, quoting, source duplicates and every financial row are validated. Inspect row numbers, error codes and messages. Preview accepts nothing; acceptance commits every row together or none. A changed file invalidates its preview; re-preview it before submitting.

CSV v1 accepted-result export includes obligation ID, source identity, obligation reference, exact amount, currency, canonical status, accepted allocated amount, version and updated timestamp. Up to 10,000 records are exported from a consistent snapshot; use paginated API queries above that limit. Cells that could become spreadsheet formulas are prefixed with an apostrophe. No bearer links, credentials or document contents are exported.

Test your integration

Test with sample data: register, deliver a link, acknowledge, provide an expected date, report a payment, upload separate issuer evidence, record an observation, explicitly accept evidence, then inspect reconciliation and signed updates. Use two equal-amount obligations to verify reference isolation and intentionally fail one webhook delivery to verify retry/deduplication.

The runnable reference simulator demonstrates source creation → existing outgoing email template → recipient inbox → secure interaction → signed source update. It is provided as a development reference, not a customer-software dependency. Request its source bundle from your onboarding contact if you need an executable example.

Use the environment provided during onboarding and sample data for integration testing. The SDK guide includes registration examples, supported operations, retry recovery and webhook verification for all four languages.

Organization profile and access lifecycle

Company administrators can update the organization display name and upload/replace/remove a PNG or JPEG logo in Settings. Logos are private to the organization and its scoped hosted recipients; uploads are limited to 1 MiB and 2048 × 2048 pixels. Files are checked before they become available.

If AEGVEN suspends or closes an organization, customer API/human and hosted-recipient access are blocked and new webhook dispatch pauses. Reactivation preserves history and resumes queued delivery; customer humans sign in again. Previously leased work may finish during the transition. Contact your AEGVEN onboarding contact for help with account recovery. API integration still requires only the public API/SDK, organization credential, webhook contract and your own mapping code.