Worldpay Manage payments API

openapi: 3.0.1
info:
  title: 3DS 3DS actions Manage payments 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: Manage payments
paths:
  /payments/settlements/{linkData}:
    post:
      tags:
      - Manage payments
      summary: Settle for full amount
      description: To receive all the funds from the customer, send us a settle request.
      operationId: settle
      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
      requestBody:
        content:
          application/vnd.worldpay.payments-v7+json:
            schema:
              $ref: '#/components/schemas/payments_settle'
            examples:
              Request to fully settle the authorization:
                description: Request to settle the authorization
      responses:
        '202':
          description: The payment settlement has been accepted
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/payments_fullSettle_response'
              examples:
                Response to fully settle the authorization:
                  description: Response to fully settle the authorization
                  value:
                    paymentId: payT7hS-8vS4h_95A2f7905v0
                    commandId: cmdp9D1t-ENYQxVnJkh0iPRC0
                    _links:
                      cardPayments:refund:
                        href: /payments/settlements/refunds/full/:linkData
                      cardPayments:partialRefund:
                        href: /payments/settlements/refunds/partials/:linkData
                      cardPayments:reverse:
                        href: /payments/authorizations/reversals/:linkData
                      cardPayments:events:
                        href: /payments/events/: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:
            aapplication/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/settlements/partials/{linkData}:
    post:
      tags:
      - Manage payments
      summary: Settle for partial amount
      description: To receive a portion of the funds of a payment, send us a partial settle request.
      operationId: partialSettlement
      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
      requestBody:
        content:
          application/vnd.worldpay.payments-v7+json:
            schema:
              $ref: '#/components/schemas/payments_partialSettle'
            examples:
              Request to partially settle the authorization:
                description: Request to partially settle the authorization
                value:
                  sequence:
                    number: 1
                    total: 2
                  value:
                    amount: 500
                    currency: EUR
                  reference: partial-settle-reference
              Request to partially settle the authorization, with marketplace seller country code:
                description: Request to partially settle the authorization
                value:
                  sequence:
                    number: 1
                    total: 2
                  value:
                    amount: 500
                    currency: EUR
                  reference: partial-settle-reference
                  merchant:
                    marketplace:
                      sellerCountryCode: FR
              Request to partially settle the authorization, with a split funding reference:
                description: Request to partially settle the authorization
                value:
                  sequence:
                    number: 1
                    total: 2
                  value:
                    amount: 500
                    currency: EUR
                  reference: partial-settle-reference
                  merchant:
                    marketplace:
                      splitFundingReference: my split funding ref
      responses:
        '202':
          description: The partial settlement has been accepted
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/payments_partialSettle_response'
              examples:
                Response to partially settle the authorization:
                  description: Response to partially settle the authorization
                  value:
                    paymentId: payI-dUcet9fk4_X4qZU0hpU0
                    commandId: cmdwZ5y_rSi1VmjD6CpgCuXG0
                    _links:
                      cardPayments:refund:
                        href: /payments/settlements/refunds/full/:linkData
                      cardPayments:partialRefund:
                        href: /payments/settlements/refunds/partials/:linkData
                      cardPayments:partialSettle:
                        href: /payments/settlements/partials/:linkData
                      cardPayments:reverse:
                        href: /payments/authorizations/reversals/:linkData
                      cardPayments:cancel:
                        href: /payments/authorizations/cancellations/:linkData
                      cardPayments:events:
                        href: /payments/events/: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/settlements/refunds/full/{linkData}:
    post:
      tags:
      - Manage payments
      summary: Refund full amount
      description: "Send a refund request to return the full settled amount to your customer.\n\n  **Note:** No request body is needed for this request."
      operationId: refund
      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
      requestBody:
        content:
          application/vnd.worldpay.payments-v7+json:
            schema:
              $ref: '#/components/schemas/payments_refund'
      responses:
        '202':
          description: The refund request has been accepted
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/payments_fullRefund_response'
              examples:
                Response to refund an authorization:
                  description: Response to refund an authorization
                  value:
                    paymentId: payI-dUcet9fk4_X4qZU0hpU0
                    commandId: cmdwZ5y_rSV1VmjD6CpgCuXG0
                    _links:
                      cardPayments:events:
                        href: /payments/events/: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/settlements/refunds/partials/{linkData}:
    post:
      tags:
      - Manage payments
      summary: Refund partial amount
      description: "Send a partial refund request to return a portion of the settled amount to your customer.\n Send the amount to refund and the authorization currency in the body."
      operationId: partialRefund
      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
      requestBody:
        content:
          application/vnd.worldpay.payments-v7+json:
            schema:
              $ref: '#/components/schemas/payments_partialRefund'
            examples:
              Request to perform a partial refund of the settlement:
                description: Request to perform a partial refund of the settlement
                value:
                  value:
                    amount: 10
                    currency: EUR
                  reference: partial-refund-reference
              Request to perform a partial refund of the settlement, with a split funding reference:
                description: Request to perform a partial refund of the settlement
                value:
                  value:
                    amount: 500
                    currency: EUR
                  reference: partial-refund-reference
                  merchant:
                    marketplace:
                      splitFundingReference: my split funding ref
      responses:
        '202':
          description: The partial refund has been accepted
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/payments_partialRefund_response'
              examples:
                Response to partially refund an authorization:
                  description: Response to partially refund an authorization
                  value:
                    paymentId: payI-dUcet9fk4_X4qZU0hpU0
                    commandId: cmdwZ5y_rSV1VmjD6CpgCuXG0
                    _links:
                      cardPayments:events:
                        href: /payments/events/: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/authorizations/cancellations/{linkData}:
    post:
      tags:
      - Manage payments
      summary: Cancel full authorization
      description: "If you don't want to proceed with a payment, you can send a full cancel request.\n\n **Note:** You can only cancel a payment which is authorized. If the payment is settled, you must create a refund."
      operationId: cancel
      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
      requestBody:
        content:
          application/vnd.worldpay.payments-v7+json:
            schema:
              $ref: '#/components/schemas/payments_cancel'
      responses:
        '202':
          description: The cancellation request has been accepted
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/payments_fullCancel_response'
              examples:
                Response to cancel an authorization:
                  description: Response to cancel an authorization
                  value:
                    _links:
                      cardPayments:events:
                        href: /payments/events/: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/authorizations/cancellations/partials/{linkData}:
    post:
      tags:
      - Manage payments
      summary: Cancel partial authorization
      description: "If you don't want to proceed with a payment, you can send a partial cancel request.\n\n  **Note:** You can only cancel a payment which is authorized. If the payment is settled, you must create a refund."
      operationId: partialCancel
      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
      requestBody:
        content:
          application/vnd.worldpay.payments-v7+json:
            schema:
              $ref: '#/components/schemas/payments_partialCancel'
            examples:
              Request to partially settle the authorization:
                description: Request to partially cancel the authorization
                value:
                  value:
                    amount: 500
                    currency: EUR
                  reference: partial-cancel-reference
      responses:
        '202':
          description: The partial cancellation request has been accepted
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                $ref: '#/components/schemas/payments_partialCancel_response'
              examples:
                Response to cancel partial authorization:
                  description: Response to cancel an authorization
                  value:
                    _links:
                      cardPayments:events:
                        href: /payments/events/:linkData
                      cardPayments:partialCancel:
                        href: /payments/authorizations/cancellations/partials/:linkData
                      cardPayments:partialSettle:
                        href: /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/authorizations/incrementalAuthorizations/{linkData}:
    post:
      tags:
      - Manage payments
      summary: Increase authorization amount
      description: "If you want to increase an initial estimated authorization amount (submitted with `estimated` set to `true`), you can send a incremental authorization request.\n\n **Note:** You must use the latest next action links returned by the incremental authorization response to settle (full/partial) and cancel (full/partial) the increased authorized amount. Using the next action links returned in your estimated authorization response will not use any increased amounts."
      operationId: increaseAuthorize
      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
      requestBody:
        content:
          application/vnd.worldpay.payments-v7+json:
            schema:
              $ref: '#/components/schemas/payments_increaseAuthorize'
            examples:
              Request to partially settle the authorization:
                description: Request to increase the initial estimated authorization
                value:
                  value:
                    amount: 500
                    currency: EUR
      responses:
        '202':
          description: The request to increase the authorization amount has been successfully processed
          content:
            application/vnd.worldpay.payments-v7+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/payments_increaseAuthorize_response'
                - $ref: '#/components/schemas/payments_increaseAuthorize_response_refused'
                discriminator:
                  mapping:
                    authorized: '#/components/schemas/payments_increaseAuthorize_response'
                    refused: '#/components/schemas/payments_increaseAuthorize_response_refused'
                  propertyName: outcome
              examples:
                Successful response to increase the authorization amount:
                  description: Successful response to increase an estimated authorization amount
                  value:
                    outcome: authorized
                    amounts:
                      totalAuthorized: 1100
                      currency: EUR
                    issuer:
                      authorizationCode: T91252
                    scheme:
                      reference: MCCRU3I5U0701
    

# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-manage-payments-api-openapi.yml