Worldpay Update API

openapi: 3.2.0
info:
  title: FraudSight Update API
  description: Request a risk assessment and prevent fraud with this standalone API.
  version: v1
  x-metadata:
    category:
    - Risk Assessments
    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: Update
paths:
  /fraudsight/update/payment:
    post:
      tags:
      - Update
      summary: Provide details of the payment outcome
      description: 'Provide payment outcome information.


        __Note:__ This should only be provided if using a different gateway for the payment.'
      operationId: updatePayment
      parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.fraudsight-v1.hal+json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.fraudsight-v1.hal+json
      requestBody:
        content:
          application/vnd.worldpay.fraudsight-v1.hal+json:
            schema:
              $ref: '#/components/schemas/fraudsight_updatePayment'
            examples:
              authorized:
                $ref: '#/components/examples/payment-request-authorized'
              refused:
                $ref: '#/components/examples/payment-request-refused'
      responses:
        '204':
          description: Successful update with payment information
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              examples:
                Payment outcome details are provided to the fraudsight service:
                  description: Payment outcome details are provided to the fraudsight service
                  value: {}
        '400':
          description: Update payment request contains invalid values
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              schema:
                $ref: '#/components/schemas/fraudsight_updatePayment_400_response'
              examples:
                An update payment request with invalid value in request body:
                  description: An update payment request with empty `authentication.eci`
                  value:
                    errorName: bodyDoesNotMatchSchema
                    validationErrors:
                    - errorName: stringIsTooShort
                      message: Authentication eci must be 2 characters long
                      jsonPath: $.authentication.eci
                    - errorName: fieldHasInvalidValue
                      message: Authentication eci must be a valid string
                      jsonPath: $.authentication.eci
                    message: The json body provided does not match the expected schema
                An update payment request using invalid http method:
                  description: An update payment request using GET method instead of POST
                  value:
                    errorName: methodNotAllowed
                    message: method GET not allowed for this request
                An update payment request with invalid JSON:
                  description: An update payment request with invalid JSON
                  value:
                    errorName: bodyIsNotJson
                    message: Request contained invalid json
        '401':
          description: Update payment request is unauthorized
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              schema:
                $ref: '#/components/schemas/fraudsight_updatePayment_401_response'
              examples:
                An update payment request with invalid Authorization header:
                  description: An update payment request using invalid Authorization header
                  value:
                    errorName: unAuthorized
                    message: Invalid access token
  /fraudsight/update/fraud:
    post:
      tags:
      - Update
      summary: Provide details of a payment that resulted in fraud
      description: Provide payment fraud information.
      operationId: updateFraud
      parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.fraudsight-v1.hal+json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.fraudsight-v1.hal+json
      requestBody:
        content:
          application/vnd.worldpay.fraudsight-v1.hal+json:
            schema:
              $ref: '#/components/schemas/fraudsight_updateFraud'
            examples:
              Provide details of a payment that resulted in fraud:
                $ref: '#/components/examples/fraud-request'
      responses:
        '204':
          description: Successful update with fraud information
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              examples:
                Provide details of a payment that resulted in fraud:
                  description: Provide details of a payment that resulted in fraud
                  value: {}
        '400':
          description: Update fraud request contains invalid values
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              schema:
                $ref: '#/components/schemas/fraudsight_updateFraud_400_response'
              examples:
                An update fraud request with invalid value in request body:
                  description: An update fraud request with empty `acquirerReference`
                  value:
                    errorName: bodyDoesNotMatchSchema
                    validationErrors:
                    - errorName: stringIsTooShort
                      message: Acquirer reference must be between 1 and 128 characters inclusive
                      jsonPath: $.acquirerReference
                    message: The json body provided does not match the expected schema
                An update fraud request using invalid http method:
                  description: An update fraud request using GET method instead of POST
                  value:
                    errorName: methodNotAllowed
                    message: method GET not allowed for this request
                An update fraud request with invalid header:
                  description: An update fraud request with "Content-Type" header of `null`
                  value:
                    errorName: headerHasInvalidValue
                    message: A valid 'Content-Type' header must be provided
        '401':
          description: Update fraud request is unauthorized
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              schema:
                $ref: '#/components/schemas/fraudsight_updateFraud_401_response'
              examples:
                An update fraud request with invalid Authorization header:
                  description: An update fraud request using invalid Authorization header
                  value:
                    errorName: unAuthorized
                    message: Invalid access token
  /fraudsight/update/chargeback:
    post:
      tags:
      - Update
      summary: Provide details of a payment that resulted in a chargeback
      description: Provide payment chargeback information.
      operationId: updateChargeback
      parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.fraudsight-v1.hal+json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          example: application/vnd.worldpay.fraudsight-v1.hal+json
      requestBody:
        content:
          application/vnd.worldpay.fraudsight-v1.hal+json:
            schema:
              $ref: '#/components/schemas/fraudsight_updateChargeback'
            examples:
              Provide details of a payment that resulted in a chargeback (fraud):
                $ref: '#/components/examples/chargeback-request'
      responses:
        '204':
          description: Successful update with chargeback information
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              examples:
                Provide details of a payment that resulted in a chargeback:
                  description: Provide details of a payment that resulted in a chargeback
                  value: {}
        '400':
          description: Update payment request contains invalid values
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              schema:
                $ref: '#/components/schemas/fraudsight_updateChargeback_400_response'
              examples:
                An update chargeback request with invalid value in request body:
                  description: An update chargeback request with empty `acquirerReference`
                  value:
                    errorName: bodyDoesNotMatchSchema
                    validationErrors:
                    - errorName: stringIsTooShort
                      message: Acquirer reference must be between 1 and 128 characters inclusive
                      jsonPath: $.acquirerReference
                    message: The json body provided does not match the expected schema
                An update chargeback request using invalid http method:
                  description: An update chargeback request using GET method instead of POST
                  value:
                    errorName: methodNotAllowed
                    message: method GET not allowed for this request
                An update chargeback request with invalid JSON:
                  description: An update chargeback request with invalid JSON
                  value:
                    errorName: bodyIsNotJson
                    message: Request contained invalid json
        '401':
          description: Update chargeback request is unauthorized
          content:
            application/vnd.worldpay.fraudsight-v1.hal+json:
              schema:
                $ref: '#/components/schemas/fraudsight_updateChargeback_401_response'
              examples:
                An update chargeback request with invalid Authorization header:
                  description: An update chargeback request using invalid Authorization header
                  value:
                    errorName: unAuthorized
                    message: Invalid access token
components:
  schemas:
    fraudsight_updateChargeback:
      required:
      - transactionReference
      - merchant
      - riskProfile
      - sourceDate
      - acquirerReference
      - chargebackReasonCode
      - chargebackCaseReference
      - chargebackValue
      type: object
      properties:
        transactionReference:
          $ref: '#/components/schemas/transactionReference'
        merchant:
          required:
          - entity
          type: object
          description: An object that contains information about the merchant and API level configuration.
          properties:
            entity:
              $ref: '#/components/schemas/entity'
        riskProfile:
          maxLength: 2048
          minLength: 39
          type: string
          format: uri
          description: Represents the outcome of the original fraud assessment. Used to link subsequent fraud related requests.
        sourceDate:
          maxLength: 20
          type: string
          format: date-time
          description: Date/time of source fraud file (TC40/SAFE).
        acquirerReference:
          maxLength: 128
          minLength: 1
          type: string
          description: Acquirer Reference Number (ARN) - unique value assigned to a credit or debit card transaction.
        chargebackReasonCode:
          maxLength: 4
          minLength: 2
          type: string
          description: Visa and Mastercard reason codes.
        chargebackCaseReference:
          maxLength: 64
          minLength: 1
          type: string
          description: Case reference for a specific chargeback.
        chargebackValue:
          required:
          - amount
          - currency
          type: object
          description: Object containing value of the chargeback transaction.
          properties:
            amount:
              maximum: 999999999
              minimum: 0
              type: integer
              description: The chargeback amount. This is a whole number with an exponent, e.g. if exponent is two, 250 is 2.50.
            currency:
              maxLength: 3
              minLength: 3
              pattern: ^[A-Z]{3}$
              type: string
              description: The three digit currency code.
    fraudsight_updateFraud:
      required:
      - transactionReference
      - merchant
      - riskProfile
      - source
      - sourceDate
      - acquirerReference
      - fraudReasonCode
      - value
      type: object
      properties:
        transactionReference:
          $ref: '#/components/schemas/transactionReference'
        merchant:
          required:
          - entity
          type: object
          description: An object that contains information about the merchant and API level configuration.
          properties:
            entity:
              $ref: '#/components/schemas/entity'
        riskProfile:
          maxLength: 2048
          minLength: 39
          type: string
          format: uri
          description: Represents the outcome of the original fraud assessment. Used to link subsequent Fraud related requests.
        source:
          enum:
          - SAFE
          - TC40
          type: string
          description: Source format of confirmed fraud cases.
        sourceDate:
          maxLength: 20
          type: string
          format: date-time
          description: Date/time of source fraud file (TC40/SAFE).
        acquirerReference:
          maxLength: 128
          minLength: 1
          type: string
          description: Acquirer Reference Number (ARN) - unique value assigned to a credit or debit card transaction.
        fraudReasonCode:
          maxLength: 16
          minLength: 1
          type: string
          description: 'Visa and Mastercard reason codes:


            | FraudReasonCode | FraudReasonDescription                |   |   |   |

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

            | 00              | Lost                                  |   |   |   |

            | 01              | Stolen                                |   |   |   |

            | 02              | Card not received                     |   |   |   |

            | 03              | Fraudulent application                |   |   |   |

            | 04              | Counterfeit                           |   |   |   |

            | 05              | Account Takeover                      |   |   |   |

            | 06              | Cardholder not present                |   |   |   |

            | 07              | Imprinting of multiple sale drafts    |   |   |   |

            | 08              | Other                                 |   |   |   |

            | 900             | Lost                                  |   |   |   |

            | 901             | Stolen                                |   |   |   |

            | 902             | Card not received                     |   |   |   |

            | 903             | Fraudulent application                |   |   |   |

            | 904             | Counterfeit                           |   |   |   |

            | 905             | Account Takeover                      |   |   |   |

            | 906             | Cardholder not present                |   |   |   |

            | 907             | Imprinting of multiple sale drafts    |   |   |   |

            | 908             | Other                                 |   |   |   |

            | 908             | Other                                 |   |   |   |

            | 919             | Other                                 |   |   |   |

            | A               | Incorrect Processing                  |   |   |   |

            | B               | Account or Credentials Takeover Fraud |   |   |   |'
        value:
          $ref: '#/components/schemas/value'
    value:
      required:
      - amount
      - currency
      type: object
      description: An object that contains information about the value of the assessment.
      properties:
        amount:
          maximum: 99999999999
          minimum: 0
          type: integer
          description: The authentication amount. This is a whole number with an exponent, e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our [currency table](/products/reference/supported-countries-currencies#iso-currency-codes). The assessment amount should be equal to the authorization amount. We recommend you delay assessment until the amount is known, or ensure it's greater than the total transaction amount.
        currency:
          maxLength: 3
          minLength: 3
          pattern: ^[A-Z]{3}$
          type: string
          description: The three digit currency code. See list of [supported currencies](/products/reference/supported-countries-currencies#iso-currency-codes).
    fraudsight_updateFraud_400_response:
      required:
      - message
      - errorName
      type: object
      properties:
        message:
          type: string
          maxLength: 2048
          minLength: 1
          description: The error description message.
        errorName:
          type: string
          maxLength: 2048
          minLength: 1
          description: The unique error name
        validationErrors:
          description: Object containing details of validation errors occurred.
          type: array
          items:
            $ref: '#/components/schemas/validation_errors'
    transactionReference:
      maxLength: 64
      minLength: 1
      pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
      type: string
      description: A unique reference for authentication. For example, e-commerce order code.
    fraudsight_updateFraud_401_response:
      required:
      - message
      - errorName
      type: object
      properties:
        message:
          type: string
          maxLength: 2048
          minLength: 1
          description: The error description message.
        errorName:
          type: string
          maxLength: 2048
          minLength: 1
          description: The unique error name.
    entity:
      maxLength: 64
      minLength: 1
      pattern: ^[A-Za-z0-9 ]*$
      type: string
      description: Used to route the request in Access Worldpay, created as part of on-boarding.
    fraudsight_updatePayment_401_response:
      required:
      - message
      - errorName
      type: object
      properties:
        message:
          type: string
          maxLength: 2048
          minLength: 1
          description: The error description message.
        errorName:
          type: string
          maxLength: 2048
          minLength: 1
          description: The unique error name.
    fraudsight_updatePayment_400_response:
      required:
      - message
      - errorName
      type: object
      properties:
        message:
          type: string
          maxLength: 2048
          minLength: 1
          description: The error description message.
        errorName:
          type: string
          maxLength: 2048
          minLength: 1
          description: The unique error name.
        validationErrors:
          description: Object containing details of validation errors occurred
          type: array
          items:
            $ref: '#/components/schemas/validation_errors'
    fraudsight_updateChargeback_400_response:
      required:
      - message
      - errorName
      type: object
      properties:
        message:
          type: string
          maxLength: 2048
          minLength: 1
          description: The error description message.
        errorName:
          type: string
          maxLength: 2048
          minLength: 1
          description: The unique error name.
        validationErrors:
          description: Object containing details of validation errors occurred.
          type: array
          items:
            $ref: '#/components/schemas/validation_errors'
    fraudsight_updateChargeback_401_response:
      required:
      - message
      - errorName
      type: object
      properties:
        message:
          type: string
          maxLength: 2048
          minLength: 1
          description: The error description message.
        errorName:
          type: string
          maxLength: 2048
          minLength: 1
          description: The unique error name.
    fraudsight_updatePayment:
      required:
      - transactionReference
      - merchant
      - riskProfile
      - paymentOutcome
      type: object
      properties:
        transactionReference:
          $ref: '#/components/schemas/transactionReference'
        merchant:
          required:
          - entity
          type: object
          description: An object that contains information about the merchant and API level configuration.
          properties:
            entity:
              $ref: '#/components/schemas/entity'
        riskProfile:
          maxLength: 2048
          minLength: 39
          type: string
          format: uri
          description: Represents the outcome of the original fraud assessment. Used to link subsequent Fraud related requests.
        paymentOutcome:
          enum:
          - authorized
          - refused
          type: string
          description: Outcome of the payment authorization.
        refusalCode:
          type: string
          maxLength: 2048
          minLength: 1
          description: The refusal response code from the acquirer.
          example: '5'
        refusalDescription:
          type: string
          maxLength: 2048
          minLength: 1
          description: The description of the 'refusalCode'.
          example: REFUSED
        cvcResult:
          enum:
          - matched
          - not_matched
          - not_checked
          - not_supplied
          type: string
          description: Outcome of the CVC check.
        avsResult:
          type: object
          description: Object containing outcome of the address verification service check.
          properties:
            address:
              enum:
              - matched
              - not_matched
              - not_checked
              - not_supplied
              type: string
              description: Outcome of the address check.
            postcode:
              enum:
              - matched
              - not_matched
              - not_checked
              - not_supplied
              type: string
              description: Outcome of the postcode check.
        authentication:
          type: object
          description: Include this object if 3DS authentication details were part of the payment.
          properties:
            version:
              maxLength: 10
              minLength: 5
              pattern: ^([0-9]{1,3})(\.)([0-9]){1,3}(\.)([0-9]{1,3})*$
              type: string
              description: 3DS version used by issuer, e.g. `1.0.2`, `2.1.0` or `2.2.0`.
            eci:
              maxLength: 2
              minLength: 2
              enum:
              - '00'
              - '01'
              - '02'
              - '05'
              - '06'
              - '07'
              type: string
              description: "Electronic Commerce Indicator (ECI). Outcome of the 3DS authentication as applied in the payment.\n  - 02 or 05 - Fully Authenticated Transaction\n  - 01 or 06 - Attempted Authentication Transaction\n  - 00 or 07 - Non 3-D Secure Transaction\n  - Mastercard - 02, 01, 00\n  - Visa - 05, 06, 07\n  - Amex - 05, 06, 07\n  - JCB - 05, 06, 07\n  - Diners - 05, 06, 07\n"
    validation_errors:
      type: object
      required:
      - errorName
      - jsonPath
      - message
      properties:
        errorName:
          maxLength: 2048
          minLength: 1
          type: string
          description: Unique name of the validation error.
        jsonPath:
          maxLength: 2048
          minLength: 1
          type: string
          description: Location of the field in request body for which the error occurred.
        message:
          maxLength: 2048
          minLength: 1
          type: string
          description: Error description message.
  examples:
    payment-request-authorized:
      description: Authorized payment outcome details are provided to the FraudSight service. This could be from any Worldpay or 3rd party payment provider.
      value:
        transactionReference: Memory265-13/08/1876
        merchant:
          entity: default
        riskProfile: https://access.worldpay.com/riskprofile/ewogICJ2ZXJzaW9uIiA6IDEsCiAgImtleSIgOiAxLAogICJkYXRhIiA6ICJ5d1NnSzMwYnNGZXVYalR0QUJ0QWdnT3UvK3VhcktrL3c1dCtmSFd4dUFXRmVMZUpuM0MyaEtnYnZlZEdnbGtRY1h4LzltN1pSZGVXZWRBQ1ZvTmxZdFNiZUxaSmFrZXZxenVndFQ2bG44NkpNTW5CeGJSRFVWWWY3dTd5SXVuVFJLK0NYZS9tODRkaHdTUWVnZlYyYTRCb1RaQVNKK0RpcGpmYUxkK1lETlJFclVyZ1c0TGIvOGhvNnFzbFVBU0dSem8zRVRkMEdIUTZXZ1dIT2t1UVBabUF1NXZuVFdBeGZrSEQ5SkdrT1BoV1pMMmIyZm9yNWNOMzZvWUhOY2dkT0lKdkhNMEg5TG1oRDM1RXA4T3R2WWptVmNXS25FZmtLZ0RrK09KRDNLb2pobG
        paymentOutcome: authorized
        cvcResult: matched
        avsResult:
          address: matched
          postcode: matched
        authentication:
          version: 2.1.0
          eci: '05'
    payment-request-refused:
      description: Refusal payment outcome details are provided to the FraudSight service. This could be from any Worldpay or 3rd party payment provider
      value:
        transactionReference: Memory265-13/08/1876
        merchant:
          entity: default
        riskProfile: https://access.worldpay.com/riskprofile/ewogICJ2ZXJzaW9uIiA6IDEsCiAgImtleSIgOiAxLAogICJkYXRhIiA6ICJ5d1NnSzMwYnNGZXVYalR0QUJ0QWdnT3UvK3VhcktrL3c1dCtmSFd4dUFXRmVMZUpuM0MyaEtnYnZlZEdnbGtRY1h4LzltN1pSZGVXZWRBQ1ZvTmxZdFNiZUxaSmFrZXZxenVndFQ2bG44NkpNTW5CeGJSRFVWWWY3dTd5SXVuVFJLK0NYZS9tODRkaHdTUWVnZlYyYTRCb1RaQVNKK0RpcGpmYUxkK1lETlJFclVyZ1c0TGIvOGhvNnFzbFVBU0dSem8zRVRkMEdIUTZXZ1dIT2t1UVBabUF1NXZuVFdBeGZrSEQ5SkdrT1BoV1pMMmIyZm9yNWNOMzZvWUhOY2dkT0lKdkhNMEg5TG1oRDM1RXA4T3R2WWptVmNXS25FZmtLZ0RrK09KRDNLb2pobG
        paymentOutcome: refused
        refusalCode: '5'
        refusalDescription: REFUSED
        cvcResult: matched
        avsResult:
          address: matched
          postcode: matched
        authentication:
          version: 2.1.0
          eci: '05'
    chargeback-request:
      description: Chargeback (fraud) information provided to the FraudSight service. This could be from any Worldpay or 3rd party payment provider
      value:
        transactionReference: Memory265-13/08/1876
        merchant:
          entity: default
        riskProfile: https://access.worldpay.com/riskprofile/ewogICJ2ZXJzaW9uIiA6IDEsCiAgImtleSIgOiAxLAogICJkYXRhIiA6ICJ5d1NnSzMwYnNGZXVYalR0QUJ0QWdnT3UvK3VhcktrL3c1dCtmSFd4dUFXRmVMZUpuM0MyaEtnYnZlZEdnbGtRY1h4LzltN1pSZGVXZWRBQ1ZvTmxZdFNiZUxaSmFrZXZxenVndFQ2bG44NkpNTW5CeGJSRFVWWWY3dTd5SXVuVFJLK0NYZS9tODRkaHdTUWVnZlYyYTRCb1RaQVNKK0RpcGpmYUxkK1lETlJFclVyZ1c0TGIvOGhvNnFzbFVBU0dSem8zRVRkMEdIUTZXZ1dIT2t1UVBabUF1NXZuVFdBeGZrSEQ5SkdrT1BoV1pMMmIyZm9yNWNOMzZvWUhOY2dkT0lKdkhNMEg5TG1oRDM1RXA4T3R2WWptVmNXS25FZmtLZ0RrK09KRDNLb2pobG
        sourceDate: '2020-12-27T00:00:00Z'
        acquirerReference: 02691780344910023278387
        chargebackReasonCode: '31'
        chargebackCaseReference: '123456'
        chargebackValue:
          currency: GBP
          amount: 250
    fraud-request:
      description: TC40/SAFE fraud information provided to the FraudSight service. This could be from any Worldpay or 3rd party payment provider.
      value:
        transactionReference: Memory265-13/08/1876
        merchant:
          entity: default
        riskProfile: https://access.worldpay.com/riskprofile/ewogICJ2ZXJzaW9uIiA6IDEsCiAgImtleSIgOiAxLAogICJkYXRhIiA6ICJ5d1NnSzMwYnNGZXVYalR0QUJ0QWdnT3UvK3VhcktrL3c1dCtmSFd4dUFXRmVMZUpuM0MyaEtnYnZlZEdnbGtRY1h4LzltN1pSZGVXZWRBQ1ZvTmxZdFNiZUxaSmFrZXZxenVndFQ2bG44NkpNTW5CeGJSRFVWWWY3dTd5SXVuVFJLK0NYZS9tODRkaHdTUWVnZlYyYTRCb1RaQVNKK0RpcGpmYUxkK1lETlJFclVyZ1c0TGIvOGhvNnFzbFVBU0dSem8zRVRkMEdIUTZXZ1dIT2t1UVBabUF1NXZuVFdBeGZrSEQ5SkdrT1BoV1pMMmIyZm9yNWNOMzZvWUhOY2dkT0lKdkhNMEg5TG1oRDM1RXA4T3R2WWptVmNXS25FZmtLZ0RrK09KRDNLb2pobG
        source: TC40
        sourceDate: '2020-12-27T00:00:00Z'
        acquirerReference: 02691780344910023278387
        fraudReasonCode: '5'
        value:
          currency: GBP
          amount: 250
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic