Adyen submitThirdParty API

openapi: 3.2.0
info:
  version: '68'
  x-publicVersion: true
  title: Adyen Payout Submit Third Party API
  description: "A set of API endpoints that allow you to store payout details, confirm, or decline a payout.\n\nFor more information, refer to [Online payouts](https://docs.adyen.com/online-payments/online-payouts).\n## Authentication\nTo use the Payout API, you need to have [two API credentials](https://docs.adyen.com/online-payments/online-payouts#payouts-to-bank-accounts-and-wallets): one for storing payout details and submitting payouts, and another one for confirming or declining payouts. If you don't have the required API credentials, contact our [Support Team](https://www.adyen.help/hc/en-us/requests/new).\n\nIf using an API key, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using [basic authentication](https://docs.adyen.com/development-resources/api-credentials#basic-authentication).\n\nThe following example shows how to authenticate your request with basic authentication when submitting a payout:\n\n```\ncurl\n-U \"storePayout@Company.YOUR_COMPANY_ACCOUNT\":\"YOUR_BASIC_AUTHENTICATION_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\n\n## Versioning\nPayments API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://pal-test.adyen.com/pal/servlet/Payout/v68/payout\n```\n\n## Going live\n\nTo authenticate to the live endpoints, you need [API credentials](https://docs.adyen.com/development-resources/api-credentials) from your live Customer Area.\n\nThe live endpoint URLs contain a prefix which is unique to your company account:\n```\n\nhttps://{PREFIX}-pal-live.adyenpayments.com/pal/servlet/Payout/v68/payout\n```\n\nGet your `{PREFIX}` from your live Customer Area under **Developers** > **API URLs** > **Prefix**."
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://pal-test.adyen.com/pal/servlet/Payout/v68
tags:
- name: submitThirdParty
paths:
  /submitThirdParty:
    post:
      tags:
      - submitThirdParty
      summary: Adyen Submit a Payout
      description: 'Submits a payout using the previously stored payment details. To store payment details, use the `/storeDetail` API call.


        The submitted payout must be confirmed or declined either by a reviewer or via `/confirmThirdParty` or `/declineThirdParty` calls.'
      x-addedInVersion: '10'
      operationId: post-submitThirdParty
      x-sortIndex: 3
      x-methodName: submitThirdParty
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              submitThirdParty:
                $ref: '#/components/examples/post-submitThirdParty-submitThirdParty'
            schema:
              $ref: '#/components/schemas/SubmitRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              examples:
                post-submitThirdParty200Example:
                  summary: Default post-submitThirdParty 200 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    pspReference: REF-001
                    refusalReason: REF-001
                    resultCode: CODE123
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-400'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-submitThirdParty401Example:
                  summary: Default post-submitThirdParty 401 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-submitThirdParty403Example:
                  summary: Default post-submitThirdParty 403 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-submitThirdParty422Example:
                  summary: Default post-submitThirdParty 422 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-submitThirdParty500Example:
                  summary: Default post-submitThirdParty 500 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Recurring:
      properties:
        contract:
          description: 'The type of recurring contract to be used.

            Possible values:

            * `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).

            * `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).

            * `ONECLICK,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not.

            * `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/online-payments/online-payouts).'
          enum:
          - ONECLICK
          - RECURRING
          - PAYOUT
          type: string
        recurringDetailName:
          description: A descriptive name for this detail.
          type: string
        recurringExpiry:
          x-addedInVersion: '40'
          description: Date after which no further authorisations shall be performed. Only for 3D Secure 2.
          format: date-time
          type: string
        recurringFrequency:
          x-addedInVersion: '40'
          description: Minimum number of days between authorisations. Only for 3D Secure 2.
          type: string
        tokenService:
          x-addedInVersion: '25'
          description: The name of the token service.
          enum:
          - VISATOKENSERVICE
          - MCTOKENSERVICE
          - AMEXTOKENSERVICE
          - TOKEN_SHARING
          type: string
      type: object
    SubmitRequest:
      properties:
        additionalData:
          additionalProperties:
            type: string
          description: This field contains additional data, which may be required for a particular request.
          type: object
        amount:
          description: A container object for the payable amount information of the transaction.
          $ref: '#/components/schemas/Amount'
        dateOfBirth:
          x-addedInVersion: '24'
          description: "The date of birth.\nFormat: ISO-8601; example: YYYY-MM-DD\n\nFor Paysafecard it must be the same as used when registering the Paysafecard account.\n\n> This field is mandatory for natural persons. \n> This field is required to update the existing `dateOfBirth` that is associated with this recurring contract."
          format: date
          type: string
        entityType:
          x-addedInVersion: '24'
          description: 'The type of the entity the payout is processed for.


            Allowed values:

            * NaturalPerson

            * Company

            > This field is required to update the existing `entityType` that is associated with this recurring contract.'
          enum:
          - NaturalPerson
          - Company
          type: string
        fraudOffset:
          description: An integer value that is added to the normal fraud score. The value can be either positive or negative.
          format: int32
          type: integer
        merchantAccount:
          description: The merchant account identifier you want to process the transaction request with.
          type: string
        nationality:
          x-addedInVersion: '24'
          description: 'The shopper''s nationality.


            A valid value is an ISO 2-character country code (e.g. ''NL'').


            > This field is required to update the existing nationality that is associated with this recurring contract.'
          type: string
        recurring:
          description: 'A container for the type of recurring contract to be retrieved.


            The `recurring.contract` must be set to "PAYOUT".'
          $ref: '#/components/schemas/Recurring'
        reference:
          description: The merchant reference for this payout. This reference will be used in all communication to the merchant about the status of the payout. Although it is a good idea to make sure it is unique, this is not a requirement.
          type: string
        selectedRecurringDetailReference:
          description: 'This is the `recurringDetailReference` you want to use for this payout.


            You can use the value LATEST to select the most recently used recurring detail.'
          type: string
        shopperEmail:
          description: The shopper's email address.
          type: string
        shopperName:
          x-addedInVersion: '24'
          description: 'The shopper''s name.


            In case the `entityType` is `Company`, the `shopperName.lastName` must contain the company name.


            > This field is required to update the existing `shopperName` associated with a recurring contract.'
          $ref: '#/components/schemas/Name'
        shopperReference:
          description: The shopper's reference for the payout transaction.
          type: string
        shopperStatement:
          x-addedInVersion: '2'
          description: The description of this payout. This description is shown on the bank statement of the shopper (if this is supported by the chosen payment method).
          type: string
        socialSecurityNumber:
          x-addedInVersion: '24'
          description: The shopper's social security number.
          type: string
      required:
      - merchantAccount
      - reference
      - amount
      - shopperEmail
      - shopperReference
      - recurring
      - selectedRecurringDetailReference
      type: object
    SubmitResponse:
      properties:
        additionalData:
          additionalProperties:
            type: string
          description: This field contains additional data, which may be returned in a particular response.
          type: object
        pspReference:
          description: A new reference to uniquely identify this request.
          type: string
        refusalReason:
          description: In case of refusal, an informational message for the reason.
          type: string
        resultCode:
          description: 'The response:

            * In case of success, it is `payout-submit-received`.

            * In case of an error, an informational message is returned.'
          type: string
      required:
      - pspReference
      - resultCode
      type: object
    ServiceError:
      properties:
        additionalData:
          x-addedInVersion: '46'
          additionalProperties:
            type: string
          description: Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
          type: object
        errorCode:
          description: The error code mapped to the error message.
          type: string
        errorType:
          description: The category of the error.
          type: string
        message:
          description: A short explanation of the issue.
          type: string
        pspReference:
          description: The PSP reference of the payment.
          type: string
        status:
          description: The HTTP response status.
          format: int32
          type: integer
      type: object
    Name:
      properties:
        firstName:
          description: The first name.
          type: string
        lastName:
          description: The last name.
          type: string
      required:
      - firstName
      - lastName
      type: object
    Amount:
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          format: int64
          type: integer
      required:
      - value
      - currency
      type: object
  examples:
    generic-400:
      summary: Response code 400. Bad Request.
      value:
        status: 400
        errorCode: '702'
        message: 'Unexpected input: I'
        errorType: validation
    post-submitThirdParty-submitThirdParty:
      summary: Submit a payout
      description: Submit a payout using the previously stored payment details
      value:
        amount:
          currency: EUR
          value: 1000
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        recurring:
          contract: PAYOUT
        reference: PayoutPayment-0001
        shopperEmail: shopper@email.com
        shopperReference: YOUR_UNIQUE_SHOPPER_ID
        shopperName:
          firstName: Adyen
          gender: MALE
          lastName: Test
        dateOfBirth: '1990-01-01'
        entityType: Company
        nationality: NL
        selectedRecurringDetailReference: LATEST
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http