/obligationsRegister an obligation and atomically create its secure hosted payment request
Authentication
Organization API credential (Bearer token) or Customer user session.
Authorization: Bearer <your-server-side-api-key>Parameters
Idempotency-Keyheader · stringrequiredstringMin length: 8
Max length: 200
Request body required
application/json
obligation_typestringrequiredAllowed: "invoice""payment_condition""contractual""credit_note""adjustment""write_off"
organization_rolestringThe current organization's role. Omit for the backward-compatible creditor default.
Allowed: "creditor""debtor"
external_referenceobjectrequiredShow external_reference schema
namespacestringrequiredidstringrequiredAdditional properties are not accepted.
debtorobjectShow debtor schema
namestringrequiredemailstringAdditional properties are not accepted.
creditorobjectShow creditor schema
namestringrequiredemailstringAdditional properties are not accepted.
amount_minorstringrequiredPositive integer minor units; never a floating-point number.
Pattern: ^[1-9][0-9]*$
currencystringrequiredAllowed: "CAD""USD""EUR""GBP""JPY""AUD""CHF"
deadlinestring · daterequiredbusiness_contextobjectrequiredShow business_context schema
source_referencestringrequiredThe source system's namespaced document or workflow reference, independent of customer terminology.
descriptionstringAdditional properties are not accepted.
labelstringconditionobjectShow condition schema
summarystringstatusstringAllowed: "pending""satisfied""waived"
satisfied_onstringAdditional properties are not accepted.
conditionsobject[]Show conditions schema
Array of object
idstring · uuidkeystringrequiredMax length: 120
subject_refstringWhat the condition is about, for example order:408869. Obligations gated on the same event share one condition by using the same key and subject; omitting it makes the condition private to this obligation.
Max length: 250
labelstringrequiredMax length: 250
external_referenceobjectShow external_reference schema
namespacestringrequiredidstringrequiredAdditional properties are not accepted.
statusstringAllowed: "waiting""satisfied""waived"
satisfied_onstring · datesourcestringevidence_referencestringAdditional properties are not accepted.
payment_termsobject[]Show payment_terms schema
Array of object
idstring · uuidsequenceintegerrequiredMinimum: 1
labelstringMax length: 250
amount_typestringrequiredAllowed: "fixed""percentage""balance"
fixed_amount_minorstringPattern: ^[1-9][0-9]*$
percentage_basis_pointsintegerMinimum: 1
Maximum: 10000
amount_minorstringPattern: ^[1-9][0-9]*$
allocated_minorstringCash amount independently accepted for this stage.
credited_minorstringAmount discharged by accepted credit applications for this stage.
trigger_typestringrequiredAllowed: "immediately""specific_date""condition_satisfied"
trigger_datestring · datecondition_idstring · uuidcondition_keystringReferences a condition key during registration.
due_rulestringrequiredAllowed: "immediately""specific_date""days_after_trigger"
due_datestring · datedue_daysintegerMinimum: 1
Maximum: 36500
triggered_onstring · datepayable_onstring · dateinvoiced_onstring · dateWhen this stage was invoiced. Recorded, not derived: only the system that raised the invoice knows it happened.
invoice_external_refstringMax length: 250
billing_statestringThe authoritative lifecycle projected by the Rust core for an explicit effective date and persisted with the stage.
Allowed: "waiting""billable""invoiced""partially_satisfied""satisfied"
reported_minorstringpending_minorstringremaining_minorstringreportable_majorstringstatus_labelstringpercentage_labelstringcondition_labelstringcondition_statusstringactivebooleancan_reportbooleanrecently_payablebooleanBecame payable in the last 14 days after a date or condition.
line_item_idstringThe line item this stage bills. Absent when the stage bills the line items that have no stages of their own, or the whole obligation when it has none. A percentage stage is a percentage of what it bills.
completebooleanBackend coverage projection.
progress_labelstringBackend presentation of the payment stage state.
kindstringAn ordinary stage, or retention held back until its release trigger.
Allowed: "stage""retention"
reportable_minorstringWhat a payer can still report for this stage after other unconfirmed reports.
paid_minorstringConfirmed payments and accepted credits already applied to this stage.
remaining_majorstringhas_pendingbooleanWhether payer reports awaiting confirmation already claim part of this stage.
Additional properties are not accepted.
context_idsstring · uuid[]Show context_ids schema
Array of string · uuid
string · uuidschedule_template_keystringRegister against a named reusable schedule instead of spelling out payment_terms. Providing both is refused.
Max length: 120
condition_subject_refstringWhat the template's conditions are about. Obligations naming the same subject share one event.
Max length: 250
tax_treatmentstringStructural, not jurisdictional. not_recorded means the source stated no tax.
Allowed: "taxable""exempt""zero_rated""reverse_charge""not_recorded"
net_amount_minorstringAmount excluding tax. Empty when tax_treatment is not_recorded. amount_minor stays tax-inclusive.
taxesobject[]Show taxes schema
Array of object
codestringrequiredThe source system's own tax code.
Min length: 1
Max length: 60
labelstringrequiredWhat the organization calls it: GST, PST, VAT, State Tax.
Min length: 1
Max length: 120
jurisdictionstringMax length: 60
rate_basis_pointsintegerMinimum: 0
Maximum: 1000000
basis_minorstringrequiredThe amount this component was charged on.
amount_minorstringrequiredExact minor units. May be "0" for a listed zero-rated component.
applies_tostringWhat this tax was charged on: the whole obligation, or only the line items or payment stages listed in parts. Empty when the source did not say.
Allowed: """obligation""line_items""payment_terms"
partsobject[]How this tax divides over the line items or payment stages it was charged on. Omitted when it was recorded against the whole amount only. The parts must add up to basis_minor and amount_minor.
Show parts schema
Array of object
line_item_idstringThe id of a line item on this obligation.
payment_term_idstringThe id of a payment stage on this obligation.
basis_minorstringrequiredThis part's amount before tax, in exact minor units.
Pattern: ^[1-9][0-9]*$
amount_minorstringrequiredThe tax charged on this part, in exact minor units.
Pattern: ^(0|[1-9][0-9]*)$
Additional properties are not accepted.
line_itemsobject[]Deliverable parts of what was ordered. Omit for an undivided obligation.
Show line_items schema
Array of object
idstringStable identifier for this part. AEGVEN assigns one when omitted.
sequenceintegerMinimum: 1
amount_minorstringrequiredExact minor-unit value of this part.
labelstringMax length: 250
descriptionstringMax length: 2000
expected_onstring · dateOptional planned delivery date, no later than the obligation's final deadline.
quantitystringOptional quantity as an exact decimal, such as "12" or "2.5".
Pattern: ^[0-9]{1,15}(\.[0-9]{1,6})?$
unitstringOptional unit of the quantity, such as "pcs", "t" or "m". Requires quantity.
Max length: 20
unit_pricestringOptional price per unit in major units as an exact decimal, such as "850.00" or "0.125". Requires quantity. Informational: amount_minor is what is owed.
Pattern: ^[0-9]{1,15}(\.[0-9]{1,6})?$
external_namespacestringexternal_idstringAdditional properties are not accepted.
Additional properties are not accepted.
Example request
Replace the sample source record. Reuse the same body and idempotency key when retrying this registration.
curl "https://app.aegven.com/api/v2/obligations" \
--header "Authorization: Bearer $AEGVEN_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: register-source-1042" \
--data '{
"obligation_type": "invoice",
"external_reference": {
"namespace": "your-system",
"id": "source-1042"
},
"debtor": {
"name": "Recipient company",
"email": "accounts@example.com"
},
"amount_minor": "125000",
"currency": "CAD",
"deadline": "2027-12-31",
"business_context": {
"invoice_number": "INV-1042",
"description": "Services"
}
}'Responses
201Success
application/json
operation_idstringrequiredevent_typestringrequiredtracking_urlstringdocument_idstringobservation_idstringobligationobjectrequiredThe obligation as accepted, including its resolved display terminology.
Show obligation schema
idstringrequiredorganization_idstringrequiredamount_minorstringrequiredallocated_minorstringrequiredcredited_minorstringrequiredAmount discharged by accepted credit applications; cash allocations remain separate.
payable_minorstringrequiredGross obligation amount activated by payment terms. Rust financial-core projection.
due_minorstringrequiredGross payable amount whose calculated due date has arrived. Rust financial-core projection.
currencystringrequiredexpected_payment_datestringrequiredreported_payment_datestringrequiredcreated_atstringrequiredupdated_atstringrequiredstatusstringrequiredAllowed: "OBLIGATION_CAPTURED""PAYMENT_REQUESTED""PAYMENT_CLAIMED""PARTIALLY_RECONCILED""RECONCILED"
versionintegerrequiredMinimum: 1
acknowledgedbooleanrequiredobligation_typestringrequiredAllowed: "invoice""payment_condition""contractual""credit_note""adjustment""write_off"
organization_rolestringrequiredAllowed: "creditor""debtor"
external_referenceobjectrequiredShow external_reference schema
namespacestringrequiredidstringrequiredAdditional properties are not accepted.
debtorobjectrequiredShow debtor schema
namestringrequiredemailstringAdditional properties are not accepted.
deadlinestring · daterequiredbusiness_contextobjectrequiredShow business_context schema
source_referencestringrequiredThe source system's namespaced document or workflow reference, independent of customer terminology.
descriptionstringAdditional properties are not accepted.
creditorobjectrequiredShow creditor schema
namestringrequiredemailstringAdditional properties are not accepted.
referencestringrequiredUnique obligation correlation reference. Optional only for historical idempotent registration responses.
payment_referencestringrequiredShort code the payer includes in the bank transfer. The last character is a check character.
Pattern: ^PAY-[2-9A-HJ-NP-Z]{7}$
labelstringrequiredconditionobjectrequiredShow condition schema
summarystringstatusstringAllowed: "pending""satisfied""waived"
satisfied_onstringAdditional properties are not accepted.
conditionsobject[]requiredShow conditions schema
Array of object
idstring · uuidkeystringrequiredMax length: 120
subject_refstringWhat the condition is about, for example order:408869. Obligations gated on the same event share one condition by using the same key and subject; omitting it makes the condition private to this obligation.
Max length: 250
labelstringrequiredMax length: 250
external_referenceobjectShow external_reference schema
namespacestringrequiredidstringrequiredAdditional properties are not accepted.
statusstringAllowed: "waiting""satisfied""waived"
satisfied_onstring · datesourcestringevidence_referencestringAdditional properties are not accepted.
payment_termsobject[]requiredShow payment_terms schema
Array of object
idstring · uuidsequenceintegerrequiredMinimum: 1
labelstringMax length: 250
amount_typestringrequiredAllowed: "fixed""percentage""balance"
fixed_amount_minorstringPattern: ^[1-9][0-9]*$
percentage_basis_pointsintegerMinimum: 1
Maximum: 10000
amount_minorstringPattern: ^[1-9][0-9]*$
allocated_minorstringCash amount independently accepted for this stage.
credited_minorstringAmount discharged by accepted credit applications for this stage.
trigger_typestringrequiredAllowed: "immediately""specific_date""condition_satisfied"
trigger_datestring · datecondition_idstring · uuidcondition_keystringReferences a condition key during registration.
due_rulestringrequiredAllowed: "immediately""specific_date""days_after_trigger"
due_datestring · datedue_daysintegerMinimum: 1
Maximum: 36500
triggered_onstring · datepayable_onstring · dateinvoiced_onstring · dateWhen this stage was invoiced. Recorded, not derived: only the system that raised the invoice knows it happened.
invoice_external_refstringMax length: 250
billing_statestringThe authoritative lifecycle projected by the Rust core for an explicit effective date and persisted with the stage.
Allowed: "waiting""billable""invoiced""partially_satisfied""satisfied"
reported_minorstringpending_minorstringremaining_minorstringreportable_majorstringstatus_labelstringpercentage_labelstringcondition_labelstringcondition_statusstringactivebooleancan_reportbooleanrecently_payablebooleanBecame payable in the last 14 days after a date or condition.
line_item_idstringThe line item this stage bills. Absent when the stage bills the line items that have no stages of their own, or the whole obligation when it has none. A percentage stage is a percentage of what it bills.
completebooleanBackend coverage projection.
progress_labelstringBackend presentation of the payment stage state.
kindstringAn ordinary stage, or retention held back until its release trigger.
Allowed: "stage""retention"
reportable_minorstringWhat a payer can still report for this stage after other unconfirmed reports.
paid_minorstringConfirmed payments and accepted credits already applied to this stage.
remaining_majorstringhas_pendingbooleanWhether payer reports awaiting confirmation already claim part of this stage.
Additional properties are not accepted.
contextsobject[]requiredShow contexts schema
Array of object
idstring · uuidrequiredtypestringrequiredAllowed: "company""project""order""invoice""external_object"
kindstringrequiredAllowed: "company""group""reference"
type_labelstringrequirednamestringrequiredreferencestringrequiredrelationship_typestringrequiredattributed_minorstringPattern: ^[1-9][0-9]*$
currencystringAdditional properties are not accepted.
type_labelstringrequiredWhat this organization calls this obligation type, for example Invoice, Bill or Contract.
type_label_pluralstringrequiredtax_treatmentstringrequiredStructural, not jurisdictional. not_recorded means the source stated no tax.
Allowed: "taxable""exempt""zero_rated""reverse_charge""not_recorded"
net_amount_minorstringAmount excluding tax. Empty when tax_treatment is not_recorded. amount_minor stays tax-inclusive.
taxesobject[]requiredShow taxes schema
Array of object
codestringrequiredThe source system's own tax code.
Min length: 1
Max length: 60
labelstringrequiredWhat the organization calls it: GST, PST, VAT, State Tax.
Min length: 1
Max length: 120
jurisdictionstringMax length: 60
rate_basis_pointsintegerMinimum: 0
Maximum: 1000000
basis_minorstringrequiredThe amount this component was charged on.
amount_minorstringrequiredExact minor units. May be "0" for a listed zero-rated component.
applies_tostringWhat this tax was charged on: the whole obligation, or only the line items or payment stages listed in parts. Empty when the source did not say.
Allowed: """obligation""line_items""payment_terms"
partsobject[]How this tax divides over the line items or payment stages it was charged on. Omitted when it was recorded against the whole amount only. The parts must add up to basis_minor and amount_minor.
Show parts schema
Array of object
line_item_idstringThe id of a line item on this obligation.
payment_term_idstringThe id of a payment stage on this obligation.
basis_minorstringrequiredThis part's amount before tax, in exact minor units.
Pattern: ^[1-9][0-9]*$
amount_minorstringrequiredThe tax charged on this part, in exact minor units.
Pattern: ^(0|[1-9][0-9]*)$
Additional properties are not accepted.
line_itemsobject[]Show line_items schema
Array of object
idstringStable identifier for this part. AEGVEN assigns one when omitted.
sequenceintegerMinimum: 1
amount_minorstringrequiredExact minor-unit value of this part.
labelstringMax length: 250
descriptionstringMax length: 2000
expected_onstring · dateOptional planned delivery date, no later than the obligation's final deadline.
quantitystringOptional quantity as an exact decimal, such as "12" or "2.5".
Pattern: ^[0-9]{1,15}(\.[0-9]{1,6})?$
unitstringOptional unit of the quantity, such as "pcs", "t" or "m". Requires quantity.
Max length: 20
unit_pricestringOptional price per unit in major units as an exact decimal, such as "850.00" or "0.125". Requires quantity. Informational: amount_minor is what is owed.
Pattern: ^[0-9]{1,15}(\.[0-9]{1,6})?$
external_namespacestringexternal_idstringAdditional properties are not accepted.
amendmentsobject[]Show amendments schema
Array of object
idstringrequiredsequenceintegerrequiredMinimum: 1
effective_onstring · daterequiredprevious_amount_minorstringrequiredamount_minorstringrequiredeffectstringrequiredDerived by AEGVEN from the two amounts.
Allowed: "increase""decrease"
labelstringMax length: 250
reasonstringMax length: 2000
external_namespacestringexternal_idstringAdditional properties are not accepted.
original_amount_minorstringThe value this obligation was accepted at, before any amendment.
condition_statusstringMirror of condition.status, kept for older integrations. Prefer condition.status.
condition_satisfied_onstringMirror of condition.satisfied_on (a date, or empty), kept for older integrations. Prefer condition.satisfied_on.
issuer_namestringThe issuing organization's display name.
link_expires_atstring · date-timeWhen the current secure payer link expires.
link_revokedbooleanWhether the issuer revoked the secure payer link.
Additional properties are not accepted.
payment_requestobjectShow payment_request schema
idstringrequiredobligation_idstringrequiredhosted_urlstringrequiredBearer capability URL for an unregistered recipient; insert into your outgoing message. Do not log.
expires_atstring · date-timerequiredAdditional properties are not accepted.
Additional properties are not accepted.
defaultStable API error
application/json
errorobjectrequiredShow error schema
codestringrequiredStable error code. 403 insufficient_permission means the signed-in role lacks the endpoint permission. 403 insufficient_scope means the API key lacks the endpoint scope.
messagestringrequiredAdditional properties are not accepted.
Additional properties are not accepted.