openapi: 3.0.1
info:
  title: 3D Secure 3DS Authentication Merchant Maintenance API
  version: 3.43.0
  description: Operations for listing and retrieving 3DS authentication records. Use these endpoints to query historical authentication results filtered by amount, currency, card, status, and more.
servers:
- url: https://emea.gsc.verifone.cloud/oidc/3ds-service
  description: EMEA Production
- url: https://us.gsc.verifone.cloud/oidc/3ds-service
  description: Americas Production
- url: https://nz.gsc.verifone.cloud/oidc/3ds-service
  description: New Zealand Production
- url: https://cst.test-gsc.vfims.com/oidc/3ds-service
  description: Global Sandbox
- url: https://uscst-gb.gsc.vficloud.net/oidc/3ds-service
  description: Americas Sandbox
security:
- BearerAuth: []
- BasicAuth: []
tags:
- name: Merchant Maintenance
paths:
  /entities/{entityUid}/tradingAddress:
    patch:
      tags:
      - Merchant Maintenance
      summary: Partial Update of a Trading address
      description: A partial update of an existing Merchant Entity Address. Only replaces the provided parameters.
      operationId: updateEntityAddress
      parameters:
      - $ref: '#/components/parameters/entityUidPathParam'
      requestBody:
        description: Address details to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseAddress'
      responses:
        '200':
          description: Patch Trading Address Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAddressWithoutType'
          headers:
            orderId:
              schema:
                $ref: '#/components/schemas/OrderId'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
components:
  schemas:
    httpError404:
      title: HTTP 404 Error
      type: object
      description: The server cannot find the requested resource.
      allOf:
      - $ref: '#/components/schemas/ErrorResp'
      - properties:
          code:
            type: string
            enum:
            - '404'
            default: '404'
          title:
            type: string
            enum:
            - Not Found
            default: Not Found
          message:
            type: string
            default: The server cannot find the requested resource.
          timestamp:
            description: "The time that the error occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone."
            type: string
            format: date-time
          type:
            type: string
            enum:
            - INVALID_REQUEST_ERROR
            default: INVALID_REQUEST_ERROR
          param:
            description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
            type: string
      required:
      - code
      - title
      - message
      - type
      additionalProperties: false
    httpError503:
      title: HTTP 503 Error
      type: object
      description: Service Unavailable Error
      allOf:
      - $ref: '#/components/schemas/ErrorResp'
      - properties:
          code:
            type: string
            enum:
            - '503'
            default: '503'
          title:
            type: string
            enum:
            - Service Unavailable
            default: Service Unavailable
          message:
            type: string
            default: The server is not ready to handle the request. If specified please check the <strong>Retry-After</strong> for the time period specified for recovery/re-attempt of request.
          timestamp:
            description: "The time that the error occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone."
            type: string
            format: date-time
          type:
            type: string
            enum:
            - API_ERROR
            default: API_ERROR
          param:
            description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
            type: string
      required:
      - code
      - title
      - message
      - type
      additionalProperties: false
    EmailAddress:
      title: Email Address
      maxLength: 254
      minLength: 3
      type: string
      format: email
      pattern: ^[a-zA-Z0-9!#$%&'*+=?^_`{|}~.-]+@[a-zA-Z0-9-]+[.].+$
      description: A valid internationalized email address, as defined by RFC 5322, RFC 6530, and other RFCs. Due to RFC 5321, an email address can be up to 254 characters long even though up to 64 characters are allowed before and 255 characters are allowed after the @ sign. This pattern verifies only that the string contains an unquoted @ sign. See https://tools.ietf.org/html/rfc5322#section-3.4.1.
    httpError500:
      title: HTTP 500 Error
      type: object
      description: Unexpected Server Error
      allOf:
      - $ref: '#/components/schemas/ErrorResp'
      - properties:
          code:
            type: string
            enum:
            - '500'
            default: '500'
          title:
            type: string
            enum:
            - Internal Server Error
            default: Internal Server Error
          message:
            type: string
            default: The server encountered an unexpected condition which prevented it from fulfilling the request.
          timestamp:
            description: "The time that the error occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone."
            type: string
            format: date-time
          type:
            type: string
            enum:
            - API_ERROR
            default: API_ERROR
          param:
            description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
            type: string
      required:
      - code
      - title
      - message
      - type
      additionalProperties: false
    PostCode:
      description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
      type: string
      minLength: 1
      maxLength: 16
    TimeZone:
      description: A time zone, following the format defined in the IANA tz database (https://www.iana.org/time-zones). Valid examples are America/New_York and Etc/UTC. Do not use ambiguous, non-qualified values such as EST or GB. Before including this type in your interface, please consider whether it is actually appropriate to convey time zone information with your type. It is almost always the case that this should be transformed from UTC at the time of display to the user; this type might therefore be most associated with user-preference APIs.
      type: string
      minLength: 1
      maxLength: 127
    httpError400:
      title: HTTP 400 Error
      type: object
      description: The request could not be understood by the server due to malformed syntax.
      allOf:
      - $ref: '#/components/schemas/ErrorResp'
      - properties:
          code:
            type: string
            enum:
            - '400'
            default: '400'
          title:
            type: string
            enum:
            - Bad Request
            default: Bad Request
          message:
            type: string
            default: The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
          timestamp:
            description: "The time that the error occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone."
            type: string
            format: date-time
          type:
            type: string
            enum:
            - INVALID_REQUEST_ERROR
            default: INVALID_REQUEST_ERROR
          param:
            description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
            type: string
      required:
      - code
      - title
      - message
      - type
      additionalProperties: false
    BaseAddressWithoutType:
      description: An Address following the convention of http://microformats.org/wiki/hcard
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseAddress'
      properties:
        contact:
          $ref: '#/components/schemas/ContactType'
        vfiSiteId:
          maxLength: 50
          minLength: 1
          type: string
          description: Address/Site identifier known as within Verifone internal systems.
        storeNumber:
          type: string
          description: Store Number or Client/Customer ID in Oracle
        governmentOwned:
          type: boolean
          description: Indicates whether the address is government-owned. E.g. Address can be in Sweden, but can be a US Embassy.
        governmentCountry:
          $ref: '#/components/schemas/CountryCode3Enum'
    httpError401:
      title: HTTP 401 Error
      type: object
      description: The request must be authenticated to access the resource.
      allOf:
      - $ref: '#/components/schemas/ErrorResp'
      - properties:
          code:
            type: string
            enum:
            - '401'
            default: '401'
          title:
            type: string
            enum:
            - Unauthorised
            default: Unauthorised
          message:
            type: string
            default: The request requires client authentication.
          timestamp:
            description: "The time that the error occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone."
            type: string
            format: date-time
          type:
            type: string
            enum:
            - AUTHENTICATION_ERROR
            default: AUTHENTICATION_ERROR
          param:
            description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
            type: string
      required:
      - code
      - title
      - message
      - type
      additionalProperties: false
    ContactTypeEnum:
      title: Contact Type
      description: 'An indicator for the type of contact.


        |Value|Description|

        |----|-----------|

        |BUSINESS|Generic business contact information, e.g. info@example.com|

        |DISPUTE_HANDLING|Generic contact information specific to dispute handling, e.g. disputes@example.com|

        |OWNER|Individual contact information of the owner of the Entity, e.g. ben.jerry@example.com|

        |PERSONAL|Personal contact information of the person representing the Entity, e.g. bjerr83@example-personal-email-domain.com|'
      type: string
      enum:
      - BUSINESS
      - DISPUTE_HANDLING
      - OWNER
      - PERSONAL
      default: BUSINESS
    OrderId:
      description: Verifone allocated ID for the Order.
      type: string
      format: uuid
    Phone:
      title: Phone number
      description: A simple Phone Number
      type: object
      additionalProperties: false
      properties:
        callingCode:
          description: Country Calling Code. Mapped to PARTY_PHONE.CALLING_CODE or VENUE_PHONE.CALLING_CODE
          type: string
        value:
          description: The actual phone number less country code and/or extension.
          type: string
          minLength: 5
        extension:
          description: The internal extension number where applicable or known.
          type: string
        isPrimary:
          description: Indicates that the phone is a the primary phone. Mapped to PARTY_PHONE_PRIMARY
          type: boolean
          default: false
        phoneType:
          $ref: '#/components/schemas/PhoneTypeEnum'
      required:
      - value
      - phoneType
    httpError504:
      title: HTTP 504 Error
      type: object
      description: Gateway Timeout Error
      allOf:
      - $ref: '#/components/schemas/ErrorResp'
      - properties:
          code:
            type: string
            enum:
            - '504'
            default: '504'
          title:
            type: string
            enum:
            - Gateway Timeout
            default: Gateway Timeout
          message:
            type: string
            default: The server, while acting as a gateway or proxy, did not get a response in time from the upstream server that it needed in order to complete the request.
          timestamp:
            description: "The time that the error occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone."
            type: string
            format: date-time
          type:
            type: string
            enum:
            - API_ERROR
            default: API_ERROR
          param:
            description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
            type: string
      required:
      - code
      - title
      - message
      - type
      additionalProperties: false
    Name:
      title: Name Details
      description: An object representing the name or component names of a party, person or business. No elements are mandatory due to the different usages, but the business rules need to be applied in the context where name is used.
      type: object
      uniqueItems: false
      properties:
        firstName:
          description: The given name of contact.
          type: string
          minLength: 1
          maxLength: 120
        lastName:
          description: The surname name or family name of the contact. This is required when the name is for a party or person. Can also include the matronymic or mother's family name where this is customarily used.
          minLength: 1
          maxLength: 120
          type: string
        prefix:
          description: The prefix to the party name. This is sometimes referred to as a title, salutation or appellation.
          maxLength: 120
          type: string
        alternateFullName:
          description: The alternate name for the party. This can be a business name or nickname. This should be used where the name of the party cannot be parsed into its constituent parts such as first name or last name. If the party is a business then this should always be present.
          maxLength: 200
          type: string
        middleName:
          description: The middle name or names for a party or person.
          maxLength: 120
          type: string
        suffix:
          description: The name suffix for the party.
          maxLength: 120
          type: string
      required:
      - firstName
      - lastName
    ContactType:
      description: The details of a Contact.
      type: object
      properties:
        contactType:
          $ref: '#/components/schemas/ContactTypeEnum'
        name:
          $ref: '#/components/schemas/ContactName'
        phoneNumbers:
          description: The phone numbers to be used for the Contact. If you include this property there should be at least one phone number.
          items:
            $ref: '#/components/schemas/Phone'
          minItems: 1
          uniqueItems: true
          type: array
        email:
          $ref: '#/components/schemas/EmailAddress'
        businessTitle:
          $ref: '#/components/schemas/BusinessTitle'
      required:
      - contactType
      - name
    BaseAddress:
      description: An Address following the convention of http://microformats.org/wiki/hcard
      type: object
      properties:
        receiverName:
          type: string
          minLength: 1
          description: The receiver name for the address if different to the company/site name.
        addressLine1:
          minLength: 1
          maxLength: 40
          type: string
          description: Address Line 1. Should include street and apartment number if required.
        addressLine2:
          maxLength: 40
          type: string
          description: Address Line 2
        addressLine3:
          maxLength: 40
          type: string
          description: Address Line 3
        poBox:
          type: string
          description: The PO BOX number.
        city:
          minLength: 1
          maxLength: 28
          type: string
          description: Name of a built-up area, with defined boundaries, and a local government. This could be city or town.
        countrySubdivision:
          maxLength: 35
          minLength: 1
          type: string
          description: Identifies a sub-division of a country which may be state, region or county. This follows a similar format to the openbank api.
        postCode:
          $ref: '#/components/schemas/PostCode'
        country:
          $ref: '#/components/schemas/CountryCode3Enum'
        timeZone:
          $ref: '#/components/schemas/TimeZone'
    PhoneTypeEnum:
      title: Phone Type
      description: Phone type in PHONE_TYPE_CON. Mapped to PARTY_PHONE.PHONE_TYPE_CON_ID or VENUE_PHONE.PHONE_TYPE_CON_ID
      type: string
      enum:
      - HOME
      - MOBILE
      - WORK
      - FAX
      - OTHER
      default: HOME
    httpError429:
      title: HTTP 429 Error
      type: object
      description: The resource exists the number of requests has exceeded the specified quota.
      allOf:
      - $ref: '#/components/schemas/ErrorResp'
      - properties:
          code:
            type: string
            enum:
            - '429'
            default: '429'
          title:
            type: string
            enum:
            - Too Many Requests
            default: Too Many Requests
          message:
            type: string
            default: The number of requests from this client is restricted to a specified quota.
          timestamp:
            description: "The time that the error occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone."
            type: string
            format: date-time
          type:
            type: string
            enum:
            - RATE_LIMIT_ERROR
            default: RATE_LIMIT_ERROR
          param:
            description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
            type: string
      required:
      - code
      - title
      - message
      - type
      additionalProperties: false
    ContactName:
      allOf:
      - $ref: '#/components/schemas/Name'
    httpError403:
      title: HTTP 403 Error
      type: object
      description: The request must be authorised to access the resource.
      allOf:
      - $ref: '#/components/schemas/ErrorResp'
      - properties:
          code:
            type: string
            enum:
            - '403'
            default: '403'
          title:
            type: string
            enum:
            - Forbidden
            default: Forbidden
          message:
            type: string
            default: The request requires client authorisation to access resource.
          timestamp:
            description: "The time that the error occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone."
            type: string
            format: date-time
          type:
            type: string
            enum:
            - AUTHENTICATION_ERROR
            default: AUTHENTICATION_ERROR
          param:
            description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
            type: string
      required:
      - code
      - title
      - message
      - type
      additionalProperties: false
    CountryCode3Enum:
      title: Country Code
      type: string
      description: The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code.<blockquote><strong>Note:</strong> The country code for Great Britain is <code>GB</code> and not <code>UK</code> as is used in that country's top-level domain names.</blockquote>.
      enum:
      - ZZZ
      - ABW
      - AFG
      - AGO
      - AIA
      - ALA
      - ALB
      - AND
      - ARE
      - ARG
      - ARM
      - ASM
      - ATA
      - ATF
      - ATG
      - AUS
      - AUT
      - AZE
      - BDI
      - BEL
      - BEN
      - BES
      - BFA
      - BGD
      - BGR
      - BHR
      - BHS
      - BIH
      - BLM
      - BLR
      - BLZ
      - BMU
      - BOL
      - BRA
      - BRB
      - BSB
      - BRN
      - BTN
      - BVT
      - BWA
      - CAF
      - CAN
      - CCK
      - CHE
      - CHL
      - CHN
      - CIV
      - CMR
      - COD
      - COG
      - COK
      - COL
      - COM
      - CPV
      - CRI
      - CUB
      - CUW
      - CXR
      - CYM
      - CYP
      - CZE
      - DEU
      - DJI
      - DMA
      - DNK
      - DOM
      - DZA
      - ECU
      - EGY
      - ERI
      - ESH
      - ESP
      - EST
      - ETH
      - FIN
      - FJI
      - FLK
      - FRA
      - FRO
      - FSM
      - GAB
      - GBR
      - GEO
      - GGY
      - GHA
      - GIB
      - GIN
      - GLP
      - GMB
      - GNB
      - GNQ
      - GRC
      - GRD
      - GRL
      - GTM
      - GUF
      - GUM
      - GUY
      - HKG
      - HMD
      - HND
      - HRV
      - HTI
      - HUN
      - IDN
      - IMN
      - IND
      - IOT
      - IRL
      - IRN
      - IRQ
      - ISL
      - ISR
      - ITA
      - JAM
      - JEY
      - JOR
      - JPN
      - KAZ
      - KEN
      - KGZ
      - KHM
      - KIR
      - KNA
      - KOR
      - KWT
      - LAO
      - LBN
      - LBR
      - LBY
      - LCA
      - LIE
      - LKA
      - LSO
      - LTU
      - LUX
      - LVA
      - MAC
      - MAF
      - MAR
      - MCO
      - MDA
      - MDG
      - MDV
      - MEX
      - MHL
      - MKD
      - MLI
      - MLT
      - MMR
      - MNE
      - MNG
      - MNP
      - MOZ
      - MRT
      - MSR
      - MTQ
      - MUS
      - MWI
      - MYS
      - MYT
      - NAM
      - NCL
      - NER
      - NFK
      - NGA
      - NIC
      - NIU
      - NLD
      - NOR
      - NPL
      - NRU
      - NZL
      - OMN
      - PAK
      - PAN
      - PCN
      - PER
      - PHL
      - PLW
      - PNG
      - POL
      - PRI
      - PRK
      - PRT
      - PRY
      - PSE
      - PYF
      - QAT
      - REU
      - ROU
      - RUS
      - RWA
      - SAU
      - SDN
      - SEN
      - SGC
      - SGP
      - SHN
      - SJM
      - SLB
      - SLE
      - SLV
      - SMR
      - SOM
      - SPM
      - SRB
      - SSD
      - STP
      - SUR
      - SVK
      - SVN
      - SWE
      - SWZ
      - SXM
      - SYC
      - SYR
      - TCA
      - TCD
      - TGO
      - THA
      - TJK
      - TKL
      - TKM
      - TLS
      - TON
      - TTO
      - TUN
      - TUR
      - TUV
      - TWN
      - TZA
      - UGA
      - UKR
      - UMI
      - URY
      - USA
      - UZB
      - VAT
      - VCT
      - VEN
      - VGB
      - VIR
      - VNM
      - VUT
      - WLF
      - WSM
      - YEM
      - ZAF
      - ZMB
      - ZWE
    BusinessTitle:
      type: string
      maxLength: 100
    ErrorResp:
      title: Error
      description: 'A common Error object returned as part of the API layer.


        . This is modified to become the base class for all of the derived HTTP Error Responses.'
      type: object
      properties:
        reversalStatus:
          description: 'Indicates to the API client if a technical reversal is required or has been completed by Verifone.


            |Value|Description|

            |-|-|

            |NONE|Reversal status is not set. This indicates the status of reversal processing is not known and the client should implement default reversal processing.|

            |REQUIRED|A reversal is required by the client.|

            |COMPLETED|A reversal has been completed by verifone or a reversal is not required for this transaction.|'
          type: string
          enum:
          - NONE
          - REQUIRED
          - COMPLETED
          default: NONE
      required:
      - code
  responses:
    '504':
      description: Service Timeout
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/httpError504'
            - properties:
                param:
                  description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
                  type: string
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
            required:
            - code
            - title
            - message
            - type
    '429':
      description: Too Many Requests
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/httpError429'
            - properties:
                param:
                  description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
                  type: string
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
            required:
            - code
            - title
            - message
            - type
    '403':
      description: Forbidden Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/httpError403'
    '401':
      description: Unauthorised Request
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/httpError401'
            - properties:
                param:
                  description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
                  type: string
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
            required:
            - code
            - title
            - message
            - type
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/httpError400'
            - properties:
                param:
                  description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
                  type: string
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
            required:
            - code
            - title
            - message
            - type
    '404':
      description: Not Found Request
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/httpError404'
            - properties:
                param:
                  description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
                  type: string
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
            required:
            - code
            - title
            - message
            - type
    '500':
      description: Internal Error
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/httpError500'
            - properties:
                param:
                  description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
                  type: string
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
            required:
            - code
            - title
            - message
            - type
    '503':
      description: Service Not Available
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/httpError503'
            - properties:
                param:
                  description: The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.
                  type: string
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
            required:
            - code
            - title
            - message
            - type
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT Bearer token. Pass as: `Authorization: Bearer <token>`. The JWT must be signed with your Verifone-provisioned private key and must include `entity_id`, `sub` (user_id), and `roles` claims.'
    BasicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic authentication. Pass base64-encoded `username:password` as: `Authorization: Basic <credentials>`.'