{ "openapi": "3.1.0", "info": { "title": "Nexus FXP API", "description": "Combined Nexus API for FX Providers (FXPs). Includes rate management (exchange rates, tier-based improvements, PSP relationships) and completed payment query. All API endpoints require mutual TLS and OAuth 2.0 bearer authentication. The client certificate is presented and validated during the TLS handshake at the Akamai edge; the certificate is not supplied as an HTTP header.", "contact": { "name": "Nexus API Support", "url": "https://developer.nexus.example/support", "email": "api-support@nexus.example" }, "version": "v1" }, "servers": [ { "url": "http://localhost:8080", "description": "Generated server url" } ], "tags": [ { "name": "FXP Rates", "description": "Manage FXP exchange rates. Rates are one-directional, identified by source and destination IA account references, and remain live until replaced by a new rate for the same account pair or voluntarily withdrawn. Nexus does not impose time-based expiry on rates; isExpired marks superseded or voluntarily withdrawn records only." }, { "name": "FXP Tier Improvements", "description": "Manage tier-based rate improvements per source currency. Tiers apply a basis-point improvement for transactions meeting or exceeding a threshold amount. Nexus selects the tier with the greatest qualifying threshold and combines it with any applicable PSP-based improvement before applying the total to the base rate." }, { "name": "FXP PSP Relationships", "description": "Manage FXP–PSP business relationships and optional PSP-based rate improvements expressed in basis points. A relationship must exist for the FXP to be eligible to provide quotes to a PSP. The PSP-based improvement applies to all currencies for that PSP." }, { "name": "FXP Payment Query", "description": "Query completed payment records by UETR or date range. Results are scoped to payments where the authenticated FXP was the FX provider." } ], "paths": { "/v1/rates": { "get": { "tags": [ "FXP Rates" ], "summary": "List FXP rates", "description": "Returns the authenticated FXP's current (live, non-superseded) rates, optionally filtered by currency pair and IPSs. When includeExpired=true, historical rates from the last 13 months are included and limit is required (maximum 100). Nexus does not impose time-based expiry on rates; isExpired marks superseded or voluntarily withdrawn records only.", "operationId": "listRates", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "sourceCurrency", "in": "query", "description": "ISO 4217 3-letter source currency code (uppercase). Filters to rates for this source currency.", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]{3}$" }, "example": "EUR" }, { "name": "destinationCurrency", "in": "query", "description": "ISO 4217 3-letter destination currency code (uppercase). Filters to rates for this destination currency.", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]{3}$" }, "example": "AUD" }, { "name": "sourceIps", "in": "query", "description": "Source IPS identifier. Filters to rates where the FXP receives source currency via this IPS.", "required": false, "schema": { "type": "string" }, "example": "EURTIPS" }, { "name": "destinationIps", "in": "query", "description": "Destination IPS identifier. Filters to rates where the FXP pays out destination currency via this IPS.", "required": false, "schema": { "type": "string" }, "example": "AUSNPP" }, { "name": "includeExpired", "in": "query", "description": "If true, include historical (withdrawn or superseded) rates from the last 13 months. Default: false. When true, limit is required.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "limit", "in": "query", "description": "Max items to return. Default 50. Maximum 100. Required when includeExpired=true.", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Pagination cursor; omit for first page. This endpoint is limited to a maximum of 100 records.", "required": false, "schema": { "type": "string" }, "example": "eyJwayI6Li4ufQ==" } ], "responses": { "200": { "description": "Rates retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatesPageResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, POST" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "rates.read" ] } ] }, "post": { "tags": [ "FXP Rates" ], "summary": "Create or replace a rate", "description": "Creates a new rate record identified by the FXP's source and destination IA account references. Nexus resolves source currency, destination currency, source IPS, and destination IPS from the IA account records registered for the submitting FXP. If a live rate already exists for the same (sourceIAAccount, destinationIAAccount) pair, Nexus marks the prior record as superseded (isExpired=true — a historical marker, not time-based expiry) and creates the new rate.", "operationId": "createRate", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" } ], "requestBody": { "description": "Rate creation request.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateRequest" }, "examples": { "createEurToAud": { "summary": "Create an EUR to AUD rate", "value": { "sourceIAAccount": { "addressTypeCode": "IBAN", "fields": { "iban": "DE89370400440532013000" } }, "destinationIAAccount": { "addressTypeCode": "AU-BSB", "fields": { "bsb": "062-000", "accountNumber": "12345678" } }, "rate": 1.5019 } } } } } }, "responses": { "200": { "description": "Rate created successfully. Returns the new rate record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more request fields are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more request fields are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, POST" } } }, "409": { "description": "Conflict. The rate could not be created due to a conflicting state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "RATE_CONFLICT": { "description": "Update rejected due to a conflicting state (e.g., invalid effective time ordering).", "value": { "statusCode": "RJCT", "reasonCode": "BE023", "name": "RATE_CONFLICT", "description": "The rate could not be created due to a conflicting state." } } } } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "rates.write" ] } ] } }, "/v1/rates/count": { "get": { "tags": [ "FXP Rates" ], "summary": "Get rate count", "description": "Returns the count of rates for the authenticated FXP. includeExpired controls whether historical (withdrawn or superseded) rates are included in the count.", "operationId": "getRateCount", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "includeExpired", "in": "query", "description": "If true, include historical (withdrawn or superseded) rates in the count. Default: false.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "200": { "description": "Count retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" }, "example": { "count": 2 } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "rates.read" ] } ] } }, "/v1/rates/{id}": { "delete": { "tags": [ "FXP Rates" ], "summary": "Withdraw a rate", "description": "Voluntarily withdraws a rate by id so it is no longer used to generate quotes for PSPs. Sets isExpired=true and records expiryDateTime as a historical marker — not a time-based expiry. Already-issued quotes remain honoured for the NQVT window (600 seconds). Returns the withdrawn rate record.", "operationId": "withdrawRate", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "id", "in": "path", "description": "UUID of the rate record to withdraw.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "9929ea23-f29c-4053-b54a-5bf7a1bb348e" } ], "responses": { "200": { "description": "Rate withdrawn successfully. Returns the withdrawn rate record with isExpired=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "404": { "description": "Rate Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "RATE_NOT_FOUND": { "description": "No rate was found for the specified id for this FXP.", "value": { "statusCode": "RJCT", "reasonCode": "BE022", "name": "RATE_NOT_FOUND", "description": "No rate was found for the specified id for this FXP." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "DELETE" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "rates.write" ] } ] } }, "/v1/tiers": { "get": { "tags": [ "FXP Tier Improvements" ], "summary": "List FXP tiers", "description": "Returns the authenticated FXP's configured tiers, optionally filtered by source currency. When includeExpired=true, historical tiers from the last 13 months are included and limit is required (maximum 100). Tiers remain live until replaced for the same (fxpId, sourceCurrency, threshold) or voluntarily withdrawn.", "operationId": "listTiers", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "sourceCurrency", "in": "query", "description": "ISO 4217 3-letter source currency code (uppercase). Filters results to tiers for this source currency.", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]{3}$" }, "example": "EUR" }, { "name": "includeExpired", "in": "query", "description": "If true, include expired (withdrawn or superseded) tiers from the last 13 months. Default: false. When true, limit is required.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "limit", "in": "query", "description": "Max items to return. Default 50. Maximum 100. Required when includeExpired=true.", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Pagination cursor; omit for first page. This endpoint is limited to a maximum of 100 records.", "required": false, "schema": { "type": "string" }, "example": "eyJwayI6Li4ufQ==" } ], "responses": { "200": { "description": "Tiers retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TiersPageResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, POST" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "tiers.read" ] } ] }, "post": { "tags": [ "FXP Tier Improvements" ], "summary": "Create or replace a tier", "description": "Creates a new tier record for the given source currency and threshold. If a live tier already exists for the same fxpId, sourceCurrency, and threshold, Nexus marks the prior record as superseded and creates the new tier. Tiers are PSP-agnostic and apply based on transaction size in the source currency.", "operationId": "createTier", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" } ], "requestBody": { "description": "Tier creation request.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierRequest" }, "examples": { "createEurTier": { "summary": "Create a EUR tier at 50,000 threshold", "value": { "sourceCurrency": "EUR", "threshold": 50000, "improvementBps": 100 } } } } } }, "responses": { "200": { "description": "Tier created successfully. Returns the new tier record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more request fields are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more request fields are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, POST" } } }, "409": { "description": "Conflict. The tier could not be created due to a conflicting state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "TIER_CONFLICT": { "description": "Conflicting state (e.g., duplicate tier for same currency and threshold, or threshold ordering violation).", "value": { "statusCode": "RJCT", "reasonCode": "BE025", "name": "TIER_CONFLICT", "description": "The tier could not be created due to a conflicting state." } } } } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "tiers.write" ] } ] } }, "/v1/tiers/count": { "get": { "tags": [ "FXP Tier Improvements" ], "summary": "Get tier count", "description": "Returns the count of tiers for the authenticated FXP. includeExpired controls whether expired (withdrawn or superseded) tiers are included in the count.", "operationId": "getTierCount", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "includeExpired", "in": "query", "description": "If true, include expired (withdrawn or superseded) tiers in the count. Default: false.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "200": { "description": "Count retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" }, "example": { "count": 3 } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "tiers.read" ] } ] } }, "/v1/tiers/{tierId}": { "get": { "tags": [ "FXP Tier Improvements" ], "summary": "Get a single tier", "description": "Returns a single tier record by tierId for the authenticated FXP.", "operationId": "getTier", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "tierId", "in": "path", "description": "UUID of the tier record.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87" } ], "responses": { "200": { "description": "Tier retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "404": { "description": "Tier Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "TIER_NOT_FOUND": { "description": "No tier was found for the specified tierId for this FXP.", "value": { "statusCode": "RJCT", "reasonCode": "BE024", "name": "TIER_NOT_FOUND", "description": "No tier was found for the specified tierId for this FXP." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, DELETE" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "tiers.read" ] } ] }, "delete": { "tags": [ "FXP Tier Improvements" ], "summary": "Withdraw a tier", "description": "Voluntarily withdraws a tier so it no longer applies to quote generation. Sets isExpired=true and records expiryDateTime as a historical marker. Returns the withdrawn tier record.", "operationId": "withdrawTier", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "tierId", "in": "path", "description": "UUID of the tier record to withdraw.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87" } ], "responses": { "200": { "description": "Tier withdrawn successfully. Returns the withdrawn tier record with isExpired=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "404": { "description": "Tier Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "TIER_NOT_FOUND": { "description": "No tier was found for the specified tierId for this FXP.", "value": { "statusCode": "RJCT", "reasonCode": "BE024", "name": "TIER_NOT_FOUND", "description": "No tier was found for the specified tierId for this FXP." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, DELETE" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "tiers.write" ] } ] } }, "/v1/relationships/fxps/{fxpId}/psps": { "get": { "tags": [ "FXP PSP Relationships" ], "summary": "List PSP relationships for an FXP", "description": "Returns all PSP relationships for the given FXP, including the configured PSP-based improvement (if any) for each PSP. Results are cursor-paginated.", "operationId": "listFxpPspRelationships", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "fxpId", "in": "path", "description": "Nexus internal identifier for the FXP.", "required": true, "schema": { "type": "string" }, "example": "FXP-A" }, { "name": "limit", "in": "query", "description": "Max items to return. Default 50.", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Pagination cursor; omit for first page.", "required": false, "schema": { "type": "string" }, "example": "eyJwayI6Li4ufQ==" } ], "responses": { "200": { "description": "Relationships retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipsPageResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "404": { "description": "FXP Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "RELATIONSHIP_NOT_FOUND": { "description": "No relationships were found for the specified FXP.", "value": { "statusCode": "RJCT", "reasonCode": "BE026", "name": "RELATIONSHIP_NOT_FOUND", "description": "No relationships were found for the specified FXP." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "relationships.read" ] } ] } }, "/v1/relationships/fxps/{fxpId}/psps/{pspId}": { "get": { "tags": [ "FXP PSP Relationships" ], "summary": "Get a single FXP–PSP relationship", "description": "Returns a single FXP–PSP relationship, including the PSP-based improvement (if configured).", "operationId": "getFxpPspRelationship", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "fxpId", "in": "path", "description": "Nexus internal identifier for the FXP.", "required": true, "schema": { "type": "string" }, "example": "FXP-A" }, { "name": "pspId", "in": "path", "description": "Nexus internal identifier for the PSP.", "required": true, "schema": { "type": "string" }, "example": "PSP-C" } ], "responses": { "200": { "description": "Relationship retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "404": { "description": "Relationship Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "RELATIONSHIP_NOT_FOUND": { "description": "No relationship was found for the specified FXP and PSP.", "value": { "statusCode": "RJCT", "reasonCode": "BE026", "name": "RELATIONSHIP_NOT_FOUND", "description": "No relationship was found for the specified FXP and PSP." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, POST, PUT, DELETE" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "relationships.read" ] } ] }, "post": { "tags": [ "FXP PSP Relationships" ], "summary": "Create an FXP–PSP relationship", "description": "Creates an FXP–PSP relationship, recording that the FXP is eligible to provide FX quotes to the specified PSP. Optionally configures a PSP-based improvement in basis points. The improvement applies to all currencies for this PSP.", "operationId": "createFxpPspRelationship", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "fxpId", "in": "path", "description": "Nexus internal identifier for the FXP.", "required": true, "schema": { "type": "string" }, "example": "FXP-A" }, { "name": "pspId", "in": "path", "description": "Nexus internal identifier for the PSP.", "required": true, "schema": { "type": "string" }, "example": "PSP-C" } ], "requestBody": { "description": "Relationship creation request. pspImprovementBps is optional; omit to apply the FXP's base rate to this PSP.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipRequest" }, "examples": { "withImprovement": { "summary": "Create relationship with 25 bps improvement", "value": { "pspImprovementBps": 25 } }, "withoutImprovement": { "summary": "Create relationship without improvement (base rate applies)", "value": {} } } } } }, "responses": { "200": { "description": "Relationship created successfully. Returns the new relationship record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, POST, PUT, DELETE" } } }, "409": { "description": "Conflict. A relationship already exists for this FXP and PSP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "RELATIONSHIP_CONFLICT": { "description": "A relationship already exists for the specified FXP and PSP. Use PUT to update it.", "value": { "statusCode": "RJCT", "reasonCode": "BE027", "name": "RELATIONSHIP_CONFLICT", "description": "A relationship already exists for the specified FXP and PSP. Use PUT to update it." } } } } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "relationships.write" ] } ] }, "put": { "tags": [ "FXP PSP Relationships" ], "summary": "Update an FXP–PSP relationship", "description": "Updates an existing FXP–PSP relationship. Replaces the configured PSP-based improvement in basis points. Set pspImprovementBps to 0 to remove the improvement so the FXP's base rate applies.", "operationId": "updateFxpPspRelationship", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "fxpId", "in": "path", "description": "Nexus internal identifier for the FXP.", "required": true, "schema": { "type": "string" }, "example": "FXP-A" }, { "name": "pspId", "in": "path", "description": "Nexus internal identifier for the PSP.", "required": true, "schema": { "type": "string" }, "example": "PSP-C" } ], "requestBody": { "description": "Relationship update request.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipUpdateRequest" }, "examples": { "updateImprovement": { "summary": "Update improvement to 50 bps", "value": { "pspImprovementBps": 50 } }, "removeImprovement": { "summary": "Remove improvement (base rate applies)", "value": { "pspImprovementBps": 0 } } } } } }, "responses": { "200": { "description": "Relationship updated successfully. Returns the updated relationship record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "404": { "description": "Relationship Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "RELATIONSHIP_NOT_FOUND": { "description": "No relationship was found for the specified FXP and PSP.", "value": { "statusCode": "RJCT", "reasonCode": "BE026", "name": "RELATIONSHIP_NOT_FOUND", "description": "No relationship was found for the specified FXP and PSP." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, POST, PUT, DELETE" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "relationships.write" ] } ] }, "delete": { "tags": [ "FXP PSP Relationships" ], "summary": "Delete an FXP–PSP relationship", "description": "Deletes the FXP–PSP relationship so the FXP is no longer eligible to provide quotes to that PSP. Returns 204 No Content on success.", "operationId": "deleteFxpPspRelationship", "parameters": [ { "name": "fxpId", "in": "path", "description": "Nexus internal identifier for the FXP.", "required": true, "schema": { "type": "string" }, "example": "FXP-A" }, { "name": "pspId", "in": "path", "description": "Nexus internal identifier for the PSP.", "required": true, "schema": { "type": "string" }, "example": "PSP-C" } ], "responses": { "204": { "description": "Relationship deleted successfully. No content returned." }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more path parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "404": { "description": "Relationship Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "RELATIONSHIP_NOT_FOUND": { "description": "No relationship was found for the specified FXP and PSP.", "value": { "statusCode": "RJCT", "reasonCode": "BE026", "name": "RELATIONSHIP_NOT_FOUND", "description": "No relationship was found for the specified FXP and PSP." } } } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET, POST, PUT, DELETE" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "relationships.write" ] } ] } }, "/v1/fxp/payments": { "get": { "tags": [ "FXP Payment Query" ], "summary": "Query FXP completed payments", "description": "Retrieve completed payment records for the authenticated FXP.\n\nSupported query modes:\n\n1. Single payment:\n Provide `uetr` only.\n\n2. Date range:\n Provide `fromDate` and `toDate`.\n `cursor` and `limit` are optional.\n", "operationId": "queryFxpPayments", "parameters": [ { "name": "Accept", "in": "header", "description": "application/json", "required": true, "schema": { "type": "string", "default": "application/json" }, "example": "application/json" }, { "name": "uetr", "in": "query", "description": "UETR of the payment to retrieve. Required for single-payment mode. UUID v4.", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "example": "d302cc08-323b-4ac6-897e-579a9abe0c88" }, { "name": "fromDate", "in": "query", "description": "Start of query window (inclusive). Required for date-range mode. ISO 8601 UTC date-time.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-03-01T00:00:00Z" }, { "name": "toDate", "in": "query", "description": "End of query window (exclusive). Required for date-range mode. ISO 8601 UTC date-time.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-03-31T00:00:00Z" }, { "name": "cursor", "in": "query", "description": "Pagination cursor; omit for first page. Optional. Opaque token.", "required": false, "schema": { "type": "string" }, "example": "eyJwayI6Li4ufQ==" }, { "name": "limit", "in": "query", "description": "Max records per page. Optional. 1-100, default 50.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 }, "example": 50 } ], "responses": { "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INVALID_REQUEST": { "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema.", "value": { "statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "One or more query parameters are missing, malformed, or do not conform to the expected schema." } } } } } }, "401": { "description": "Authentication Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "AUTH_TOKEN_MISSING": { "description": "The Authorization header is absent or does not contain a Bearer token.", "value": { "statusCode": "RJCT", "reasonCode": "AE001", "name": "AUTH_TOKEN_MISSING", "description": "The Authorization header is absent or does not contain a Bearer token." } }, "AUTH_TOKEN_INVALID": { "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid).", "value": { "statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A Bearer token was provided but could not be verified (malformed, expired, or signature-invalid)." } } } } } }, "403": { "description": "Authorization Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "ACCESS_DENIED": { "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint.", "value": { "statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The token is valid but its OAuth2 scopes do not grant access to this endpoint." } } } } } }, "404": { "description": "FXP Payment Not Found (single-payment query only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "FXP_PAYMENT_NOT_FOUND": { "description": "No completed payment was found for the UETR. The same response is returned when the payment belongs to a different FXP to prevent information leakage.", "value": { "statusCode": "RJCT", "reasonCode": "BE021", "name": "FXP_PAYMENT_NOT_FOUND", "description": "No completed payment found for the given UETR for this FXP." } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorApiResponse" }, "examples": { "INTERNAL_ERROR": { "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff.", "value": { "statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "An unhandled exception or infrastructure failure occurred. The caller may retry with exponential backoff." } } } } } }, "200": { "description": "Returns a single-payment response for UETR mode or a page response for date-range mode.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FxpPaymentResponse" }, { "$ref": "#/components/schemas/FxpPaymentPageResponse" } ] } } } }, "405": { "description": "Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.", "headers": { "Allow": { "description": "Permitted HTTP methods for this endpoint", "schema": { "type": "string" }, "example": "GET" } } }, "429": { "description": "Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.", "headers": { "Retry-After": { "description": "Duration after which the caller may retry", "schema": { "type": "integer", "minimum": 0, "description": "Number of seconds to wait before retrying" }, "example": 30 } } }, "502": { "description": "Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate." }, "503": { "description": "Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff." }, "504": { "description": "Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff." } }, "security": [ { "nexusClientCert": [], "nexusOAuth": [ "fxp.payment.read" ] } ] } } }, "components": { "schemas": { "ErrorApiResponse": { "type": "object", "description": "Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.", "properties": { "statusCode": { "type": "string", "description": "Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.", "enum": [ "RJCT" ], "example": "RJCT", "maxLength": 4 }, "reasonCode": { "type": "string", "description": "Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error, e.g. BE021).", "enum": [ "TE001", "TE099", "AE001", "AE002", "AE004", "BE021", "BE022", "BE023", "BE024", "BE025", "BE026", "BE027" ], "example": "TE001", "maxLength": 5, "pattern": "[A-Z]{2}[0-9]{3}" }, "name": { "type": "string", "description": "Machine-readable business error name from the reason code catalogue.", "example": "INVALID_REQUEST", "maxLength": 50, "pattern": "[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*" }, "description": { "type": "string", "description": "Human-readable error description. MUST NOT contain PII (CD-INV-09).", "example": "One or more request parameters are missing, malformed, or do not conform to the expected schema.", "maxLength": 500 } }, "required": [ "description", "name", "reasonCode", "statusCode" ] }, "IAAccountReference": { "type": "object", "required": [ "addressTypeCode", "fields" ], "description": "Reference to an IA account by address type and its identifying fields.", "properties": { "addressTypeCode": { "type": "string", "description": "Nexus address type code identifying the account addressing scheme (e.g. IBAN, AU-BSB).", "example": "IBAN" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map of address fields as defined by the address type schema.", "example": { "iban": "DE89370400440532013000" } } } }, "RateRequest": { "type": "object", "required": [ "sourceIAAccount", "destinationIAAccount", "rate" ], "description": "Request body for creating or replacing a rate.", "properties": { "sourceIAAccount": { "$ref": "#/components/schemas/IAAccountReference" }, "destinationIAAccount": { "$ref": "#/components/schemas/IAAccountReference" }, "rate": { "type": "number", "format": "double", "exclusiveMinimum": 0, "description": "Exchange rate: number of destination currency units per one source currency unit.", "example": 1.5019 } } }, "RateResponse": { "type": "object", "description": "A single FXP rate record.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Nexus-assigned unique identifier for the rate record.", "example": "9929ea23-f29c-4053-b54a-5bf7a1bb348e" }, "fxpId": { "type": "string", "description": "Nexus internal identifier for the FXP that owns this rate.", "example": "FXP-A" }, "sourceIAAccount": { "$ref": "#/components/schemas/IAAccountReference" }, "destinationIAAccount": { "$ref": "#/components/schemas/IAAccountReference" }, "sourceCurrency": { "type": "string", "maxLength": 3, "minLength": 3, "description": "ISO 4217 source currency code resolved from sourceIAAccount.", "example": "EUR" }, "destinationCurrency": { "type": "string", "maxLength": 3, "minLength": 3, "description": "ISO 4217 destination currency code resolved from destinationIAAccount.", "example": "AUD" }, "sourceIps": { "type": "string", "description": "Source IPS identifier resolved from sourceIAAccount.", "example": "EURTIPS" }, "destinationIps": { "type": "string", "description": "Destination IPS identifier resolved from destinationIAAccount.", "example": "AUSNPP" }, "rate": { "type": "number", "format": "double", "description": "The exchange rate.", "example": 1.5019 }, "createdDateTime": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp when this rate record was created.", "example": "2024-11-01T10:00:00Z" }, "isExpired": { "type": "boolean", "description": "If true, this rate has been superseded by a newer rate for the same account pair, or voluntarily withdrawn. Not a time-based expiry.", "example": false }, "expiryDateTime": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp when this rate was superseded or withdrawn. Null if still live.", "example": null } } }, "RatesPageResponse": { "type": "object", "description": "Paginated list of rate records.", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RateResponse" }, "description": "Rate records for the current page." }, "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null if this is the last page.", "example": "eyJwayI6Li4ufQ==" } } }, "TierRequest": { "type": "object", "required": [ "sourceCurrency", "threshold", "improvementBps" ], "description": "Request body for creating or replacing a tier.", "properties": { "sourceCurrency": { "type": "string", "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]{3}$", "description": "ISO 4217 source currency code the tier applies to.", "example": "EUR" }, "threshold": { "type": "number", "format": "double", "exclusiveMinimum": 0, "description": "Minimum transaction amount in the source currency for this tier to apply.", "example": 50000 }, "improvementBps": { "type": "integer", "minimum": 1, "description": "Rate improvement in basis points applied to the base rate when this tier is selected.", "example": 100 } } }, "TierResponse": { "type": "object", "description": "A single FXP tier record.", "properties": { "tierId": { "type": "string", "format": "uuid", "description": "Nexus-assigned unique identifier for the tier record.", "example": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87" }, "fxpId": { "type": "string", "description": "Nexus internal identifier for the FXP that owns this tier.", "example": "FXP-A" }, "sourceCurrency": { "type": "string", "maxLength": 3, "minLength": 3, "description": "ISO 4217 source currency code this tier applies to.", "example": "EUR" }, "threshold": { "type": "number", "format": "double", "description": "Minimum transaction amount (in source currency) for this tier to apply.", "example": 50000 }, "improvementBps": { "type": "integer", "description": "Improvement in basis points applied when this tier is selected.", "example": 100 }, "createdDateTime": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp when this tier record was created.", "example": "2024-11-01T10:00:00Z" }, "isExpired": { "type": "boolean", "description": "If true, this tier has been superseded or voluntarily withdrawn.", "example": false }, "expiryDateTime": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live.", "example": null } } }, "TiersPageResponse": { "type": "object", "description": "Paginated list of tier records.", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TierResponse" }, "description": "Tier records for the current page." }, "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null if this is the last page.", "example": "eyJwayI6Li4ufQ==" } } }, "RelationshipRequest": { "type": "object", "description": "Request body for creating an FXP–PSP relationship. pspImprovementBps is optional.", "properties": { "pspImprovementBps": { "type": [ "integer", "null" ], "minimum": 0, "description": "PSP-based improvement in basis points. Omit to apply the FXP base rate without improvement to this PSP.", "example": 25 } } }, "RelationshipUpdateRequest": { "type": "object", "required": [ "pspImprovementBps" ], "description": "Request body for updating an FXP–PSP relationship improvement.", "properties": { "pspImprovementBps": { "type": "integer", "minimum": 0, "description": "Updated PSP-based improvement in basis points. Set to 0 to remove the improvement so the base rate applies.", "example": 50 } } }, "RelationshipResponse": { "type": "object", "description": "A single FXP–PSP relationship record.", "properties": { "relationshipId": { "type": "string", "format": "uuid", "description": "Nexus-assigned unique identifier for this relationship record.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "fxpId": { "type": "string", "description": "Nexus internal identifier for the FXP.", "example": "FXP-A" }, "pspId": { "type": "string", "description": "Nexus internal identifier for the PSP.", "example": "PSP-C" }, "pspImprovementBps": { "type": [ "integer", "null" ], "description": "PSP-based improvement in basis points. Null if no improvement is configured.", "example": 25 }, "createdDateTime": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp when this relationship was created.", "example": "2024-09-15T08:30:00Z" }, "updatedDateTime": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp of the last update. Null if never updated.", "example": "2024-10-01T12:00:00Z" } } }, "RelationshipsPageResponse": { "type": "object", "description": "Paginated list of FXP–PSP relationship records.", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipResponse" }, "description": "Relationship records for the current page." }, "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null if this is the last page.", "example": "eyJwayI6Li4ufQ==" } } }, "CountResponse": { "type": "object", "description": "Count of records matching the query.", "properties": { "count": { "type": "integer", "minimum": 0, "description": "Total count of matching records.", "example": 2 } } }, "FxpPaymentResponse": { "type": "object", "description": "Completed payment record for FXP query.", "example": { "uetr": "d302cc08-323b-4ac6-897e-579a9abe0c88", "status": "COMPLETED", "paymentTime": "2026-03-25T09:15:12Z", "fxpRateId": "FXP-A-RATE-20260325-00001234", "source": { "currency": "EUR", "amount": "49530.17", "pspId": "SOURCE_PSP_001" }, "destination": { "currency": "SGD", "amount": "75000.00", "pspId": "DEST_PSP_009" }, "exchangeRate": "1.5225" }, "properties": { "uetr": { "type": "string", "format": "uuid", "description": "Unique payment identifier (UETR) from the original pacs.008. UUID v4.", "example": "d302cc08-323b-4ac6-897e-579a9abe0c88", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "status": { "type": "string", "description": "Payment completion status.", "enum": [ "COMPLETED" ], "example": "COMPLETED" }, "paymentTime": { "type": "string", "format": "date-time", "description": "Time of successful payment completion (ISO 8601 UTC).", "example": "2026-03-25T09:15:12Z" }, "fxpRateId": { "type": "string", "description": "FXP-issued rate identifier, if applicable.", "example": "FXP-A-RATE-20260325-00001234" }, "source": { "$ref": "#/components/schemas/PaymentPartyResponse", "description": "Source-side values." }, "destination": { "$ref": "#/components/schemas/PaymentPartyResponse", "description": "Destination-side values." }, "exchangeRate": { "type": "string", "description": "Exchange rate applied (decimal string, > 0).", "example": 1.5225 } }, "required": [ "destination", "exchangeRate", "paymentTime", "source", "status", "uetr" ] }, "PaymentPartyResponse": { "type": "object", "description": "Payment party details (source or destination side).", "example": { "currency": "EUR", "amount": "49530.17", "pspId": "SOURCE_PSP_001" }, "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "EUR", "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "description": "Amount in the currency.", "example": 49530.17 }, "pspId": { "type": "string", "description": "The PSP identifier.", "example": "PSP_001" } }, "required": [ "amount", "currency", "pspId" ] }, "FxpPaymentPageResponse": { "type": "object", "description": "Paginated response for FXP payment date-range query.", "example": { "items": [ { "uetr": "d302cc08-323b-4ac6-897e-579a9abe0c88", "status": "COMPLETED", "paymentTime": "2026-03-25T09:15:12Z", "fxpRateId": "FXP-A-RATE-20260325-00001234", "source": { "currency": "EUR", "amount": "49530.17", "pspId": "SOURCE_PSP_001" }, "destination": { "currency": "SGD", "amount": "75000.00", "pspId": "DEST_PSP_009" }, "exchangeRate": "1.5225" } ], "nextCursor": "eyJwayI6Li4ufQ==", "totalCount": 142 }, "properties": { "items": { "type": "array", "description": "Array of payment records (same schema as single-payment response).", "items": { "$ref": "#/components/schemas/FxpPaymentResponse", "description": "Array of payment records (same schema as single-payment response)." } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for next page; null if no more results.", "example": "eyJwayI6Li4ufQ==" }, "totalCount": { "type": "integer", "format": "int32", "description": "Total number of matching records (may be omitted for performance).", "example": 142 } } } }, "securitySchemes": { "nexusOAuth": { "type": "oauth2", "description": "OAuth2 client credentials token issued per participant.", "flows": { "clientCredentials": { "tokenUrl": "https://auth.nexus.net/realms/nexus/protocol/openid-connect/token", "scopes": { "fxp.payment.read": "Query the FXP's own completed payments", "rates.read": "Read FXP rate records.", "rates.write": "Create or withdraw FXP rate records.", "tiers.read": "Read FXP tier records.", "tiers.write": "Create or withdraw FXP tier records.", "relationships.read": "Read FXP–PSP relationship records.", "relationships.write": "Create, update, or delete FXP–PSP relationship records." } } } }, "nexusClientCert": { "type": "mutualTLS", "description": "Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header." } } } }