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. When the AEGVEN deployment has email delivery configured, the invitation link is emailed to the invitee and the console only confirms that it was sent; otherwise the console shows the one-time link once, to share through your approved secure channel. New members choose a password. Accepting an emailed link also confirms that you own the address. Someone who already has an AEGVEN account signs in with it first and then accepts the invitation; the console does both when they enter their current password. Five failed attempts revoke an invitation. Administrators can change roles or disable members; these actions invalidate the affected sessions. A last active administrator cannot be removed.
If your first administrator password was set or seen by someone else — handed to you by AEGVEN onboarding, or set with the offline provisioning tool — the console asks you to replace it before anything else. Until you do, the API answers every request except reading your session, signing out and POST /api/v2/session/password with 403 password_change_required, and GET /api/v2/session reports password_change_required: true. The new password must differ from the old one; changing it signs you out everywhere, so sign in again with the new password. Where email delivery is configured, a new organization's first administrator instead receives an emailed link to choose their own password.
When an AEGVEN operator issues password recovery, invites an administrator or changes your organization's status, every active administrator receives an email notice (where email delivery is configured). Recovery links are emailed to the person being recovered and expire after 30 minutes.
Administrator has full organization access. Developer manages scoped API credentials, webhooks, event delivery and safe API diagnostics, but cannot perform manual financial work or read customer workflow data. Operations user performs the manual obligation, CSV, recipient-link, document, evidence, exception and reconciliation workflow, but cannot access credentials, webhooks, members or organization settings. Reviewer can inspect the financial workflow and accepted evidence with no mutations, hosted bearer links, credentials, settings or CSV export. For account recovery, contact your AEGVEN onboarding contact.
Use the console immediately
- Confirm your organization and individual role in the header.
- Open Obligations → Add obligation. Enter the other company, exact amount/currency and final deadline, then name any payment stages and choose when each becomes payable. A single stage covers the full amount. AEGVEN assigns a unique manual source ID automatically.
- 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.
- The recipient can acknowledge, provide an expected date, report a payment against an active stage, attach a receipt to the claim and send messages without registering.
- Inspect Interactions, Observations, Exceptions, Documents and Reconciliation. A payment report leaves confirmed balances unchanged. An issuer bank-observation document and independently recorded observation are required before evidence acceptance. AEGVEN requires an exact reference, matching currency and bounded allocation; partial acceptance leaves the stage or obligation partially reconciled.
For existing records, open a company and its Project, Order or other group. Import obligations accepts a CSV or Excel table with column mapping and row corrections; review all rows before atomic acceptance. Alternatively, open a PDF invoice, inspect the extracted draft or enter details from a scan, confirm the company and payment schedule, then create the obligation with the original PDF attached. An individual issuer-viewed obligation offers Export record as a human-readable CSV report or paginated PDF summary; the original invoice remains a separate document. Each payment stage offers its own PDF and CSV status report to both the authorized issuer and secure-link recipient, even before payment. These stage reports distinguish what the payer reported from confirmed payment and accepted credit, so an unconfirmed report is never proof of settlement. None of these reports is a direct re-import template. The Payment review page handles unmatched, outgoing and multi-obligation external payments.
The payer chooses how an already-made stage payment was sent, with an optional transaction reference. This is self-reported and never asks for full card or account credentials. Compact Overview and Conversation counts show new activity from the other side; opening a tab clears its count for that viewer. A payment claim and its receipt do not reduce the remaining balance until the issuer accepts independent evidence.
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://docs.aegven.com/aegven-sdk-0.13.0.tgzExplore 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 and select only the scopes the integration needs: obligations:read, obligations:write, documents:read, documents:write, events:read, webhooks:manage, and/or settings:manage (schedules, payment stages, terminology, payment matching and source connections). A key can only carry access your own role has, so Developers can issue events:read and webhooks:manage keys only. Copy the secret once into your integration server's secret store. Rotation inherits its current scopes unless you explicitly narrow them; the replaced key keeps working for 24 hours and then stops. Create a separate key for expanded access. Disabling a member revokes the keys they created. Existing unscoped credentials appear as Legacy full access and must be replaced, verified and revoked. Never put API keys in browser code or outgoing mail.
Set AEGVEN_API_URL to your supplied origin plus /api/v2, 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: { source_reference: '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 insufficient_permission: the signed-in human role is not allowed to use that endpoint.403 insufficient_scope: the API key does not carry the scope required by that machine endpoint.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 accepts CSV files using the aegven.obligations.v1 profile. Create a file with these exact ordered columns:
profile,obligation_type,external_namespace,external_id,source_reference,debtor_name,debtor_email,amount_minor,currency,deadline,descriptionUse profile aegven.obligations.v1, type invoice, exact minor-unit strings, uppercase currency, and ISO YYYY-MM-DD deadline. Description may be empty. In the console, choosing a file automatically previews it; Import becomes available only when every row is valid. The API preview and accept endpoints 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.