openapi: 3.0.3
info:
  title: DCC rate service API
  description: >-
    This is an API reference for the DCC (Dynamic Currency Conversion) rate
    service.
  version: 1.0.0
servers:
  - url: https://api-services.pxp.io/api/v1
    description: Production environment
  - url: https://api-services.test.pxp.io/api/v1
    description: Sandbox environment
paths:
  /dcc/rate:
    post:
      operationId: get-dcc-rate
      summary: Get DCC rate
      description: >-
        Retrieve the Dynamic Currency Conversion (DCC) rate for a transaction
        from various providers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DccRateRequest'
            examples:
              p2pe-example:
                summary: P2PE transaction
                description: Example request for a P2PE transaction with encrypted payload.
                value:
                  merchant: MERCHANT-1
                  site: SITE-1
                  exchangeRateProvider: Elavon
                  cardholderCurrencyCode: EUR
                  securityLevel:
                    encryptedPayload: >-
                      48BCFZFUklGT05F348CBFA0MDDfjwMLMjc1LTA0MC0zNzHfjwYBAN+PBwQbTVL4348ECv//AAAQACXgAA/fjwUIPmP5MQz/poffjwhoreYH9Y6M47xapI7MALlOG7zWO97lD7rVPK5pUVdHUotneMaiaBwE/2EMliZV3ZIiWPi4Xaa3A3wcnEFjAT9SqwwEEVI6XmDQXAbplogQzMQsOsDFmIGXaTPb9sVdTumSsyFAmZwRE=
                  transactionMethod:
                    entryMode: Instore
                    intent: Authorisation
                  pointOfInteraction:
                    entryType: ChipAndPin
                    merchantPointOfSaleId: POS-1
                  amounts:
                    localTransaction: 100
                    localCurrencyCode: USD
              non-p2pe-example:
                summary: Non-P2PE transaction
                description: Example request for a non-P2PE transaction with PAN.
                value:
                  merchant: MERCHANT-1
                  site: SITE-1
                  exchangeRateProvider: GlobalBlue
                  cardholderCurrencyCode: GBP
                  securityLevel:
                    primaryAccountNumber: '4111111111111111'
                  transactionMethod:
                    entryMode: Instore
                    intent: Authorisation
                  pointOfInteraction:
                    entryType: ChipAndPin
                    merchantPointOfSaleId: POS-001
                  amounts:
                    localTransaction: 100
                    localCurrencyCode: USD
              ecom-example:
                summary: E-commerce transaction
                description: Example request for an e-commerce transaction.
                value:
                  merchant: MERCHANT-1
                  site: SITE-1
                  exchangeRateProvider: Fexco
                  cardholderCurrencyCode: EUR
                  securityLevel:
                    primaryAccountNumber: '4111111111111111'
                  transactionMethod:
                    entryMode: Ecom
                    intent: Authorisation
                  amounts:
                    localTransaction: 100
                    localCurrencyCode: USD
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DccRateResponse'
              examples:
                elavon-response:
                  summary: Available DCC rate - Elavon provider
                  description: Example response from Elavon provider
                  value:
                    state: Available
                    amounts:
                      local:
                        transaction: 100
                        currencyCode: USD
                      cardholder:
                        transaction: 85.5
                        currencyCode: EUR
                    exchangeRate:
                      rate: 0.855
                      exponent: 3
                      markUpPercentage: 3.5
                      commissionRate: 0.025
                      margin: 2.1
                    messaging:
                      markUpMessage: Competitive exchange rate with 3.5% markup
                      disclaimer: Exchange rate includes markup and may vary.
                    providerResponse:
                      provider: Elavon
                      referenceId: REF123456789
                      merchantId: MERCH-001
                      terminalId: TERM-001
                fexco-response:
                  summary: Available DCC rate - Fexco provider
                  description: Example response from Fexco provider
                  value:
                    state: Available
                    amounts:
                      local:
                        transaction: 100
                        currencyCode: USD
                      cardholder:
                        transaction: 86.2
                        currencyCode: EUR
                    exchangeRate:
                      rate: 0.862
                      exponent: 3
                      markUpPercentage: 3.2
                      commissionRate: 0.022
                      margin: 1.8
                    messaging:
                      markUpMessage: Fexco exchange rate with 3.2% markup
                      disclaimer: Rate subject to market conditions and markup.
                    providerResponse:
                      provider: Fexco
                      conversionId: FEXCO_CONV_456789
                      clientRef: CLIENT_REF_001
                      processorId: PROC_789
                globalblue-response:
                  summary: Available DCC rate - Global Blue provider
                  description: Example response from Global Blue provider
                  value:
                    state: Available
                    amounts:
                      local:
                        transaction: 100
                        currencyCode: USD
                      cardholder:
                        transaction: 84.75
                        currencyCode: EUR
                    exchangeRate:
                      rate: 0.8475
                      exponent: 4
                      markUpPercentage: 4
                      commissionRate: 0.03
                      margin: 2.5
                    messaging:
                      markUpMessage: Global Blue exchange rate with 4.0% markup
                      disclaimer: Exchange rate provided by Global Blue includes markup.
                    providerResponse:
                      provider: GlobalBlue
                      transactionId: GB987654321
                      merchantCode: GB_MERCH001
                      shopId: SHOP_001
                dcc-not-available:
                  summary: DCC not available
                  description: Example response when DCC service is not available
                  value:
                    state: NotAvailable
                    amounts:
                      local:
                        transaction: 100
                        currencyCode: USD
                      cardholder:
                        transaction: 0
                        currencyCode: EUR
                    exchangeRate:
                      rate: 0
                      exponent: 0
                      markUpPercentage: 0
                      commissionRate: 0
                      margin: 0
                    messaging:
                      markUpMessage: ''
                      disclaimer: DCC service not available for this transaction
                    providerResponse:
                      provider: Elavon
                      referenceId: ''
                      merchantId: ''
                      terminalId: ''
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CurrencyCode:
      type: string
      description: Currency code in ISO 4217 format.
      example: USD
      minLength: 3
      maxLength: 3
      pattern: ^[A-Z]{3}$
    BaseAmount:
      type: object
      required:
        - localTransaction
        - localCurrencyCode
      properties:
        localCurrencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        localTransaction:
          type: number
          description: The transaction amount in the local currency.
          example: 100
          minimum: 0.01
    BaseProviderResponse:
      type: object
      description: Base structure for provider responses.
      required:
        - provider
      properties:
        provider:
          type: string
          description: The name of the provider.
    RequestAmounts:
      allOf:
        - $ref: '#/components/schemas/BaseAmount'
    ResponseAmounts:
      type: object
      description: Details about the amounts.
      allOf:
        - $ref: '#/components/schemas/BaseAmount'
        - type: object
          required:
            - cardholderTransaction
            - cardholderCurrencyCode
          properties:
            cardholderCurrencyCode:
              $ref: '#/components/schemas/CurrencyCode'
            cardholderTransaction:
              type: number
              description: The transaction amount in the cardholder's currency.
              example: 85.5
              minimum: 0.01
    DccRateRequest:
      type: object
      required:
        - merchant
        - site
        - exchangeRateProvider
        - cardholderCurrencyCode
        - securityLevel
        - transactionMethod
        - amounts
      properties:
        merchant:
          type: string
          description: Your unique merchant identifier, as assigned by PXP.
          example: MERCHANT-1
          maxLength: 20
        site:
          type: string
          description: Your unique site identifier, as assigned by PXP.
          example: SITE-1
          maxLength: 20
        exchangeRateProvider:
          type: string
          enum:
            - Elavon
            - GlobalBlue
            - Fexco
          description: The exchange rate provider to use for the DCC rate calculation.
          example: Elavon
        cardholderCurrencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        securityLevel:
          $ref: '#/components/schemas/SecurityLevel'
        transactionMethod:
          $ref: '#/components/schemas/TransactionMethod'
        pointOfInteraction:
          $ref: '#/components/schemas/PointOfInteraction'
        amounts:
          $ref: '#/components/schemas/RequestAmounts'
    PointOfInteraction:
      type: object
      description: >-
        Details about the point of interaction. This object is optional for
        `Ecom` transactions.
      properties:
        entryType:
          type: string
          enum:
            - CardContactless
            - ChipAndPin
          description: The type of entry used to capture the card details.
          example: ChipAndPin
          minLength: 1
        merchantPointOfSaleId:
          type: string
          description: The unique identifier for the merchant point of sale.
          example: POS-001
          minLength: 1
    SecurityLevel:
      type: object
      description: >-
        Details about the security level of the transaction. This object
        contains either an encrypted payload for P2PE or primary account number
        for non-P2PE.
      oneOf:
        - title: P2PE card data
          type: object
          properties:
            encryptedPayload:
              type: string
              description: The encrypted payload, for P2PE transactions.
              example: >-
                48BCFZFUklGT05F348CBFA0MDDfjwMLMjc1LTA0MC0zNzHfjwYBAN+PBwQbTVL4348ECv//AAAQACXgAA/fjwUIPmP5MQz/poffjwhoreYH9Y6M47xapI7MALlOG7zWO97lD7rVPK5pUVdHUotneMaiaBwE/2EMliZV3ZIiWPi4Xaa3A3wcnEFjAT9SqwwEEVI6XmDQXAbplogQzMQsOsDFmIGXaTPb9sVdTumSsyFAmZwRE=
              minLength: 1
          required:
            - encryptedPayload
        - title: Non-P2PE card data
          type: object
          properties:
            primaryAccountNumber:
              type: string
              description: The primary account number (PAN), for non-P2PE transactions.
              example: primaryAccountNumber
              minLength: 1
          required:
            - primaryAccountNumber
    TransactionMethod:
      type: object
      description: Details about the transaction method.
      required:
        - entryMode
        - intent
      properties:
        entryMode:
          type: string
          enum:
            - Instore
            - Ecom
          description: The entry mode of the transaction.
        intent:
          type: string
          enum:
            - Purchase
            - Authorisation
            - EstimatedAuthorisation
            - Capture
            - FinalCapture
            - Refund
            - Reversal
          description: The intent of the transaction.
    DccRateResponse:
      type: object
      description: The response body containing the DCC rate.
      required:
        - state
        - amounts
        - exchangeRate
        - messaging
        - providerResponse
      properties:
        state:
          type: string
          enum:
            - Available
            - NotAvailable
            - CardEligible
            - CardNotEligible
            - Error
          description: The state of the DCC rate request.
        amounts:
          $ref: '#/components/schemas/ResponseAmounts'
        exchangeRate:
          $ref: '#/components/schemas/ExchangeRate'
        messaging:
          $ref: '#/components/schemas/Messaging'
        providerResponse:
          oneOf:
            - $ref: '#/components/schemas/ElavonProviderResponse'
            - $ref: '#/components/schemas/GlobalBlueProviderResponse'
            - $ref: '#/components/schemas/FexcoProviderResponse'
    Messaging:
      type: object
      description: Details about the messaging of the DCC rate request.
      required:
        - markUpMessage
        - disclaimer
      properties:
        markUpMessage:
          type: string
          description: Message about the markup.
          example: Competitive exchange rate with 3.5% markup
        disclaimer:
          type: string
          description: Disclaimer text about the rate.
          example: Exchange rate includes markup and may vary.
    ExchangeRate:
      type: object
      description: Details about the exchange rate.
      required:
        - rate
        - exponent
        - markUpPercentage
        - commissionRate
        - margin
      properties:
        rate:
          type: number
          description: The foreign exchange rate.
          example: 0.855
        exponent:
          type: integer
          description: The exponent of the foreign exchange rate.
          example: 3
        markUpPercentage:
          type: number
          description: The markup percentage.
          example: 3
        commissionRate:
          type: number
          description: The commission rate applied.
          example: 0.025
        margin:
          type: number
          description: The margin applied.
          example: 2.1
    ElavonProviderResponse:
      type: object
      description: Details about the Elavon provider response.
      allOf:
        - $ref: '#/components/schemas/BaseProviderResponse'
        - type: object
          required:
            - referenceId
            - merchantId
            - terminalId
          properties:
            provider:
              type: string
              description: The name of the provider.
              example: Elavon
            referenceId:
              type: string
              description: The Elavon reference ID.
              example: REF123456789
            terminalId:
              type: string
              description: The terminal ID provided by Elavon.
              example: TERM-001
    GlobalBlueProviderResponse:
      type: object
      description: Details about the Global Blue provider response.
      allOf:
        - $ref: '#/components/schemas/BaseProviderResponse'
        - type: object
          required:
            - transactionId
            - merchantCode
            - shopId
          properties:
            provider:
              type: string
              description: The name of the provider.
              example: GlobalBlue
            transactionId:
              type: string
              description: The transaction ID provided by Global Blue.
              example: GB987654321
            merchantCode:
              type: string
              description: The merchant code provided by Global Blue.
              example: GB_MERCH001
            shopId:
              type: string
              description: The shop ID provided by Global Blue.
              example: SHOP_001
    FexcoProviderResponse:
      type: object
      description: Details about the Fexco provider response.
      allOf:
        - $ref: '#/components/schemas/BaseProviderResponse'
        - type: object
          required:
            - conversionId
            - clientRef
            - processorId
          properties:
            provider:
              type: string
              description: The name of the provider.
              example: Fexco
            conversionId:
              type: string
              description: The conversion ID provided by Fexco.
              example: FEXCO_CONV_456789
            clientRef:
              type: string
              description: The client reference provided by Fexco.
              example: CLIENT_REF_001
            processorId:
              type: string
              description: The processor ID provided by Fexco.
              example: PROC_789
    ErrorResponse:
      type: object
      description: Details about the error response.
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: The error code.
          example: VALIDATION_ERROR
        message:
          type: string
          description: The error message.
          example: >-
            Either encryptedPayload or primaryAccountNumber must be provided in
            securityLevel
        details:
          type: string
          description: Additional details about the error.
          example: >-
            List [ "Field 'merchant' is required", "Field 'localTransaction'
            must be greater than 0" ]
