/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"
external_referenceobjectrequiredShow external_reference schema
namespacestringrequiredidstringrequiredAdditional properties are not accepted.
debtorobjectrequiredShow debtor schema
namestringrequiredemailstring · emailrequiredAdditional 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.
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/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_namestringrequiredreferencestringrequiredexternal_namespacestringrequiredexternal_idstringrequiredinvoice_numberstringrequiredrecipient_namestringrequiredrecipient_emailstringrequireddescriptionstringrequiredamount_minorstringrequiredallocated_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_minorstringrequiredcurrencystringrequiredexpected_payment_datestringrequiredreported_payment_datestringrequiredcreated_atstringrequiredupdated_atstringrequiredstatusstringrequiredAllowed: "OBLIGATION_CAPTURED""PAYMENT_REQUESTED""PAYMENT_CLAIMED""PARTIALLY_RECONCILED""RECONCILED"
versionintegerrequiredMinimum: 1
acknowledgedbooleanrequiredobligation_typestringrequiredAllowed: "invoice"
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.
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
codestringrequiredmessagestringrequiredAdditional properties are not accepted.
Additional properties are not accepted.