Open Payments Payout Service API

openapi: 3.2.0
info:
  title: Open Payments Payout Service API
  version: 1.3.3
  description: '# Summary

    The Open Banking part of our API is based on The BerlinGroup NextGenPSD2 Framework with some additional services.'
  license:
    name: Creative Commons Attribution 4.0 International Public License
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Open Payments Europe AB
    url: https://www.openpayments.io/
    email: info@openpayments.io
servers:
- url: https://api.openbankingplatform.com
- url: https://api.sandbox.openbankingplatform.com
security:
- {}
tags:
- name: Payout Service
  description: The Payout Service brings efficiency and security to a wide range of payment processes, including supplier invoices, payroll, refunds, and other forms of disbursement.
paths:
  /premium/v1/payouts:
    servers:
    - url: https://api.openbankingplatform.com
      description: Premium products production server
    post:
      tags:
      - Payout Service
      operationId: CreatePayout
      security:
      - oAuth2Production:
        - paymentinitiation corporate
      summary: Create Payout
      description: Initiates a payout request by submitting payment details.
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/PSU-Corporate-ID'
      - $ref: '#/components/parameters/PSU-ID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePayoutResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
      x-operation-id-source: normalized
      x-operation-id-original: Create Payout
  /premium/v1/payouts/{payoutId}:
    servers:
    - url: https://api.openbankingplatform.com
      description: Premium products production server
    get:
      tags:
      - Payout Service
      operationId: GetPayout
      security:
      - oAuth2Production:
        - paymentinitiation corporate
      summary: Get Payout
      description: Returns the details and current status of a payout.
      parameters:
      - name: payoutId
        description: ID of the generated payout resource.
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/PSU-Corporate-ID'
      - $ref: '#/components/parameters/PSU-ID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPayoutResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
      x-operation-id-source: normalized
      x-operation-id-original: Get Payout
  /premium/v1/payouts/confirm:
    servers:
    - url: https://api.openbankingplatform.com
      description: Premium products production server
    put:
      tags:
      - Payout Service
      operationId: ConfirmPayout
      security:
      - oAuth2Production:
        - paymentinitiation corporate
      summary: Confirm Payout
      description: Confirms and finalizes a pending payout, triggering the disbursement of funds. Only confirmed payouts are sent to Bankgirot for processing.
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/PSU-Corporate-ID'
      - $ref: '#/components/parameters/PSU-ID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmPayoutRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmPayoutResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
      x-operation-id-source: normalized
      x-operation-id-original: Confirm Payout
components:
  schemas:
    countryCode:
      description: ISO 3166 ALPHA2 country code
      type: string
      pattern: '[A-Z]{2}'
      example: SE
    remittanceInformationStructured:
      description: 'Structured remittance information

        '
      type: object
      required:
      - reference
      properties:
        reference:
          type: string
          maxLength: 35
        referenceType:
          type: string
          maxLength: 35
        referenceIssuer:
          type: string
          maxLength: 35
    address:
      type: object
      required:
      - country
      properties:
        street:
          type: string
          maxLength: 70
        buildingNumber:
          type: string
        city:
          type: string
        postalCode:
          type: string
        country:
          $ref: '#/components/schemas/countryCode'
      example:
        street: rue blue
        buildingNumber: '89'
        city: Paris
        postalCode: '75000'
        country: FR
    giroType:
      type: string
      description: Swedish giro type
      enum:
      - BANKGIRO
      - PLUSGIRO
    giroReference:
      description: 'Reference to a Swedish Bankgiro or Plusgiro account

        '
      type: object
      required:
      - giroNumber
      - giroType
      properties:
        giroNumber:
          $ref: '#/components/schemas/giroNumber'
        giroType:
          $ref: '#/components/schemas/giroType'
    hrefEntry:
      description: Link to a resource
      type: string
      example: /v1/payments/sepa-credit-transfers/1234-wertiq-983
    ConfirmPayoutRequest:
      type: object
      properties:
        payoutIds:
          type:
          - array
          - 'null'
          items:
            type: string
      additionalProperties: false
    amount:
      type: object
      required:
      - currency
      - amount
      properties:
        currency:
          $ref: '#/components/schemas/currencyCode'
        amount:
          $ref: '#/components/schemas/amountValue'
      example:
        currency: EUR
        amount: '123'
    iban:
      type: string
      description: International Bank Account Number (IBAN) of an account.
      pattern: '[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}'
      example: FR7612345987650123456789014
    accountReference:
      description: "Reference to an account by either\n  * IBAN, of a payment account, or\n  * BBAN, for payment accounts if there is no IBAN, or \n  * the Primary Account Number (PAN) of a card, can be tokenised by the ASPSP due to PCI DSS requirements, or\n  * the Primary Account Number (PAN) of a card in a masked form, or\n  * an alias to access a payment account via a registered mobile phone number (MSISDN).\n"
      type: object
      properties:
        iban:
          $ref: '#/components/schemas/iban'
        bban:
          $ref: '#/components/schemas/bban'
        clearingNumber:
          $ref: '#/components/schemas/clearingNumber'
        accountNumber:
          $ref: '#/components/schemas/accountNumber'
        pan:
          $ref: '#/components/schemas/pan'
        maskedPan:
          $ref: '#/components/schemas/maskedPan'
        msisdn:
          $ref: '#/components/schemas/msisdn'
        currency:
          $ref: '#/components/schemas/currencyCode'
    msisdn:
      type: string
      maxLength: 35
      description: Mobile phone number.
      example: +49 170 1234567
    currencyCode:
      description: 'ISO 4217 Alpha 3 currency code.

        '
      type: string
      pattern: '[A-Z]{3}'
      example: EUR
    accountNumber:
      description: "Bank account number. Used to identify the particular customer account within the financial institution. \n"
      type: string
      pattern: '[a-zA-Z0-9]{1,30}'
      example: BARC12345612345678
    ErrorResponseDetails:
      type: object
      properties:
        tppMessages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/tppMessage2XX'
      additionalProperties: false
    authenticationMethodId:
      description: 'An identification provided by the ASPSP for the later identification of the authentication method selection.

        '
      type: string
      maxLength: 35
      example: myAuthenticationID
    challengeData:
      description: "Contained in addition to the data element `chosenScaMethod` if challenge data is needed for SCA. In rare cases, this attribute is also used in the context of the `startAuthorisationWithPsuAuthentication` link. \n"
      type: object
      properties:
        image:
          type: string
          format: byte
          description: 'PNG data (max. 512 kilobyte) to be displayed to the PSU,

            Base64 encoding, cp. [RFC4648].

            This attribute is used only, when PHOTO_OTP or CHIP_OTP

            is the selected SCA method.

            '
        data:
          type: array
          items:
            type: string
          description: Challenge data
        imageLink:
          type: string
          format: url
          description: A link where the ASPSP will provides the challenge image for the TPP.
        otpMaxLength:
          type: integer
          description: The maximal length for the OTP to be typed in by the PSU.
        otpFormat:
          type: string
          description: The format type of the OTP to be typed in. The admitted values are "characters" or "integer".
          enum:
          - characters
          - integer
        additionalInformation:
          type: string
          description: 'Additional explanation for the PSU to explain

            e.g. fallback mechanism for the chosen SCA method.

            The TPP is obliged to show this to the PSU.

            '
    authenticationType:
      description: 'Type of the authentication method. See Statuses & Types for full descriptions of values.

        '
      type: string
      enum:
      - SMS_OTP
      - CHIP_OTP
      - PHOTO_OTP
      - PUSH_OTP
    tppMessage2XX:
      type: object
      required:
      - category
      - code
      properties:
        category:
          $ref: '#/components/schemas/tppMessageCategory'
        code:
          $ref: '#/components/schemas/MessageCode2XX'
        path:
          type: string
        text:
          $ref: '#/components/schemas/tppMessageText'
    amountValue:
      description: "The amount given with fractional digits, where fractions must be compliant to the currency definition.\nUp to 14 significant figures. Negative amounts are signed by minus.\nThe decimal separator is a dot.\n\n**Example:**\nValid representations for EUR with up to two decimals are:\n\n  * 1056\n  * 5768.2\n  * -1.50\n  * 5877.78\n"
      type: string
      pattern: -?[0-9]{1,14}(\.[0-9]{1,3})?
      example: '5877.78'
    tppMessageText:
      description: Additional explaining text to the TPP.
      type: string
      maxLength: 512
    CreatePayoutResponse:
      required:
      - _links
      - transactionStatus
      type: object
      properties:
        tppMessages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/tppMessage2XX'
        transactionStatus:
          $ref: '#/components/schemas/transactionStatus'
        transactionFees:
          $ref: '#/components/schemas/amount'
        transactionFeeIndicator:
          type:
          - boolean
          - 'null'
        scaMethods:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/authenticationObject'
        chosenScaMethod:
          $ref: '#/components/schemas/authenticationObject'
        challengeData:
          $ref: '#/components/schemas/challengeData'
        _links:
          $ref: '#/components/schemas/PayoutLinks'
        psuMessage:
          maxLength: 512
          type:
          - string
          - 'null'
        payoutId:
          type:
          - string
          - 'null'
          readOnly: true
      additionalProperties: false
    pan:
      description: 'Primary Account Number according to ISO/IEC 7812.

        '
      type: string
      maxLength: 35
      example: '5409050000000000'
    CreatePayoutRequest:
      required:
      - creditorGiro
      - creditorName
      - debtorAccount
      - instructedAmount
      type: object
      properties:
        instructionId:
          maxLength: 35
          type:
          - string
          - 'null'
        debtorAccount:
          $ref: '#/components/schemas/accountReference'
        creditorAgent:
          maxLength: 35
          type:
          - string
          - 'null'
        creditorGiro:
          $ref: '#/components/schemas/giroReference'
        creditorName:
          maxLength: 70
          minLength: 1
          type: string
        instructedAmount:
          $ref: '#/components/schemas/amount'
        requestedExecutionDate:
          type:
          - string
          - 'null'
        debtorAccountMessage:
          type:
          - string
          - 'null'
        creditorAccountMessage:
          type:
          - string
          - 'null'
        invoiceRef:
          type:
          - string
          - 'null'
        ocrRef:
          type:
          - string
          - 'null'
        endToEndIdentification:
          maxLength: 35
          type:
          - string
          - 'null'
      additionalProperties: false
    ConfirmPayoutResponse:
      type: object
      properties:
        tppMessages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/tppMessage2XX'
        reference:
          type:
          - string
          - 'null'
        totalAmount:
          $ref: '#/components/schemas/amount'
      additionalProperties: false
    PayoutLinks:
      type: object
      properties:
        confirmPayout:
          $ref: '#/components/schemas/hrefType'
        self:
          $ref: '#/components/schemas/hrefType'
      additionalProperties: false
    clearingNumber:
      description: "Bank account clearing number. Used to identify the financial institution within a domestic payment system. \n"
      type: string
      pattern: '[0-9]{1,5}'
      example: '5392'
    transactionStatus:
      description: "Uses codes from the ISO 20022 data table. See Statuses & Types documentation for full descriptions of values. \n"
      type: string
      enum:
      - ACCC
      - ACCP
      - ACSC
      - ACSP
      - ACTC
      - ACWC
      - ACWP
      - RCVD
      - PDNG
      - RJCT
      - CANC
      - ACFC
      - PATC
      - PART
      example: ACSP
    maskedPan:
      description: 'Masked Primary Account Number.

        '
      type: string
      maxLength: 35
      example: 123456xxxxxx1234
    hrefType:
      description: Link to a resource
      type: object
      properties:
        href:
          $ref: '#/components/schemas/hrefEntry'
    authenticationObject:
      description: 'Authentication Object

        '
      type: object
      required:
      - authenticationType
      - authenticationMethodId
      properties:
        authenticationType:
          $ref: '#/components/schemas/authenticationType'
        authenticationVersion:
          description: "Specifies the version of the authentication method. Useful when multiple tools exist under the same method type. \n"
          type: string
        authenticationMethodId:
          $ref: '#/components/schemas/authenticationMethodId'
        name:
          description: 'A user-defined or bank-provided label for the authentication method (e.g. "SMS OTP on phone +49160 xxxxx 28"). This should be shown to the user when offering authentication method choices.

            '
          type: string
          example: SMS OTP on phone +49160 xxxxx 28
        explanation:
          description: 'Detailed information about the SCA method for the PSU.

            '
          type: string
          example: Detailed information about the SCA method for the PSU.
    MessageCode2XX:
      description: Message codes for HTTP Error codes 2XX.
      type: string
    tppMessageCategory:
      description: Category of the TPP message category
      type: string
      enum:
      - INFORMATION
      - UNMAPPED
      - ERROR
      - WARNING
    giroNumber:
      type: string
      description: Swedish Bankgiro or Plusgiro number
      pattern: '[0-9-]{5,35}'
      example: 1234-5678
    bban:
      description: "Basic Bank Account Number (BBAN) Identifier. Used nationally by financial institutions, i.e., in individual countries, \n  generally as part of a National Account Numbering Scheme(s), \n  which uniquely identifies the account of a customer.\n"
      type: string
      pattern: '[a-zA-Z0-9]{1,30}'
      example: BARC12345612345678
    GetPayoutResponse:
      required:
      - creditorAccount
      - creditorName
      - debtorAccount
      - instructedAmount
      type: object
      properties:
        tppMessages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/tppMessage2XX'
        creditorAccount:
          $ref: '#/components/schemas/accountReference'
        creditorName:
          maxLength: 70
          minLength: 1
          type: string
        debtorAccount:
          $ref: '#/components/schemas/accountReference'
        instructedAmount:
          $ref: '#/components/schemas/amount'
        endToEndIdentification:
          maxLength: 35
          type:
          - string
          - 'null'
        creditorAgent:
          pattern: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}'
          type:
          - string
          - 'null'
        creditorAddress:
          $ref: '#/components/schemas/address'
        remittanceInformationUnstructured:
          maxLength: 140
          type:
          - string
          - 'null'
        remittanceInformationStructured:
          $ref: '#/components/schemas/remittanceInformationStructured'
        debtorAccountMessage:
          type:
          - string
          - 'null'
        creditorAccountMessage:
          type:
          - string
          - 'null'
        requestedExecutionDate:
          type:
          - string
          - 'null'
        transactionStatus:
          $ref: '#/components/schemas/transactionStatus'
      additionalProperties: false
  parameters:
    PSU-ID:
      name: PSU-ID
      in: header
      description: 'Client ID of the PSU in the ASPSP client interface. This is typically a local social security number or another unique login ID.

        '
      schema:
        type: string
      required: true
      example: 199002092386
    PSU-Corporate-ID:
      name: PSU-Corporate-ID
      in: header
      description: 'Corporate Client ID for the ASPSP. This is typically the unique Corporate ID in the local format. E.g. Org. nummer for SE, KVK for NL. **Mandatory in the corporate scope**.

        '
      schema:
        type: string
      required: false
      example: 5560160680
    X-Request-ID:
      name: X-Request-ID
      in: header
      description: ID of the request, unique to the call, as determined by the initiating party.
      required: true
      example: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
      schema:
        type: string
        format: uuid
  securitySchemes:
    oAuth2Sandbox:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.sandbox.openbankingplatform.com/connect/token
          scopes:
            aspspinformation: ASPSP Information
            accountinformation: Account Information
            paymentinitiation: Payment Initiation
            private: Private accounts context
            corporate: Corporate accounts context
    oAuth2Production:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.openbankingplatform.com/connect/token
          scopes:
            aspspinformation: ASPSP Information
            accountinformation: Account Information
            bankgiroinformation: Account Information Enrichment
            paymentinitiation: Payment Initiation
            private: Private accounts context
            corporate: Corporate accounts context
externalDocs:
  description: 'Full Documentation of NextGenPSD2 Access to Account Interoperability Framework

    (General Introduction Paper, Operational Rules, Implementation Guidelines)

    '
  url: https://www.berlin-group.org/nextgenpsd2-downloads
x-tagGroups:
- name: Core APIs
  tags:
  - ASPSP Information Service
  - Consent Service
  - Account Information Service (AIS)
  - Payment Initiation Service (PIS)
  - KYC Service
- name: Alternative APIs
  tags:
  - ISO Payments
  - FX Connect
- name: Premium APIs
  tags:
  - Bankgiro Lookup
  - Payout Service
  - Verification of Payee (VoP)
  - SEPA Direct Debit