/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"
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
invoice_numberstringrequireddescriptionstringAdditional 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
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"
fixed_amount_minorstringPattern: ^[1-9][0-9]*$
percentage_basis_pointsintegerMinimum: 1
Maximum: 10000
amount_minorstringPattern: ^[1-9][0-9]*$
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 · dateAdditional properties are not accepted.
context_idsstring · uuid[]Show context_ids schema
Array of string · uuid
string · uuidAdditional 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/v1/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
invoiceobjectrequiredShow invoice schema
idstringrequiredorganization_idstringrequiredissuer_namestringrequiredreferencestringrequiredobligation_typestringrequiredAllowed: "invoice""payment_condition""contractual"
organization_rolestringrequiredAllowed: "creditor""debtor"
obligation_labelstringrequiredcreditor_namestringrequiredcreditor_emailstringrequireddebtor_namestringrequireddebtor_emailstringrequiredcondition_summarystringrequiredcondition_statusstringrequiredAllowed: "pending""satisfied""waived"
condition_satisfied_onstringrequiredconditionsobject[]requiredShow conditions schema
Array of object
idstring · uuidkeystringrequiredMax length: 120
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"
fixed_amount_minorstringPattern: ^[1-9][0-9]*$
percentage_basis_pointsintegerMinimum: 1
Maximum: 10000
amount_minorstringPattern: ^[1-9][0-9]*$
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 · dateAdditional 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.
external_namespacestringrequiredexternal_idstringrequiredinvoice_numberstringrequiredrecipient_namestringrequiredrecipient_emailstringrequireddescriptionstringrequiredamount_minorstringrequiredallocated_minorstringrequiredpayable_minorstringrequireddue_minorstringrequiredcurrencystringrequireddue_datestringrequiredexpected_payment_datestringrequiredreported_payment_datestringrequiredcreated_atstringrequiredupdated_atstringrequiredlink_expires_atstringrequiredstatusstringrequiredAllowed: "OBLIGATION_CAPTURED""PAYMENT_REQUESTED""PAYMENT_CLAIMED""PARTIALLY_RECONCILED""RECONCILED"
versionintegerrequiredMinimum: 1
acknowledgedbooleanrequiredlink_revokedbooleanrequiredAdditional properties are not accepted.
operation_idstringrequiredevent_typestringrequiredtracking_urlstringdocument_idstringobservation_idstringobligationobjectCanonical projection on new operations. Legacy persisted replays may omit it.
Show obligation schema
idstringrequiredorganization_idstringrequiredamount_minorstringrequiredallocated_minorstringrequiredpayable_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"
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
invoice_numberstringrequireddescriptionstringAdditional properties are not accepted.
creditorobjectrequiredShow creditor schema
namestringrequiredemailstringAdditional properties are not accepted.
referencestringUnique obligation correlation reference. Optional only for historical idempotent registration responses.
labelstringrequiredconditionobjectrequiredShow condition schema
summarystringstatusstringAllowed: "pending""satisfied""waived"
satisfied_onstringAdditional properties are not accepted.
conditionsobject[]requiredShow conditions schema
Array of object
idstring · uuidkeystringrequiredMax length: 120
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"
fixed_amount_minorstringPattern: ^[1-9][0-9]*$
percentage_basis_pointsintegerMinimum: 1
Maximum: 10000
amount_minorstringPattern: ^[1-9][0-9]*$
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 · dateAdditional 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.
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.