> For the complete documentation index, see [llms.txt](https://docs.nexusglobalpayments.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexusglobalpayments.org/nexus-fxp-apis/models.md).

# Models

## The ErrorApiResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"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"],"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"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","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).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}}}
```

## The IAAccountReference object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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)."},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of address fields as defined by the address type schema."}}}}}}
```

## The RateRequest object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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."}}},"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)."},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of address fields as defined by the address type schema."}}}}}}
```

## The RateResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"RateResponse":{"type":"object","description":"A single FXP rate record.","properties":{"id":{"type":"string","format":"uuid","description":"Nexus-assigned unique identifier for the rate record."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP that owns this rate."},"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."},"destinationCurrency":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 destination currency code resolved from destinationIAAccount."},"sourceIps":{"type":"string","description":"Source IPS identifier resolved from sourceIAAccount."},"destinationIps":{"type":"string","description":"Destination IPS identifier resolved from destinationIAAccount."},"rate":{"type":"number","format":"double","description":"The exchange rate."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this rate record was created."},"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."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp when this rate was superseded or withdrawn. Null if still live."}}},"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)."},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of address fields as defined by the address type schema."}}}}}}
```

## The RatesPageResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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."}}},"RateResponse":{"type":"object","description":"A single FXP rate record.","properties":{"id":{"type":"string","format":"uuid","description":"Nexus-assigned unique identifier for the rate record."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP that owns this rate."},"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."},"destinationCurrency":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 destination currency code resolved from destinationIAAccount."},"sourceIps":{"type":"string","description":"Source IPS identifier resolved from sourceIAAccount."},"destinationIps":{"type":"string","description":"Destination IPS identifier resolved from destinationIAAccount."},"rate":{"type":"number","format":"double","description":"The exchange rate."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this rate record was created."},"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."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp when this rate was superseded or withdrawn. Null if still live."}}},"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)."},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of address fields as defined by the address type schema."}}}}}}
```

## The TierRequest object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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."},"threshold":{"type":"number","format":"double","exclusiveMinimum":0,"description":"Minimum transaction amount in the source currency for this tier to apply."},"improvementBps":{"type":"integer","minimum":1,"description":"Rate improvement in basis points applied to the base rate when this tier is selected."}}}}}}
```

## The TierResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"TierResponse":{"type":"object","description":"A single FXP tier record.","properties":{"tierId":{"type":"string","format":"uuid","description":"Nexus-assigned unique identifier for the tier record."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP that owns this tier."},"sourceCurrency":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 source currency code this tier applies to."},"threshold":{"type":"number","format":"double","description":"Minimum transaction amount (in source currency) for this tier to apply."},"improvementBps":{"type":"integer","description":"Improvement in basis points applied when this tier is selected."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this tier record was created."},"isExpired":{"type":"boolean","description":"If true, this tier has been superseded or voluntarily withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live."}}}}}}
```

## The TiersPageResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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."}}},"TierResponse":{"type":"object","description":"A single FXP tier record.","properties":{"tierId":{"type":"string","format":"uuid","description":"Nexus-assigned unique identifier for the tier record."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP that owns this tier."},"sourceCurrency":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 source currency code this tier applies to."},"threshold":{"type":"number","format":"double","description":"Minimum transaction amount (in source currency) for this tier to apply."},"improvementBps":{"type":"integer","description":"Improvement in basis points applied when this tier is selected."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this tier record was created."},"isExpired":{"type":"boolean","description":"If true, this tier has been superseded or voluntarily withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live."}}}}}}
```

## The RelationshipRequest object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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."}}}}}}
```

## The RelationshipUpdateRequest object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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."}}}}}}
```

## The RelationshipResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP."},"pspId":{"type":"string","description":"Nexus internal identifier for the PSP."},"pspImprovementBps":{"type":["integer","null"],"description":"PSP-based improvement in basis points. Null if no improvement is configured."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this relationship was created."},"updatedDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp of the last update. Null if never updated."}}}}}}
```

## The RelationshipsPageResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"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."}}},"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."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP."},"pspId":{"type":"string","description":"Nexus internal identifier for the PSP."},"pspImprovementBps":{"type":["integer","null"],"description":"PSP-based improvement in basis points. Null if no improvement is configured."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this relationship was created."},"updatedDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp of the last update. Null if never updated."}}}}}}
```

## The CountResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"CountResponse":{"type":"object","description":"Count of records matching the query.","properties":{"count":{"type":"integer","minimum":0,"description":"Total count of matching records."}}}}}}
```

## The FxpPaymentResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"FxpPaymentResponse":{"type":"object","description":"Completed payment record for FXP query.","properties":{"uetr":{"type":"string","format":"uuid","description":"Unique payment identifier (UETR) from the original pacs.008. UUID v4.","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"]},"paymentTime":{"type":"string","format":"date-time","description":"Time of successful payment completion (ISO 8601 UTC)."},"fxpRateId":{"type":"string","description":"FXP-issued rate identifier, if applicable."},"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)."}},"required":["destination","exchangeRate","paymentTime","source","status","uetr"]},"PaymentPartyResponse":{"type":"object","description":"Payment party details (source or destination side).","properties":{"currency":{"type":"string","description":"ISO 4217 currency code.","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"amount":{"type":"string","description":"Amount in the currency."},"pspId":{"type":"string","description":"The PSP identifier."}},"required":["amount","currency","pspId"]}}}}
```

## The PaymentPartyResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"PaymentPartyResponse":{"type":"object","description":"Payment party details (source or destination side).","properties":{"currency":{"type":"string","description":"ISO 4217 currency code.","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"amount":{"type":"string","description":"Amount in the currency."},"pspId":{"type":"string","description":"The PSP identifier."}},"required":["amount","currency","pspId"]}}}}
```

## The FxpPaymentPageResponse object

```json
{"openapi":"3.1.0","info":{"title":"Nexus FXP API","version":"v1"},"components":{"schemas":{"FxpPaymentPageResponse":{"type":"object","description":"Paginated response for FXP payment date-range query.","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."},"totalCount":{"type":"integer","format":"int32","description":"Total number of matching records (may be omitted for performance)."}}},"FxpPaymentResponse":{"type":"object","description":"Completed payment record for FXP query.","properties":{"uetr":{"type":"string","format":"uuid","description":"Unique payment identifier (UETR) from the original pacs.008. UUID v4.","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"]},"paymentTime":{"type":"string","format":"date-time","description":"Time of successful payment completion (ISO 8601 UTC)."},"fxpRateId":{"type":"string","description":"FXP-issued rate identifier, if applicable."},"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)."}},"required":["destination","exchangeRate","paymentTime","source","status","uetr"]},"PaymentPartyResponse":{"type":"object","description":"Payment party details (source or destination side).","properties":{"currency":{"type":"string","description":"ISO 4217 currency code.","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"amount":{"type":"string","description":"Amount in the currency."},"pspId":{"type":"string","description":"The PSP identifier."}},"required":["amount","currency","pspId"]}}}}
```