openapi: 3.0.1
info:
  title: Payouts
  description: Payouts root resource, returns links to available payouts actions.
  version: '1'
servers:
  - url: https://try.access.worldpay.com
    description: testing (try)
  - url: https://access.worldpay.com
    description: live
paths:
  /payouts/{resource}:
    get:
      summary: Retrieve payout details
      description: >+
        Retrieve the details of an existing Basic Disbursement or Fast Access
        Payout.

      operationId: getPayoutsDetails
      parameters:
        - name: resource
          in: path
          description: original resource
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payout resource.
          content:
            application/vnd.worldpay.payouts-v1+json:
              schema:
                $ref: '#/components/schemas/payouts_payouts_200_response'
              examples:
                'Basic Disbursement: Successful resource retrieval with outcome requestReceived':
                  description: >-
                    Basic Disbursement: Successful resource retrieval with
                    outcome requestReceived
                  value:
                    outcome: requestReceived
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Basic Disbursement: Successful resource retrieval with outcome refused':
                  description: >-
                    Basic Disbursement: Successful resource retrieval with
                    outcome refused
                  value:
                    outcome: refused
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Basic Disbursement: Successful resource retrieval with outcome error':
                  description: >-
                    Basic Disbursement: Successful resource retrieval with
                    outcome error
                  value:
                    outcome: error
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Basic Disbursement: Successful resource retrieval with outcome queryRequired':
                  description: >-
                    Basic Disbursement: Successful resource retrieval with
                    outcome queryRequired
                  value:
                    outcome: queryRequired
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                      payouts:update:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access Payout: Successful resource retrieval with outcome requested':
                  description: >-
                    Fast Access Payout: Successful resource retrieval with
                    outcome requested
                  value:
                    outcome: requested
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                      payouts:update:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access Payout: Successful resource retrieval with outcome pending':
                  description: >-
                    Fast Access Payout: Successful resource retrieval with
                    outcome pending
                  value:
                    outcome: pending
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                      payouts:update:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access Payout: Successful resource retrieval with outcome approved':
                  description: >-
                    Fast Access Payout: Successful resource retrieval with
                    outcome approved
                  value:
                    outcome: approved
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                      payouts:update:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access Payout: Successful resource retrieval with outcome disbursed':
                  description: >-
                    Fast Access Payout: Successful resource retrieval with
                    outcome disbursed
                  value:
                    outcome: disbursed
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access Payout: Successful resource retrieval with outcome refused':
                  description: >-
                    Fast Access Payout: Successful resource retrieval with
                    outcome refused
                  value:
                    outcome: refused
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access Payout: Successful resource retrieval with outcome error':
                  description: >-
                    Fast Access Payout: Successful resource retrieval with
                    outcome error
                  value:
                    outcome: error
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access Payout: Successful resource retrieval with outcome queryRequired':
                  description: >-
                    Fast Access Payout: Successful resource retrieval with
                    outcome queryRequired
                  value:
                    outcome: queryRequired
                    receivedAt: '2023-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                      payouts:update:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
  /payouts/query:
    get:
      summary: Retrieve the payout details of a historic resource.
      description: |+
        Query by transaction reference and entity to retrieve a Payout.

      operationId: queryPayouts
      parameters:
        - name: transactionReference
          in: query
          description: >-
            A unique reference generated by you, used to identify a payout
            throughout its lifecycle
          required: true
          schema:
            type: string
            example: '12345'
        - name: entity
          in: query
          description: merchant entity
          required: true
          schema:
            type: string
            example: default
      responses:
        '200':
          description: >-
            Returns a payout resource, provided one matches the transaction and
            entity references.
          content:
            application/vnd.worldpay.payouts-v1+json:
              schema:
                $ref: '#/components/schemas/payouts_query_200_response'
              examples:
                'Basic Disbursement: An existing resource is retrieved with outcome ''requestReceived''':
                  description: >-
                    Basic Disbursement: An existing resource is retrieved with
                    outcome 'requestReceived'
                  value:
                    outcome: requestReceived
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Basic Disbursement: An existing resource is retrieved with outcome ''refused''':
                  description: >-
                    Basic Disbursement: An existing resource is retrieved with
                    outcome 'refused'
                  value:
                    outcome: refused
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Basic Disbursement: An existing resource is retrieved with outcome ''error''':
                  description: >-
                    Basic Disbursement: An existing resource is retrieved with
                    outcome 'error'
                  value:
                    outcome: error
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access: An existing resource is retrieved with outcome ''requested''':
                  description: >-
                    Fast Access: An existing resource is retrieved with outcome
                    'requested'
                  value:
                    outcome: requested
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access: An existing resource is retrieved with outcome ''pending''':
                  description: >-
                    Fast Access: An existing resource is retrieved with outcome
                    'pending'
                  value:
                    outcome: pending
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access: An existing resource is retrieved with outcome ''approved''':
                  description: >-
                    Fast Access: An existing resource is retrieved with outcome
                    'approved'
                  value:
                    outcome: approved
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access: An existing resource is retrieved with outcome ''disbursed''':
                  description: >-
                    Fast Access: An existing resource is retrieved with outcome
                    'disbursed'
                  value:
                    outcome: disbursed
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access: An existing resource is retrieved with outcome ''refused''':
                  description: >-
                    Fast Access: An existing resource is retrieved with outcome
                    'refused'
                  value:
                    outcome: refused
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                'Fast Access: An existing resource is retrieved with outcome ''error''':
                  description: >-
                    Fast Access: An existing resource is retrieved with outcome
                    'error'
                  value:
                    outcome: error
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
  /payouts/basicDisbursement:
    post:
      summary: Disburses funds to the payout instrument specified.
      description: |+
        Disburse funds to a payout instrument.

      operationId: basicDisbursement
      requestBody:
        content:
          application/vnd.worldpay.payouts-v1+json:
            schema:
              $ref: '#/components/schemas/payouts_basicDisbursement'
            examples:
              Successful Basic Disbursement:
                description: Successful Basic Disbursement
                value:
                  merchant:
                    entity: default
                  instruction:
                    value:
                      amount: 300
                      currency: GBP
                    payoutInstrument:
                      type: card/plain
                      cardHolderName: Sherlock Holmes
                      cardExpiryDate:
                        month: 1
                        year: 2025
                      cardNumber: '4444333322221111'
                    narrative: STATEMENT
                  transactionReference: transaction-ref
              Unsuccessful Payout request:
                description: Unsuccessful Payout request
                value:
                  merchant:
                    entity: default
                  instruction:
                    value:
                      amount: 300
                      currency: GBP
                    payoutInstrument:
                      type: card/plain
                      cardHolderName: Sherlock Holmes
                      cardExpiryDate:
                        month: 1
                        year: 2025
                      cardNumber: '4444333322221111'
                    narrative: STATEMENT
                  transactionReference: transaction-ref
              Successful Basic Disbursement with a token:
                description: Successful Basic Disbursement with a token
                value:
                  merchant:
                    entity: default
                  instruction:
                    value:
                      amount: 300
                      currency: GBP
                    payoutInstrument:
                      type: card/tokenized
                      href: https://tokens/token
                    narrative: STATEMENT
                  transactionReference: transaction-ref
      responses:
        '201':
          description: Funds have been disbursed or queued for disbursal successfully.
          content:
            application/vnd.worldpay.payouts-v1+json:
              schema:
                $ref: '#/components/schemas/payouts_basicDisbursement_201_response'
              examples:
                Successful Basic Disbursement:
                  description: Successful Basic Disbursement
                  value:
                    outcome: requestReceived
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                Unsuccessful Payout request:
                  description: Unsuccessful Payout request
                  value:
                    outcome: refused
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                Successful Basic Disbursement with a token:
                  description: Successful Basic Disbursement with a token
                  value:
                    outcome: requestReceived
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
  /payouts/fastAccess:
    post:
      summary: Disburses funds to the payout instrument specified.
      description: |+
        Disburse funds to a payout instrument using fastAccess.

      operationId: fastAccess
      requestBody:
        content:
          application/vnd.worldpay.payouts-v1+json:
            schema:
              $ref: '#/components/schemas/payouts_fastAccess'
            examples:
              Successful issuing of a disbursal request:
                description: Successful issuing of a disbursal request
                value:
                  merchant:
                    entity: default
                  instruction:
                    value:
                      amount: 300
                      currency: GBP
                    payoutInstrument:
                      type: card/plain
                      cardHolderName: Sherlock Holmes
                      cardExpiryDate:
                        month: 1
                        year: 2025
                      cardNumber: '4444333322221111'
                    narrative: STATEMENT
                  transactionReference: transaction-ref
              Successful disbursal of funds:
                description: Successful disbursal of funds
                value:
                  merchant:
                    entity: default
                  instruction:
                    value:
                      amount: 300
                      currency: GBP
                    payoutInstrument:
                      type: card/plain
                      cardHolderName: Sherlock Holmes
                      cardExpiryDate:
                        month: 1
                        year: 2025
                      cardNumber: '4444333322221111'
                    narrative: STATEMENT
                  transactionReference: transaction-ref
              Successful disbursal of funds to a token:
                description: Successful disbursal of funds to a token
                value:
                  merchant:
                    entity: default
                  instruction:
                    value:
                      amount: 300
                      currency: GBP
                    payoutInstrument:
                      type: card/tokenized
                      href: https://tokens/token
                    narrative: STATEMENT
                  transactionReference: transaction-ref
      responses:
        '201':
          description: Funds have been disbursed or queued for disbursal successfully.
          content:
            application/vnd.worldpay.payouts-v1+json:
              schema:
                $ref: '#/components/schemas/payouts_fastAccess_201_response'
              examples:
                Successful issuing of a disbursal request:
                  description: Successful issuing of a disbursal request
                  value:
                    outcome: pending
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                Successful disbursal of funds:
                  description: Successful disbursal of funds
                  value:
                    outcome: approved
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
                Successful disbursal of funds to a token:
                  description: Successful disbursal of funds to a token
                  value:
                    outcome: approved
                    receivedAt: '2018-09-01T10:37:36.923Z'
                    _links:
                      payouts:payout:
                        href: https://try.access.worldpay.com/payouts/{resource}
                    curies:
                      - name: payouts
                        href: https://try.access.worldpay.com/rels/payouts/{rel}
                        templated: true
components:
  schemas:
    payouts_payouts_200_response:
      required:
        - _links
        - curies
        - outcome
        - receivedAt
      type: object
      properties:
        curies:
          required:
            - href
            - name
            - templated
          type: array
          items:
            required:
              - href
              - name
              - templated
            type: object
            properties:
              href:
                type: string
              name:
                type: string
              templated:
                type: boolean
        outcome:
          type: string
          description: outcome of payouts request
        receivedAt:
          type: string
          description: A timestamp of receivedAt
    payouts_query_200_response:
      required:
        - _links
        - curies
        - outcome
        - receivedAt
      type: object
      properties:
        curies:
          required:
            - href
            - name
            - templated
          type: array
          items:
            required:
              - href
              - name
              - templated
            type: object
            properties:
              href:
                type: string
              name:
                type: string
              templated:
                type: boolean
        outcome:
          type: string
          description: outcome of payouts query request
        receivedAt:
          type: string
          description: A timestamp of receivedAt
    card_plain:
      required:
        - cardExpiryDate
        - cardHolderName
        - cardNumber
        - type
      type: object
      description: Plain card details.
      properties:
        cardExpiryDate:
          required:
            - month
            - year
          type: object
          description: >-
            An object that contains your customer's payout card expiry date.
            Must be a date in the future.
          properties:
            month:
              type: integer
            year:
              type: integer
        cardHolderName:
          type: string
          description: An object that contains your customer's payout card name.
        cardNumber:
          type: string
          description: An object that contains your customer's payout card number.
        type:
          type: string
    card_tokenized:
      required:
        - href
        - type
      type: object
      description: Tokenized card details.
      properties:
        href:
          type: string
          description: An object that contains your link to an Access Token.
        type:
          type: string
    payouts_basicDisbursement:
      required:
        - instruction
        - merchant
        - transactionReference
      type: object
      properties:
        instruction:
          required:
            - narrative
            - payoutInstrument
            - value
          type: object
          description: Basic disbursement input.
          properties:
            narrative:
              type: string
              description: >-
                An object that contains all the information related to your
                payout request.
            payoutInstrument:
              description: An object that contains your customer's payout type.
              oneOf:
                - $ref: '#/components/schemas/card_plain'
                - $ref: '#/components/schemas/card_tokenized'
              discriminator:
                mapping:
                  card/plain: '#/components/schemas/card_plain'
                  card/tokenized: '#/components/schemas/card_tokenized'
                propertyName: type
            value:
              required:
                - amount
                - currency
              type: object
              description: An object that contains payout amount and currency.
              properties:
                amount:
                  type: integer
                  description: The payout amount.
                currency:
                  type: string
                  description: The 3 digit currency code.
        merchant:
          required:
            - entity
          type: object
          description: An object that contains information about the merchant.
          properties:
            entity:
              type: string
              description: >-
                This is mandatory for authentication and queries. Contact your
                Implementation Manager for more information.
        transactionReference:
          type: string
          description: >-
            A unique reference generated by you, used to identify a payout
            throughout its lifecycle.
    payouts_basicDisbursement_201_response:
      required:
        - _links
        - curies
        - outcome
        - receivedAt
      type: object
      properties:
        curies:
          required:
            - href
            - name
            - templated
          type: array
          items:
            required:
              - href
              - name
              - templated
            type: object
            properties:
              href:
                type: string
              name:
                type: string
              templated:
                type: boolean
        outcome:
          type: string
          description: outcome of payouts request
        receivedAt:
          type: string
          description: A timestamp of receivedAt
    payouts_fastAccess:
      required:
        - instruction
        - merchant
        - transactionReference
      type: object
      description: Fast access input.
      properties:
        instruction:
          required:
            - narrative
            - payoutInstrument
            - value
          type: object
          description: >-
            An object that contains all the information related to your payout
            request.
          properties:
            narrative:
              type: string
            payoutInstrument:
              description: An object that contains your customer's payout type.
              oneOf:
                - $ref: '#/components/schemas/card_plain'
                - $ref: '#/components/schemas/card_tokenized'
              discriminator:
                mapping:
                  card/plain: '#/components/schemas/card_plain'
                  card/tokenized: '#/components/schemas/card_tokenized'
                propertyName: type
            value:
              required:
                - amount
                - currency
              type: object
              description: An object that contains payout amount and currency.
              properties:
                amount:
                  type: integer
                  description: The payout amount.
                currency:
                  type: string
                  description: The 3 digit currency code.
        merchant:
          required:
            - entity
          type: object
          description: An object that contains information about the merchant.
          properties:
            entity:
              type: string
              description: >-
                This is mandatory for authentication and queries. Contact your
                Implementation Manager for more information.
        transactionReference:
          type: string
          description: >-
            A unique reference generated by you, used to identify a payout
            throughout its lifecycle.
    payouts_fastAccess_201_response:
      required:
        - _links
        - curies
        - outcome
        - receivedAt
      type: object
      properties:
        curies:
          required:
            - href
            - name
            - templated
          type: array
          items:
            required:
              - href
              - name
              - templated
            type: object
            properties:
              href:
                type: string
              name:
                type: string
              templated:
                type: boolean
        outcome:
          type: string
          description: outcome of payouts request
        receivedAt:
          type: string
          description: A timestamp of receivedAt
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
security:
  - BasicAuth: []
