FXP Payment Query

FXP will use the following APIs to retrieve completed payment records

Query FXP completed payments

get

/v1/fxp/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. cursor and limit are optional.

Required scopes

This endpoint requires the following scopes:

• : Query the FXP's own completed payments

Authorizations

mutualTLS

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.

OAuth2clientCredentialsRequired

OAuth2 client credentials token issued per participant.

Token URL:

Query parameters

uetrstring · uuidOptional

UETR of the payment to retrieve. Required for single-payment mode. UUID v4.

Example: d302cc08-323b-4ac6-897e-579a9abe0c88Pattern: ^[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}$

fromDatestring · date-timeOptional

Start of query window (inclusive). Required for date-range mode. ISO 8601 UTC date-time.

Example: 2026-03-01T00:00:00Z

toDatestring · date-timeOptional

End of query window (exclusive). Required for date-range mode. ISO 8601 UTC date-time.

Example: 2026-03-31T00:00:00Z

cursorstringOptional

Pagination cursor; omit for first page. Optional. Opaque token.

Example: eyJwayI6Li4ufQ==

limitinteger · min: 1 · max: 100Optional

Max records per page. Optional. 1-100, default 50.

Default: 50Example: 50

Header parameters

AcceptstringRequired

application/json

Default: application/jsonExample: application/json

Responses

200

Returns a single-payment response for UETR mode or a page response for date-range mode.

application/json

or

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

404

FXP Payment Not Found (single-payment query only)

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

get/v1/fxp/payments

GET /v1/fxp/payments HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json

{
  "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"
}