> ## Documentation Index > Fetch the complete documentation index at: https://docs.fexco.com/llms.txt > Use this file to discover all available pages before exploring further. # Create DCC Rate Offer > Creates a Dynamic Currency Conversion (DCC) rate offer for a card transaction. The offer includes exchange rate, foreign currency amounts, fees, and expiry information. ## OpenAPI ````yaml /openapi/rest-ng.json post /dcc/offers openapi: 3.1.0 info: title: Flex Proxy REST NG API description: "# Flex Proxy REST NG API Specification\r\n\r\n## Overview\r\nThe Flex Proxy REST NG API provides Dynamic Currency Conversion (DCC) services through a secure, RESTful interface. This API enables financial institutions and payment processors to offer real-time currency conversion services to their customers.\r\n\r\n## Authentication\r\nAll API requests must be authenticated using JSON Web Token (JWT) with Public Key Infrastructure (PKI) certificates embedded in the token header. This ensures secure, non-repudiable authentication using industry-standard cryptographic practices.\r\nSee [JSON Web Token Documentation](https://www.jwt.io/introduction#what-is-json-web-token)\r\n\r\n## Integrator Notes\r\n\r\nThe following request fields are **optional**. If you have no value, omit the field entirely rather than sending an empty string — some optional fields are pattern-validated and an empty string will be rejected.\r\n\r\n`referenceCode` | Optional field dchoed back in the response and recorded in logs for traceability. Recommended to aid support/troubleshooting.\r\n`paymentDetails.cid` | Optional field that allows for card digits beyond the first 6 digits to be contained in a separate field. Numeric text only (`^[0-9]+$`). \r\n`paymentDetails.posEntryMode` | ISO 8583 entry mode (3-digit code). See the field description for the full list of valid values. `07x` and `91x` are the current Contactless values configured for TLL on the DHS service. \r\n`orderDetails.fee` | Merchant fee in the order currency, sent as a decimal string (e.g. `\"2.50\"`). Omit when no fee applies.\r\n`orderDetails.currency` | ISO 4217 alphabetic currency code (`^[A-Z]{3}$`, e.g. `EUR`) identifying the order's base currency. \r\n`terminalInformation.terminalLocation` | Human-readable terminal location, used for receipts and reporting. \r\n\r\n> All other fields shown in the request schema are **required** — see each model's `required` list in the schema reference below.\r\n\r\n### Request Format\r\n```\r\nContent-Type: application/json\r\nAuthorization: Bearer \r\n```\r\n\r\n### JWT Token Structure\r\nJWT tokens consist of three Base64URL-encoded parts separated by dots (.):\r\n\r\n```\r\nJWT Token = base64url(Header) . base64url(Payload) . base64url(Signature)\r\n```\r\n\r\nExample format: `xxxxx.yyyyy.zzzzz`\r\n\r\n**HTTP Header Format:**\r\n```json\r\n{\r\n \"Authorization\": \"Bearer \"\r\n}\r\n```\r\n*Note: One space must follow \"Bearer\"*\r\n\r\n### JWT Header\r\nThe JWT header contains metadata about the token, including the certificate chain for verification.\r\n\r\n```json\r\n{\r\n \"alg\": \"RS256\",\r\n \"typ\": \"JWT\",\r\n \"version\": \"v1\",\r\n \"x5c\": [\r\n \"MIIDqTCCApGgAwIBAgIJAKNsmL7QbNMzMA0GCSqGSIb3DQEBCwUAMGsxCzAJBgNV...\"\r\n ]\r\n}\r\n```\r\n\r\n**Header Parameters:**\r\n- `alg`: Signing algorithm (always \"RS256\" for RSA with SHA-256)\r\n- `typ`: Token type (always \"JWT\")\r\n- `version`: API version identifier\r\n- `x5c`: X.509 certificate chain array (Base64-encoded DER certificates)\r\n - First certificate: End-entity certificate containing the public key\r\n - Subsequent certificates: Intermediate CA certificates (if any)\r\n - Root CA certificate is not included (must be pre-trusted)\r\n\r\n### JWT Payload\r\nThe payload contains the request metadata and integrity information.\r\n\r\n```json\r\n{\r\n \"iss\": \"client-system-identifier\",\r\n \"sub\": \"api-client-id\",\r\n \"aud\": \"dcc-dhs-api\",\r\n \"iat\": 1745839403,\r\n \"exp\": 1745841203,\r\n \"digest\": \"tP7hDajF4f6q0ysBQCHgef5K/PBq8iMASvlEARp8tl8=\",\r\n \"digestAlgorithm\": \"SHA-256\"\r\n}\r\n```\r\n\r\n**Payload Parameters:**\r\n- `iss`: Issuer - identifies the client system making the request - Optional - used for troubleshooting\r\n- `sub`: Subject - the API client identifier (recommended to use Acquirer ID) - Optional - used for troubleshooting\r\n- `aud`: Audience - target API service (always \"dcc-dhs-api\")\r\n- `iat`: Issued at time (Unix timestamp)\r\n- `exp`: Expiration time (Unix timestamp, max 30 minutes from `iat`)\r\n- `digest`: Base64-encoded SHA-256 hash of the request body: `Base64(SHA256(JSON_payload))`\r\n- `digestAlgorithm`: Hash algorithm used for request body digest (Supported: \"SHA-256\")\r\n\r\n### JWT Signature\r\nThe signature is created using the RS256 algorithm:\r\n\r\n```\r\nsignature = RS256(\r\n base64urlEncode(header) + \".\" + base64urlEncode(payload),\r\n private_key\r\n)\r\n```\r\n\r\nThe signature ensures token integrity and proves possession of the private key corresponding to the certificate in the `x5c` header.\r\n\r\n**CSR Requirements:**\r\n```\r\nSubject: CN=client-identifier, O=, OU=department, L=city, ST=state, C=country-code\r\nKey Usage: Digital Signature\r\nExtended Key Usage: Client Authentication\r\nKey Size: RSA-2048 minimum (RSA-4096 recommended)\r\n```\r\n\r\n**CSR Submission Format:**\r\n```\r\n-----BEGIN CERTIFICATE REQUEST-----\r\nMIICvjCCAaYCAQAwejELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWEx\r\n...\r\n-----END CERTIFICATE REQUEST-----\r\n```\r\n\r\n### Implementation Examples\r\n\r\n**BASH example:**\r\n```bash\r\n# JWT creation with provider-issued certificate\r\njwt_header='{\"alg\":\"RS256\",\"typ\":\"JWT\",\"version\":\"v1\",\"x5c\":[\"MIID...\"]}'\r\njwt_payload='{\"iss\":\"client-system\",\"sub\":\"api-client\",\"aud\":\"dcc-dhs-api\",\"iat\":1745839403,\"exp\":1745841203,\"digest\":\"...\"}'\r\n\r\n# Sign with provider-issued private key\r\nsignature=$(echo -n \"${jwt_header}.${jwt_payload}\" | openssl dgst -sha256 -sign private_key.pem | base64url)\r\njwt_token=\"${jwt_header}.${jwt_payload}.${signature}\"\r\n```\r\n\r\n## API Endpoints\r\n\r\n### Authentication Headers\r\nAll API requests must include the following headers:\r\n\r\n```\r\nContent-Type: application/json\r\nAuthorization: Bearer \r\nx-acquirer-id: <3-letter-acquirer-code>\r\nx-card-acceptor-id: \r\n```\r\n\r\n**Header Validation:**\r\n- `x-acquirer-id`: Exactly 3 alphabetic characters (case-insensitive)\r\n- `x-card-acceptor-id`: numeric characters\r\n\r\n### Error Handling\r\nStandard HTTP status codes with detailed error responses:\r\n\r\n```json\r\n{\r\n \"timestamp\": \"2025-10-14T09:15:55.857Z\",\r\n \"status\": 401,\r\n \"error\": \"Unauthorized\",\r\n \"message\": \"JWT signature verification failed\",\r\n \"path\": \"/pos/offers\",\r\n \"details\": [\r\n {\r\n \"code\": \"INVALID_JWT_SIGNATURE\",\r\n \"message\": \"The JWT signature could not be verified with the provided certificate\"\r\n }\r\n ]\r\n}\r\n```" contact: name: Fexco API Team email: ProductionSupportPFX@fexco.com license: name: Apache 2.0 url: http://springdoc.org version: v0.0.1 servers: - url: https://{your-base-url} description: Base URL provided by Fexco during onboarding security: - Authentication: [] tags: - name: DCC Rate Offers description: APIs for Dynamic Currency Conversion (DCC) rate offer management paths: /dcc/offers: post: tags: - DCC Rate Offers summary: Create DCC Rate Offer description: >- Creates a Dynamic Currency Conversion (DCC) rate offer for a card transaction. The offer includes exchange rate, foreign currency amounts, fees, and expiry information. operationId: createDccRateOffer parameters: - name: X-Correlation-ID in: header description: Optional correlation ID for request tracing required: false schema: type: string - $ref: '#/components/parameters/x-acquirer-id' - $ref: '#/components/parameters/x-card-acceptor-id' requestBody: content: application/json: schema: $ref: '#/components/schemas/DccRateOfferRequest' required: true responses: '201': description: Successfully created DCC rate offer content: application/json: schema: $ref: '#/components/schemas/DccCardRateOfferResponse' '400': description: >- Invalid request payload, missing required fields, or validation errors content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict - rate no longer available or external service unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error during rate offer processing content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: x-acquirer-id: name: x-acquirer-id in: header description: >- 3-letter alphabetic acquirer identifier (must match the Acquirer ID used to generate the CSR) required: true schema: example: ABC pattern: ^[A-Z]{3}$ x-card-acceptor-id: name: x-card-acceptor-id in: header description: Numeric card acceptor code (merchant ID), 1-16 digits required: true schema: example: '998877' pattern: ^[0-9]{1,16}$ schemas: DccRateOfferRequest: type: object description: >- DCC rate offer request containing transaction details, payment info, and order information example: referenceCode: TXN-2025-001234 transactionType: PURCHASE paymentDetails: bin: '409019' cid: '111' posEntryMode: '079' orderDetails: amount: '100.00' fee: '2.50' currency: EUR terminalInformation: terminalId: TERM001234 terminalType: POS properties: referenceCode: type: string description: >- Optional unique reference code for the transaction (Currently used for traceability in the logs, recommended to include) example: TXN-2025-001234 transactionType: type: string description: Type of transaction being processed enum: - PURCHASE - REFUND - CASH_ADVANCE - REVERSAL - PREAUTHORIZATION - INCREMENTAL_AUTHORIZATION - COMPLETE_AUTHORIZATION example: PURCHASE paymentDetails: $ref: '#/components/schemas/TransactionPaymentDetails' description: Payment card and transaction entry details orderDetails: $ref: '#/components/schemas/OrderDetails' description: Order details including amount, fee, and currency terminalInformation: $ref: '#/components/schemas/TerminalInformation' description: Terminal information for POS and ATM transactions required: - orderDetails - paymentDetails - transactionType DccCardRateOfferResponse: type: object description: >- Response containing the DCC rate offer details including exchange rates, amounts, and offer status properties: id: type: string format: uuid description: >- Unique identifier for this specific rate offer (used for tracking and acceptance) example: 550e8400-e29b-41d4-a716-446655440000 referenceCode: type: string description: >- Optional Reference code from the original request (Currently used for traceability in the logs, recommended to include) example: TXN-2025-001234 transactionType: type: string description: Type of transaction this offer applies to enum: - PURCHASE - REFUND - CASH_ADVANCE - REVERSAL - PREAUTHORIZATION - INCREMENTAL_AUTHORIZATION - COMPLETE_AUTHORIZATION example: PURCHASE baseAmount: type: string description: Transaction amount in the base (merchant) currency example: '100.0' foreignAmount: type: string description: Transaction amount converted to the cardholder's foreign currency example: '110.5' foreignFeeAmount: type: string description: Optional fee amount in the foreign currency example: '2.75' foreignTotalAmount: type: string description: >- Total amount in foreign currency (foreignAmount + foreignFeeAmount). If not provided, it can be computed from foreignAmount and foreignFeeAmount example: '113.25' exchangeRate: $ref: '#/components/schemas/ExchangeRate' description: >- Detailed exchange rate information including base/foreign currencies, rate, margins, and expiry offerText: type: string description: >- Ready-to-use text for DCC offer presentation with resolved exchange rates and amounts. Server-side processed for immediate display. example: >- Accept currency conversion at rate 1.1050? You will pay 110.50 USD instead of 100.00 EUR. receiptText: type: string description: >- Ready-to-use text for receipt display with resolved exchange rates and amounts. Server-side processed for immediate display. example: 'Currency conversion applied: 100.00 EUR = 110.50 USD at rate 1.1050' issueAt: type: string format: date-time description: Timestamp when this rate offer response was generated example: '2025-10-08T14:30:00Z' required: - baseAmount - exchangeRate - foreignAmount - id - issueAt - transactionType ErrorResponse: type: object description: Standard API error response format used across all endpoints properties: timestamp: type: string format: date-time description: Timestamp when the error occurred example: '2025-10-09T09:57:32.461Z' status: type: integer format: int32 description: HTTP status code example: 400 error: type: string description: Short error type/category example: Bad Request message: type: string description: Human-readable error message example: Request validation failed path: type: string description: Request path that caused the error example: /dcc/offers details: type: array description: >- Additional error details (e.g., field validation errors, business errors) items: $ref: '#/components/schemas/ErrorDetail' required: - error - message - status - timestamp TransactionPaymentDetails: type: object description: Payment card and transaction entry details for processing the DCC offer properties: bin: type: string description: Bank Identification Number (BIN) - first 6 digits of the card number example: '411111' minLength: 1 pattern: ^[0-9]+$ cid: type: string description: Optional Cardholder identification or customer ID example: '987' pattern: ^[0-9]+$ posEntryMode: type: string description: >- Optional POS (Point of Sale) entry mode, as defined by ISO 8583, indicating how the card data (PAN) was captured and the PIN entry capability of the terminal. **Format:** two-digit sub-field 1 (PAN entry mode) followed by one-digit sub-field 2 (PIN entry capability), e.g. `051`. **Sub-field 1 — PAN entry mode:** - `00` Unknown or unspecified - `01` Manual entry - `02` Magnetic stripe (not fully read/transmitted) - `03` Bar code reader - `04` Optical character reader (OCR) - `05` ICC - `07` Contactless ICC (EMV) - `80` Fallback from ICC to magnetic stripe - `90` Magnetic stripe - `91` Contactless magnetic stripe - `95` ICC (CVV may not be checked) **Sub-field 2 — PIN entry capability:** - `0` Unspecified or unknown - `1` Terminal has PIN entry capability - `2` Terminal does not have PIN entry capability - `8` Terminal has PIN entry capability but PIN pad not currently operative Note: `07x` and `91x` are the current Contactless values configured for TLL on the DHS service. example: '051' required: - bin OrderDetails: type: object description: Merchant order information including amount, fee, and currency details properties: amount: type: string description: Total transaction amount in the order currency example: '100.0' fee: type: string description: Optional Fee amount charged for this transaction example: '2.5' currency: type: string description: Optional ISO 4217 currency code for the order (e.g., EUR, USD, GBP) example: EUR pattern: '[A-Z]{3}' required: - amount TerminalInformation: type: object description: Terminal information for POS and ATM transactions example: terminalId: TERM001234 terminalType: POS properties: terminalId: type: string description: Unique terminal identifier (accepts terminal serial number) example: TERM001234 minLength: 1 terminalType: type: string description: Terminal type classification enum: - POS - ATM - ECOMMERCE example: POS minLength: 1 terminalLocation: type: string description: Terminal location description example: Store Front required: - terminalId - terminalType ExchangeRate: type: object description: >- Exchange rate details for currency conversion including base rate, margins, and validity period properties: id: type: string format: uuid description: Unique identifier for this exchange rate example: 650e8400-e29b-41d4-a716-446655440001 baseCurrency: $ref: '#/components/schemas/Currency' description: Base (merchant) currency details foreignCurrency: $ref: '#/components/schemas/Currency' description: Foreign (cardholder) currency details rate: type: string description: Exchange rate applied for conversion from base to foreign currency example: '1.105' marginPercentage: type: string description: Margin percentage applied to the base exchange rate example: '3.5' commissionPercentage: type: string description: Commission percentage applied to the transaction example: '1.0' source: type: string description: Source of the exchange rate (e.g., Refinitiv, Wholesale, Internal) example: Refinitiv sourceTimestamp: type: string format: date-time description: Timestamp when the source rate was obtained example: '2025-10-08T14:00:00Z' expiry: type: string format: date-time description: Timestamp when this exchange rate offer expires example: '2025-10-08T14:35:00Z' schemeCode: type: integer format: int32 description: Card scheme code (e.g., Visa, Mastercard identifier) example: 1 required: - baseCurrency - expiry - foreignCurrency - rate ErrorDetail: type: object description: >- Generic error detail for validation errors, business errors, or specific error conditions properties: code: type: string description: Error code identifying the type of error enum: - VALIDATION_ERROR - BUSINESS_ERROR - CONSTRAINT_VIOLATION example: VALIDATION_ERROR title: type: string description: Short title describing the error type example: Invalid Field Value message: type: string description: >- Detailed error message including context and rejected value if applicable example: >- Field 'amount' is required but was null, or Currency 'XYZ' is not supported Currency: type: object description: Currency information including ISO codes and decimal precision properties: numericCode: type: string description: ISO 4217 numeric currency code (3 characters) example: '978' alphaCode: type: string description: ISO 4217 alphabetic currency code (3 characters) example: EUR pattern: '[A-Z]{3}' minorUnits: type: integer format: int32 description: Number of decimal places (minor units) for this currency example: 2 securitySchemes: Authentication: type: http description: >- JWT authentication with PKI certificates. Token must include x5c header with certificate chain and digest claim for request body validation. scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.