Used by dispute enabled exchange partners to stage a settlement for connected clients.
This endpoint will:
- Authenticate the request by verifying the payload and signature provided.
- Create entities: a. Create the settlement entity b. Map provided settlement amounts to settlement transfer records for execution.
- Assign closed, unassigned disputes from prior settlements to this settlement a. Pull in any adjustedSettlementTransfers from said disputes. b. Update the settledInSettlementId on said disputes.
- Verify the relevant connection balances against liabilities based on provided settlementAmounts and assigned settlement transfers from disputes being assigned.
- Notify connection owners of a new settlement.
- Queue an event to finalize the settlement once the dispute window ends.
This endpoint is idempotent and can safely be called again with the same exact request body without worrying about creating multiple settlements.
Please note that provided settlement amounts should be based solely on new trading activity that was not included in the last settlement. Instructions from closed, unsettled disputes should not be included in the calculation of settlement instructions on the Settlement will be processed asynchronously once initiated, after dispute / top up window have elapsed.
- Error scenarios:
-
400: Invalid Request Error
-
Occurs when the request parameters are invalid or malformed.
-
Examples: Invalid format for settlement amounts, missing required fields, invalid signature.
-
401: Authentication Error or Incomplete Settlement
-
Occurs when the request is not authorized or cannot be completed immediately.
-
Examples: Caller is not a member of the enterprise, signature verification failed.
-
403: Permission Denied Error
-
Occurs when the authenticated partner doesn't have necessary permissions.
-
Examples: Enterprise does not have OES license, partner is inactive
-
409: Conflict Error
-
Occurs when the request conflicts with current state.
-
Examples: Settlement already exists with the same externalId and different properties.
-
422: Unprocessable Content
-
Occurs when the request is authenticated and permitted but is unable to be processed.
-
Examples: the liabilities for one or more connection exceed their allocated balance.
-
500: Internal Server Error or Incomplete Settlement
-
Occurs when there's an unexpected server error processing the request.
-
Examples: Database connection issues, settlement initiated but not completed due to transient errors.