Start with the connection.

Overview

AEGVEN’s integration model connects your existing software to financial obligations and their progress. Your backend submits the business context. Your customer receives a hosted interaction. Your application consumes updates and decides how to reflect them locally.

Access and authentication

Contact us about developer access before building against an environment. We will confirm scope and provide the applicable API version, base URL, organization access, and SDK instructions. Your administrator or developer provisions the machine credential through individual console access.

API calls use an organization credential in the Authorization: Bearer header. Keep credentials on your server, in a protected configuration or secret store. Never embed them in browser code, mobile bundles, URLs, or public repositories.

The examples use AEGVEN_API_URL for an assigned base URL including /api/v1. See the public API reference for request and response contracts. Obtain credentials through your organization’s console.

One integration, three steps.

1. Register the obligation.

   Send your namespaced source reference, the relevant business context, counterparty details, amount, currency, and due date. Use a stable idempotency key for that operation.

2. Connect your customer.

   New registration returns the obligation and a hosted payment-request URL. Store the mapping securely and insert the link into your existing communication. The recipient does not need an AEGVEN account or an integration.

3. Reflect progress.

   Retrieve the resource or receive signed updates. Correlate updates to your stored source reference and obligation ID, then apply them according to your own business workflow.

Your system remains the starting point. Routine console use is optional once your integration is configured. Initial access and credential management use individual console accounts.

A request with business context.

This fictional example registers a $1,250.00 USD invoice. The amount is the string "125000", expressed in the currency’s minor units. Never use floating-point arithmetic for monetary values. Minor-unit precision depends on the currency.

# AEGVEN_API_URL is your assigned base URL, including /api/v1.
# Use only the test environment and credentials provided to you.
curl --request POST "$AEGVEN_API_URL/obligations" \
  --header "Authorization: Bearer $AEGVEN_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: register-invoice-1042" \
  --data '{
  "obligation_type": "invoice",
  "external_reference": {
    "namespace": "your-system",
    "id": "invoice-1042"
  },
  "debtor": {
    "name": "Example Business",
    "email": "accounts@example.com"
  },
  "amount_minor": "125000",
  "currency": "USD",
  "deadline": "2027-01-15",
  "business_context": {
    "invoice_number": "INV-1042",
    "description": "Business services"
  }
}'

The example is not a coverage statement. Confirm the currencies and workflows supported in your assigned environment.

Keep your reference stable

The namespace identifies your source system; the ID identifies the source record. Together they let your application associate the obligation with the correct business context. Reuse that mapping for later updates.

Protect the hosted link

A hosted URL gives its holder access to a specific interaction. Treat it as confidential: share it with the intended recipient, exclude it from logs and analytics, and respect its expiry. A visit to the link does not independently verify the identity of the person using it.

Registration replay preserves the original result. If access has expired or been revoked, replay does not renew it. An active-request lookup can return HTTP 410.

Keep sending in your own workflow

Persist the source mapping, then insert the link into your existing email template. Deduplicate the outgoing message separately from API registration. After your mail transport accepts it, record the sending report:

// Run only after YOUR mail transport accepts the outgoing message.
const current = await aegven.obligations.get(obligationId);
await aegven.obligations.action(obligationId, {
  action: 'sent',
  expected_version: current.version,
  payload: { delivery_reference: 'your-mail-message-id' },
}, 'sent-invoice-1042'); // Persist this key with the delivery report.
// This records a sending report, not that the recipient read the message.

The TypeScript SDK experience.

TypeScript/JavaScript, Python, C#/.NET, and Go clients follow the same API contract. Download version 0.1.0 packages from sdk.aegven.com. See the language SDK guide for installation and examples.

// Run on your integration server with the supplied SDK.
import { Aegven } from '@aegven/sdk';

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error('Missing server configuration: ' + name);
  return value;
}

const aegven = new Aegven({
  baseURL: required('AEGVEN_API_URL'), // Includes /api/v1
  apiKey: required('AEGVEN_API_KEY'),
});

const obligationInput = {
  "obligation_type": "invoice",
  "external_reference": {
    "namespace": "your-system",
    "id": "invoice-1042"
  },
  "debtor": {
    "name": "Example Business",
    "email": "accounts@example.com"
  },
  "amount_minor": "125000",
  "currency": "USD",
  "deadline": "2027-01-15",
  "business_context": {
    "invoice_number": "INV-1042",
    "description": "Business services"
  }
} as const;

// Store this key with the input before the first attempt; reuse both on retries.
const result = await aegven.obligations.register(
  obligationInput,
  required('AEGVEN_IDEMPOTENCY_KEY'),
);

// Older accepted replays can contain only the invoice projection.
const obligationId = result.obligation?.id ?? result.invoice.id;
const request = result.payment_request
  ?? await aegven.paymentRequests.getForObligation(obligationId);
const hostedUrl = request.hosted_url;
// Save the source mapping securely.
// Add hostedUrl to your existing customer communication.
// Treat the URL as confidential; never put it in logs or analytics.

This example handles older accepted responses that contain only the invoice projection. Store the idempotency key with the input before the first attempt and keep it stable across retries. Confirm the contract version supplied with your environment.

Understand what a status means.

Present progress with the same care you apply to financial records. A customer saying “I paid” is a report, not proof of settlement.

External payment information and an accepted outcome have different meanings. In the current workflow, reconciliation does not mean AEGVEN moved the funds. Do not infer a final outcome from a button click, delivery acknowledgement, or payment report.

Read the accepted detail

The obligation detail includes claims, allocations, allocated_minor, and remaining_minor. Display the returned exact strings and resource version. A claim stays a report even when independent evidence is later accepted; do not relabel it as proof.

Plan for retries and changes.

Mutating requests require an explicit 8–200 character printable Idempotency-Key. For a timeout or an ambiguous network outcome, retry the exact request with the same key and body. Generating a new key can create unintended duplicate work.

Actions that update an obligation also use its current expected_version. If the resource changed, retrieve it and reconsider the action before submitting a new operation.

Use GET /operations?idempotency_key=… or GET /operations/{id} to inspect accepted operation metadata. An empty result does not establish that an in-flight request failed. Replay the exact original request and key to recover an uncertain result; do not invent a new key to bypass uncertainty.

// Use the original key stored before the uncertain request.
const matches = await aegven.control.lookupOperation(originalKey);
// If you retained an operation ID:
// const matches = await aegven.control.operation(operationId);

// A match describes an accepted operation. It contains no hosted URL or secret.
// An empty items array does not prove an in-flight request was rejected.
// Recover with the original request body and key, then fetch current state.

Lookup never returns a stored hosted URL, request body, or secret. Retrieve the current obligation and active request with appropriate authorization when needed. Secrets shown once during credential or signing-secret creation cannot be recovered through lookup or replay.

Keep your system informed.

Arrange your event endpoint before creating obligations. Use an HTTPS endpoint and verify the Aegven-Signature header against the raw request bytes using the helper supplied with your SDK. Parse and apply the event only after verification.

• Persist processed event IDs so duplicate deliveries do not duplicate work.
• Match the obligation ID and namespaced source reference to the record you stored.
• Use resource versions to avoid applying an older snapshot over a newer one.
• Acknowledge a delivery only after durably accepting it for processing.
• Keep payment reports unverified until a later accepted outcome supports a change.

Event schemas and supported event names are supplied with your integration version. Do not assume delivery order or treat an event acknowledgement as completion of a downstream business operation.

import { verifyWebhook } from '@aegven/sdk/webhooks';

// rawBody: exact incoming bytes; signatureHeader: Aegven-Signature value.
const valid = await verifyWebhook(rawBody, signatureHeader, signingSecret);
if (!valid) {
  throw new Error('Reject this delivery before parsing or applying it.');
}
// Parse only after verification. Persist event-ID deduplication.
// integration.test has no obligation: acknowledge it without financial updates.
// For financial events, check the stored source mapping and resource version.
// Return 2xx only after durably accepting the delivery.

Distinguish test and financial events

integration.test has resource_type: webhook_endpoint and no obligation. Financial envelopes include an event ID, operation ID, resource ID, and obligation context. The current v1 contract retains invoice.* names and a compatibility invoice projection; do not infer a different event name from the resource name.

Configure and test the receiver before generating business events. Inspect delivery results and retest after changing endpoint configuration or signing secrets. See webhook setup and readiness.

Bring us your workflow.

Tell us what creates the obligation, which system holds the original record, who needs to interact, and what update your system needs to receive. Share a high-level overview first; we can arrange an appropriate channel for sensitive details.