> 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/fxp-payment-query.md).

# FXP Payment Query

FXP will use the following APIs to retrieve completed payment records

## Query FXP completed payments

> Retrieve completed payment records for the authenticated FXP.\
> \
> Supported query modes:\
> \
> 1\. Single payment:\
>    Provide \`uetr\` only.\
> \
> 2\. Date range:\
>    Provide \`fromDate\` and \`toDate\`.\
> &#x20;  \`cursor\` and \`limit\` are optional.<br>

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"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."}],"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":[{"nexusClientCert":[],"nexusOAuth":["fxp.payment.read"]}],"components":{"securitySchemes":{"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."}},"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"]},"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)."}}},"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/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"}},{"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}$"}},{"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"}},{"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"}},{"name":"cursor","in":"query","description":"Pagination cursor; omit for first page. Optional. Opaque token.","required":false,"schema":{"type":"string"}},{"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}}],"responses":{"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"}]}}}},"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":"FXP Payment Not Found (single-payment query only)","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,"description":"Number of seconds to wait before retrying"}}}},"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."}}}}}}
```