{ "openapi": "3.1.0", "info": { "version": "2.0", "title": "MOJALOOP Central Settlements", "description": "Mojaloop API for Settlements." }, "paths": { "/health": { "get": { "deprecated": false, "description": "Gets the health of the service and sub-services (i.e. database).", "summary": "getHealth", "operationId": "getHealth", "tags": [ "getHealth" ], "responses": { "200": { "description": "A valid and health service." }, "502": { "description": "API is live, but error connecting to required sub-service." } } } }, "/settlementWindows/{id}": { "get": { "deprecated": false, "description": "Returns a Settlement Window by id.", "summary": "getSettlementWindowById", "operationId": "getSettlementWindowById", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "A valid settlement window id to be supplied in the query.\n", "schema": { "type": "integer" } } ], "tags": [ "getSettlementWindowById", "sampled" ], "responses": { "200": { "description": "A settlement window's data returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementWindow" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "deprecated": false, "description": "Closes requested window and opens a new one.", "summary": "closeSettlementWindow", "operationId": "closeSettlementWindow", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementWindowClosurePayload" } } }, "description": "A JSON object containing settlement window closure info.", "required": true }, "tags": [ "sampled", "closeSettlementWindow" ], "responses": { "200": { "description": "Settlement window closed and new window opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementWindow" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settlementWindows": { "get": { "deprecated": false, "description": "Returns Settlement Windows as per parameter(s).", "summary": "getSettlementWindowsByParams", "operationId": "getSettlementWindowsByParams", "parameters": [ { "in": "query", "name": "participantId", "description": "A valid participant Id to filter on.\n", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "state", "description": "A settlement window state to filter on.\n", "required": false, "schema": { "type": "string", "enum": [ "OPEN", "CLOSED", "PENDING_SETTLEMENT", "SETTLED", "ABORTED" ] } }, { "in": "query", "name": "fromDateTime", "description": "The start date for query (relates to central-ledger.settlementWindow.createdDate). Can be used together with `toDateTime'. eg 2017-07-20T17:32:28Z\n", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "toDateTime", "description": "The end date for query (relates to central-ledger.settlementWindow.createdDate). Can be used together with `fromDateTime'. eg 2017-07-21T17:32:28Z\n", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "currency", "description": "A valid currency to filter on.\n", "required": false, "schema": { "type": "string" } } ], "tags": [ "sampled", "getSettlementWindowsByParams" ], "responses": { "200": { "description": "Settlement window(s) returned by the filtering parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementWindows" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settlements": { "get": { "deprecated": false, "description": "Returns Settlements as per parameter(s).", "summary": "getSettlementsByParams", "operationId": "getSettlementsByParams", "parameters": [ { "in": "query", "name": "currency", "description": "A valid currency to filter on.\n", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "participantId", "description": "A valid participant Id to filter on.\n", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "settlementWindowId", "description": "A valid Settlement Window Id to filter on.\n", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "accountId", "description": "A valid Account Id to filter on.\n", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "state", "description": "A settlement state to filter on. \n", "required": false, "schema": { "type": "string", "enum": [ "PENDING_SETTLEMENT", "PS_TRANSFERS_RECORDED", "PS_TRANSFERS_RESERVED", "PS_TRANSFERS_COMMITTED", "SETTLING", "SETTLED", "ABORTED" ] } }, { "in": "query", "name": "fromDateTime", "description": "The start date for query (relates to central-ledger.settlement.createdDate). Can be used together with `toDateTime'. eg 2017-07-20T17:32:28Z\n", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "toDateTime", "description": "The end date for query (relates to central-ledger.settlement.createdDate). Can be used together with `fromDateTime'. eg 2017-07-21T17:32:28Z\n", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "fromSettlementWindowDateTime", "description": "The start date for query (relates to central-ledger.settlementWindow.createdDate). Can be used together with `toDateTime'. eg 2017-07-20T17:32:28Z\n", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "toSettlementWindowDateTime", "description": "The end date for query (relates to central-ledger.settlementWindow.createdDate). Can be used together with `fromDateTime'. eg 2017-07-21T17:32:28Z\n", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "tags": [ "sampled", "getSettlementsByParams" ], "responses": { "200": { "description": "Settlement window(s) returned by the filtering parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlements" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "deprecated": false, "description": "Triggers settlement creation. Returns settlement report.", "summary": "createSettlement", "operationId": "createSettlement", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementEventPayload" } } }, "description": "A JSON object containing settlement windows to be included.", "required": true }, "tags": [ "sampled", "createSettlement" ], "responses": { "200": { "description": "Created settlement with all windows and accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settlements/{id}": { "get": { "deprecated": false, "description": "Returns Settlement(s) as per parameters/filter criteria.", "summary": "getSettlementById", "operationId": "getSettlementById", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "A valid Settlement Id.\n", "schema": { "type": "integer" } } ], "tags": [ "sampled", "getSettlementById" ], "responses": { "200": { "description": "Settlement successfully returned by the filtering/Query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "deprecated": false, "description": "Acknowledgement of settlement by updating with Settlement Id.", "summary": "updateSettlementById", "operationId": "updateSettlementById", "parameters": [ { "in": "path", "name": "id", "description": "A valid Settlement Id.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementUpdateBySettlementIdPayload" } } }, "description": "A JSON object containing settlement update info.", "required": true }, "tags": [ "sampled", "updateSettlementById" ], "responses": { "200": { "description": "Settlements updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settlements/{sid}/participants/{pid}": { "get": { "deprecated": false, "description": "Returns Settlement(s) as per filter criteria.", "summary": "getSettlementBySettlementParticipant", "operationId": "getSettlementBySettlementParticipant", "parameters": [ { "in": "path", "name": "sid", "required": true, "description": "A valid Settlement Id.\n", "schema": { "type": "integer" } }, { "in": "path", "name": "pid", "required": true, "description": "A valid Participant Id.\n", "schema": { "type": "integer" } } ], "tags": [ "sampled", "getSettlementBySettlementParticipant" ], "responses": { "200": { "description": "Settlement, settlement windows and settlement accounts returned by the filtering parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "deprecated": false, "description": "Acknowledgement of settlement by updating the reason and state by SP.", "summary": "updateSettlementBySettlementParticipant", "operationId": "updateSettlementBySettlementParticipant", "parameters": [ { "in": "path", "name": "sid", "description": "A valid Settlement Id.", "required": true, "schema": { "type": "integer" } }, { "in": "path", "name": "pid", "description": "A valid Participant Id.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementUpdateBySettlementParticipantPayload" } } }, "description": "A JSON object containing settlement update info.", "required": true }, "tags": [ "sampled", "updateSettlementBySettlementParticipant" ], "responses": { "200": { "description": "Settlements updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settlements/{sid}/participants/{pid}/accounts/{aid}": { "get": { "deprecated": false, "description": "Returns Settlement(s) as per filter criteria.", "summary": "getSettlementBySettlementParticipantAccount", "operationId": "getSettlementBySettlementParticipantAccount", "parameters": [ { "in": "path", "name": "sid", "required": true, "description": "A valid Settlement Id.\n", "schema": { "type": "integer" } }, { "in": "path", "name": "pid", "required": true, "description": "A valid Participant Id.\n", "schema": { "type": "integer" } }, { "in": "path", "name": "aid", "required": true, "description": "A valid Account Id.\n", "schema": { "type": "integer" } } ], "tags": [ "sampled", "getSettlementBySettlementParticipantAccount" ], "responses": { "200": { "description": "Settlement, settlement windows and settlement accounts returned by the filtering parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "deprecated": false, "description": "Acknowledgement of settlement by updating the reason and state by SPA.", "summary": "updateSettlementBySettlementParticipantAccount", "operationId": "updateSettlementBySettlementParticipantAccount", "parameters": [ { "in": "path", "name": "sid", "description": "A valid Settlement Id.", "required": true, "schema": { "type": "integer" } }, { "in": "path", "name": "pid", "description": "A valid Participant Id.", "required": true, "schema": { "type": "integer" } }, { "in": "path", "name": "aid", "description": "A valid Account Id.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementUpdateBySettlementParticipantAccount" } } }, "description": "A JSON object containing settlement update info.", "required": true }, "tags": [ "sampled", "updateSettlementBySettlementParticipantAccount" ], "responses": { "200": { "description": "Settlements updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorisation information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Media Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "servers": [ { "url": "/v2" } ], "components": { "schemas": { "Account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account Id" }, "reason": { "description": "TBD", "type": "string" }, "state": { "type": "string", "example": "PENDING_SETTLEMENT" }, "netSettlementAmount": { "$ref": "#/components/schemas/netSettlementAmount" } } }, "SettlementUpdateBySettlementIdPayload": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "ABORTED", "INVALID" ] }, "reason": { "type": "string" }, "externalReference": { "type": "string" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementUpdateBySettlementIDOuterPayload" } } } }, "SettlementUpdateBySettlementIDOuterPayload": { "type": "object", "properties": { "id": { "type": "integer", "description": "Participant Id" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementUpdateBySettlementIdInnerPayload" } } } }, "SettlementUpdateBySettlementIdInnerPayload": { "type": "object", "properties": { "id": { "type": "integer", "description": "Participant Currency Id" }, "reason": { "type": "string", "example": "reason" }, "state": { "type": "string", "enum": [ "PENDING_SETTLEMENT", "PS_TRANSFERS_RECORDED", "PS_TRANSFERS_RESERVED", "PS_TRANSFERS_COMMITTED", "SETTLED" ], "example": "SETTLED" }, "externalReference": { "type": "string", "example": "external-reference-abc123" } } }, "SettlementUpdateBySettlementParticipantPayload": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementUpdateBySettlementIdInnerPayload" } } } }, "Accounts": { "type": "object", "properties": { "id": { "description": "Participant Currency Id", "type": "integer" }, "reason": { "description": "TBD", "type": "string" }, "state": { "type": "string", "example": "PENDING_SETTLEMENT" }, "netSettlementAmount": { "$ref": "#/components/schemas/netSettlementAmount" } } }, "SettlementWindowClosurePayload": { "type": "object", "properties": { "state": { "type": "string", "example": "CLOSED", "enum": [ "CLOSED" ] }, "reason": { "type": "string", "example": "string" } }, "required": [ "state", "reason" ] }, "SettlementUpdateBySettlementParticipantAccount": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "PENDING_SETTLEMENT", "PS_TRANSFERS_RECORDED", "PS_TRANSFERS_RESERVED", "PS_TRANSFERS_COMMITTED", "SETTLED" ], "example": "SETTLED" }, "reason": { "type": "string", "example": "string" }, "externalReference": { "type": "string", "example": "external-reference-abc123" } }, "required": [ "state", "reason" ] }, "SettlementEventPayload": { "type": "object", "properties": { "settlementModel": { "type": "string" }, "reason": { "type": "string" }, "settlementWindows": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/SettlementWindowId" } } }, "required": [ "settlementModel", "reason", "settlementWindows" ] }, "SettlementWindowId": { "type": "object", "properties": { "id": { "type": "integer" } }, "required": [ "id" ] }, "SettlementWindow": { "type": "object", "properties": { "id": { "type": "integer" }, "reason": { "type": "string" }, "state": { "type": "string" }, "createdDate": { "type": "string" }, "changedDate": { "type": "string" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementWindowContent" } } }, "required": [ "id", "state", "createdDate" ] }, "SettlementWindowContent": { "type": "object", "properties": { "id": { "type": "integer" }, "state": { "type": "string" }, "ledgerAccountType": { "type": "string" }, "currencyId": { "type": "string" }, "createdDate": { "type": "string" }, "changedDate": { "type": "string" }, "settlementId": { "type": "integer" } }, "required": [ "id", "state", "ledgerAccountType", "currencyId", "createdDate" ] }, "SettlementWindows": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementWindow" } }, "netSettlementAmount": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } } }, "Participant": { "type": "object", "properties": { "id": { "type": "integer" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Accounts" } } } }, "Settlements": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" } }, "Settlement": { "type": "object", "properties": { "id": { "type": "integer" }, "state": { "type": "string" }, "settlementWindows": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementWindows" } }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } } }, "Error": { "type": "object", "required": [ "errorInformation" ], "properties": { "errorInformation": { "type": "object", "properties": { "errorCode": { "type": "integer" }, "errorDescription": { "type": "string" }, "extensionList": { "type": "object", "properties": { "extension": { "type": "array", "items": { "$ref": "#/components/schemas/Extension" } } } } } } } }, "Extension": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } } } }