> 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/apis/fees-and-amounts.md).

# Fees and Amounts

{% hint style="info" %}
For further information on the types of fees in Nexus, see [Fees](/payment-processing/fees.md).
{% endhint %}

## Get Fees and Interbank Settlement Amounts

> Retrieves the various fees and amounts based on specified parameters. Information can be used in the pacs.008 payment instruction.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"Fees and Amounts","description":"APIs for a Source PSP acting as its own FX Provider to either have settlement amounts and fees computed on its behalf, or retrieve the fee formula for independent computation."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusOAuth":["quote.read"]}],"components":{"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":{"countries.read":"Read country and currency reference data","address.read":"Read address types and input definitions","institutions.read":"Read the financial institution directory","quotes.read":"Retrieve FX quotes for a corridor and amount","quote.read":"Compute fees and settlement amounts from a PSP supplied rate","fees.read":"Retrieve the Destination Agent fee formula","payment.process":"Submit and receive ISO 20022 payment messages","admin.downtime.notify":"Submit admi.004 downtime notifications for a Direct Participant IPS","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."}}}}},"schemas":{"FeesAndAmountsResponse":{"type":"object","description":"Computed debtor and creditor amounts with fees.","properties":{"debtorAgent":{"$ref":"#/components/schemas/DebtorAgentAmounts","description":"Debtor-side amounts and fees."},"creditorAgent":{"$ref":"#/components/schemas/CreditorAgentAmounts","description":"Creditor-side amounts and fees."}},"required":["creditorAgent","debtorAgent"]},"DebtorAgentAmounts":{"type":"object","description":"Debtor-side amounts.","properties":{"interbankSettlementAmount":{"$ref":"#/components/schemas/AmountDto","description":"Interbank settlement amount."}}},"AmountDto":{"type":"object","description":"Monetary amount with currency code.","properties":{"amount":{"type":"number","description":"Fixed nominal fee amount in Destination Currency. Omitted when the formula has no fixed component."},"currency":{"type":"string","description":"ISO-4217 currency code for the fee. Always the Destination Currency. Omitted when nominalFee is omitted.","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}}},"CreditorAgentAmounts":{"type":"object","description":"Creditor-side amounts.","properties":{"interbankSettlementAmount":{"$ref":"#/components/schemas/AmountDto","description":"Interbank settlement amount."},"chargesAmount":{"$ref":"#/components/schemas/AmountDto","description":"Charges amount."},"creditorAccountAmount":{"type":"number","description":"Net amount credited to the creditor account."}}},"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/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"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"]}}},"paths":{"/v1/fees-and-amounts/{sourceCountry}/{sourceCurrency}/{destinationCountry}/{destinationCurrency}/{amountCurrency}/{amount}/{exchangeRate}":{"get":{"tags":["Fees and Amounts"],"summary":"Get Fees and Interbank Settlement Amounts","description":"Retrieves the various fees and amounts based on specified parameters. Information can be used in the pacs.008 payment instruction.","operationId":"getFeesAndAmounts","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"sourceCountry","in":"path","description":"ISO-3166 alpha-2 country code of the Source Country.","required":true,"schema":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"}},{"name":"sourceCurrency","in":"path","description":"ISO-4217 3-letter code of the Source Currency.","required":true,"schema":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}},{"name":"destinationCountry","in":"path","description":"ISO-3166 alpha-2 country code of the Destination Country.","required":true,"schema":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"}},{"name":"destinationCurrency","in":"path","description":"ISO-4217 3-letter code of the Destination Currency.","required":true,"schema":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}},{"name":"amountCurrency","in":"path","description":"ISO-4217 3-letter code of the currency in which amount is expressed.","required":true,"schema":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}},{"name":"amount","in":"path","description":"The amount in the specified amountCurrency. If defined in Source Currency, this\nmust be the Interbank Settlement Amount (after Source PSP deduction). If defined\nin Destination Currency, this is the CreditorAccountAmount to be credited to the\nRecipient.\n","required":true,"schema":{"type":"number","minimum":0}},{"name":"exchangeRate","in":"path","description":"The exchange rate from Source to Destination currency, as managed by the Source PSP.","required":true,"schema":{"type":"number","minimum":0}},{"name":"finInstIdType","in":"query","description":"Type ID of the Source PSP. Used together with finInstId to identify the Source\nPSP, which is treated as the FX Provider for the resulting payment. The\noriginating Source IPS is resolved separately from the authenticated caller\ncontext.\n","required":true,"schema":{"type":"string"}},{"name":"finInstId","in":"query","description":"ID of the Source PSP.","required":true,"schema":{"type":"string"}},{"name":"destFinInstIdType","in":"query","description":"Type ID of the Destination PSP. Required when the destination country operates\nmultiple IPSes. Used to resolve which Destination IPS serves the Destination PSP\nfor the Source PSP's Destination-side settlement-account check.\n","required":false,"schema":{"type":"string"}},{"name":"destFinInstId","in":"query","description":"ID of the Destination PSP. Required when the destination country operates\nmultiple IPSes. If absent in a multi-IPS destination country, Nexus rejects the\nrequest with BE008 QUOTE_DESTINATION_PSP_REQUIRED.\n","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Fees and amounts quote generated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeesAndAmountsResponse"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"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"}}}},"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}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"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."}}}}}}
```

## Get Destination Agent Fee Formula

> Returns the Destination Agent (Destination PSP) Fee FORMULA for a specified Destination Country, denominated in the Destination Currency. Supports HTTP conditional GET via If-None-Match header.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"Fees and Amounts","description":"APIs for a Source PSP acting as its own FX Provider to either have settlement amounts and fees computed on its behalf, or retrieve the fee formula for independent computation."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusOAuth":["fees.read"]}],"components":{"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":{"countries.read":"Read country and currency reference data","address.read":"Read address types and input definitions","institutions.read":"Read the financial institution directory","quotes.read":"Retrieve FX quotes for a corridor and amount","quote.read":"Compute fees and settlement amounts from a PSP supplied rate","fees.read":"Retrieve the Destination Agent fee formula","payment.process":"Submit and receive ISO 20022 payment messages","admin.downtime.notify":"Submit admi.004 downtime notifications for a Direct Participant IPS","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."}}}}},"schemas":{"DestinationAgentFeeResponse":{"type":"object","description":"Destination agent fee configuration.","properties":{"countryCode":{"type":"string","description":"ISO-3166 alpha-2 country code of the Destination Country.","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"},"nominalFee":{"$ref":"#/components/schemas/AmountDto","description":"Fixed nominal fee amount and currency in the Destination Currency. Omitted when the formula has no fixed component."},"percentageFee":{"type":"number","description":"Percentage fee expressed as a decimal ratio (e.g., 0.1 = 10%). Omitted when the formula has no percentage component."},"validTo":{"type":"string","format":"date-time","description":"Timestamp at which the returned fee formula is scheduled to expire. Always set to the next 23:59:59 Singapore-time boundary (+08:00). PSPs/IPSs MUST refresh the formula on or before this time."}}},"AmountDto":{"type":"object","description":"Monetary amount with currency code.","properties":{"amount":{"type":"number","description":"Fixed nominal fee amount in Destination Currency. Omitted when the formula has no fixed component."},"currency":{"type":"string","description":"ISO-4217 currency code for the fee. Always the Destination Currency. Omitted when nominalFee is omitted.","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}}},"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/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"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"]}}},"paths":{"/v1/fee-formulas/destination-agent-fee/{countryCode}/{currencyCode}":{"get":{"tags":["Fees and Amounts"],"summary":"Get Destination Agent Fee Formula","description":"Returns the Destination Agent (Destination PSP) Fee FORMULA for a specified Destination Country, denominated in the Destination Currency. Supports HTTP conditional GET via If-None-Match header.","operationId":"getDestinationAgentFee","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"countryCode","in":"path","description":"ISO‑3166 alpha‑2 country code of the Destination Country. Example:`MY`","required":true,"schema":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"}},{"name":"currencyCode","in":"path","description":"ISO‑4217 3‑letter code of the Destination Currency. Example:`MYR`","required":true,"schema":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}},{"name":"If-None-Match","in":"header","description":"Optional. ETag value from a previous response for conditional GET. If it matches the current entity tag, the server returns 304 Not Modified with no body.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Destination Agent Fee retrieved.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationAgentFeeResponse"}}}},"304":{"description":"Not Modified. The resource has not changed since the last request.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"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"}}}},"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}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"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."}}}}}}
```