openapi: 3.0.1
info:
  title: 3DS 3DS actions Query a payment API
  description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n  ```\n    Authorization: {your_credentials}\n  ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n  ```\n  Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n  Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n  ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__  \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
  version: '3'
  x-metadata:
    category:
    - 3DS
    - SCA Exemptions
    business:
    - Enterprise
    catalog-list: true
    generated: false
servers:
- url: https://try.access.worldpay.com
  description: Test (Try)
- url: https://access.worldpay.com
  description: Live
security:
- BasicAuth: []
tags:
- name: Query a payment
paths:
  /payments/events/{linkData}:
    get:
      tags:
      - Query a payment
      summary: Query payment status
      description: "Send a request to find out the current status of your payment after it has been authorized using the events action link.\n\n  **Note:** It can take up to 15 minutes for a payment event to update."
      operationId: eventQuery
      parameters:
      - name: linkData
        in: path
        description: Action link that's received in your request.
        required: true
        schema:
          type: string
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.payments-v7+json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.payments-v7+json
      responses:
        '200':
          description: Retrieve the last event of a payment
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/payments_events_200_response'
              examples:
                Querying a payment event with a transaction reference:
                  description: Querying a payment event with a transaction reference
                  value:
                    lastEvent: Authorized
                    _links:
                      cardPayments:cancel: /payments/authorizations/cancellations/:linkData
                      cardPayments:settle: /payments/settlements/full/:linkData
                      cardPayments:partialSettle: /payments/settlements/partials/:linkData
                      curies:
                      - name: payments
                        href: /rels/payments/{rel}
                        templated: true
        '400':
          description: Bad request
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                Bad request:
                  description: Bad request
                  value:
                    errorName: bodyDoesNotMatchSchema
                    message: The json body provided does not match the expected schema
                    validationErrors:
                    - errorName: fieldMustBeString
                      message: Element at path must be a string
                      jsonPath: $.value.currency
        '401':
          description: Unauthorized
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  description: Unauthorized
                  value:
                    errorName: accessDenied
                    message: Access to the requested resource has been denied
        '404':
          description: Not found
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  description: Not found
                  value:
                    errorName: endpointNotFound
                    message: Requested endpoint was not found.
        '415':
          description: Unsupported media type
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupported:
                  description: Unsupported media type
                  value:
                    errorName: headerHasInvalidValue
                    message: Bad content type
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/events:
    get:
      tags:
      - Query a payment
      summary: Query payment status recovery
      description: "Send a request to find out the current status of your payment after it has been authorized using the events action link. \n\n **Important:** \n\n  Only use this for recovery purposes, for example when your authorization request has timed out or you are unable to locate a payment through our [Payments Queries API](/products/payment-queries). If the query returns results, you can manage the payment using the next action links returned in the response of your GET request."
      operationId: eventRecovery
      parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.payments-v7+json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.payments-v7+json
      responses:
        '200':
          description: Retrieve the last event of a payment
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/payments_events_recovery_200_response'
              examples:
                Querying a payment event with a transaction reference:
                  description: Querying a payment event with a transaction reference
                  value:
                    lastEvent: Authorized
                    _links:
                      cardPayments:cancel: /payments/authorizations/cancellations/:linkData
                      cardPayments:settle: /payments/settlements/full/:linkData
                      cardPayments:partialSettle: /payments/settlements/partials/:linkData
                      curies:
                      - name: payments
                        href: /rels/payments/{rel}
                        templated: true
        '400':
          description: Bad request
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                Bad request:
                  description: Bad request
                  value:
                    errorName: bodyDoesNotMatchSchema
                    message: The json body provided does not match the expected schema
                    validationErrors:
                    - errorName: fieldMustBeString
                      message: Element at path must be a string
                      jsonPath: $.value.currency
        '401':
          description: Unauthorized
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  description: Unauthorized
                  value:
                    errorName: accessDenied
                    message: Access to the requested resource has been denied
        '404':
          description: Not found
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  description: Not found
                  value:
                    errorName: endpointNotFound
                    message: Requested endpoint was not found.
        '415':
          description: Unsupported media type
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupported:
                  description: Unsupported media type
                  value:
                    errorName: headerHasInvalidValue
                    message: Bad content type
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        errorName:
          type: string
        message:
          type: string
    ValidationErrorResponse:
      type: object
      properties:
        errorName:
          type: string
        message:
          type: string
        validationErrors:
          type: array
          description: Further error details
          items:
            type: object
            properties:
              errorName:
                type: string
              message:
                type: string
              jsonPath:
                type: string
    payments_events_200_response:
      required:
      - lastEvent
      type: object
      properties:
        lastEvent:
          type: string
          enum:
          - Authorized
          - Refused
          - Sent for Settlement
          - Sent for Refund
          - Sent for Cancellation
          - Refund failed
          - Settlement failed
          - Settled
          - Refunded
          - Error
          - Expired
          x-enumDescriptions:
            Authorized: The payment has been approved and the funds have been reserved in your customer's account.
            Refused: Your payment request has been declined.
            Sent for Settlement: A request has been made to move the reserved funds in your customer's account and transfer them to your Worldpay account.
            Sent for Refund: A request has been made to send funds back to your customer's account.
            Sent for Cancellation: A request has been made to cancel the payment without sending it for settlement.
            Refund failed: A refund request couldn't be processed and the funds were returned to your account.
            Settlement failed: A settlement request couldn't be processed. Funds have not been transferred to your Worldpay account.
            Settled: We have received the funds and are preparing to transfer them to your bank account. This event is only available in certain use cases.
            Refunded: The card issuer has received the refund request and they will return the funds to your customer's account. This event is only available in certain use cases.
            Error: The payment wasn't completed. You may want to reattempt the payment.
            Expired: The authorization validity period ended before a settlement or cancel request was made.
    payments_events_recovery_200_response:
      required:
      - lastEvent
      type: object
      properties:
        lastEvent:
          type: string
          enum:
          - Authorized
          - Refused
          - Sent for Settlement
          - Sent for Refund
          - Send for Cancellation
          - Refund failed
          - Settlement failed
          - Settled
          - Refunded
          - Error
          - Expired
          x-enumDescriptions:
            Authorized: The payment has been approved and the funds have been reserved in your customer's account.
            Refused: Your payment request has been declined.
            Sent for Settlement: A request has been made to move the reserved funds in your customer's account and transfer them to your Worldpay account.
            Sent for Refund: A request has been made to send funds back to your customer's account.
            Sent for Cancelation: A request has been made to cancel the payment without sending it for settlement.
            Refund failed: A refund request couldn't be processed and the funds were returned to your account.
            Settlement failed: A settlement request couldn't be processed. Funds have not been transferred to your Worldpay account.
            Settled: We have received the funds and are preparing to transfer them to your bank account. This event is only available in certain use cases.
            Refunded: The card issuer has received the refund request and they will return the funds to your customer's account. This event is only available in certain use cases.
            Error: The payment wasn't completed. You may want to reattempt the payment.
            Expired: The authorization validity period ended before a settlement or cancel request was made.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic