token-io Payouts API

openapi: 3.2.0
info:
  title: Token.io's Open Banking API for TPPs Payouts API
  description: 'Token.io''s Open Banking API


    Token.io Support: support.token.io


    The Token.io Open Banking API enables you to connect securely with banks for a range of services.'
  version: ''
servers:
- url: https://api.token.io
tags:
- name: Payouts
  description: These endpoints allow you to make payouts.
  x-internal: true
paths:
  /payouts:
    post:
      tags:
      - Payouts
      summary: Initiate a payout
      description: The `POST /payouts` endpoint initiates a payout.
      operationId: InitiatePayout
      x-internal: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payouts_body'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '400':
          description: The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        '401':
          description: The authorization information is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_401'
        '403':
          description: Permission to access this endpoint is denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_403'
        '404':
          description: The requested entity, such as a payment, was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_404'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_429'
        '500':
          description: An unexpected or internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
        '501':
          description: The operation was not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_501'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_503'
        '504':
          description: Gateway has timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_504'
      deprecated: false
      security:
      - Bearer: []
      - BasicAuth: []
      x-hideTryItPanel: true
    get:
      tags:
      - Payouts
      summary: Get payouts
      description: The `GET /payouts` endpoint retrieves a complete or filtered list of payouts.
      operationId: GetPayouts
      x-internal: true
      parameters:
      - name: limit
        in: query
        description: The maximum number of records to return.
        required: true
        style: form
        explode: true
        schema:
          maximum: 200
          minimum: 1
          type: integer
          format: int32
        example: 10
      - name: offset
        in: query
        description: The offset from the previous page.
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: LerV6Jmex
      - name: startDate
        in: query
        description: Lower bound for a payout creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only payouts created at or after the given date will be returned.
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: '2010-01-01'
      - name: endDate
        in: query
        description: Upper bound for a payout creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only payouts created at or before the given date will be returned.
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: '2010-01-01'
      - name: ids
        in: query
        description: Filters payouts by their ids - returns only payouts with ids listed in this parameter.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
        example:
        - po:28oivvd3iFhBrcbNj4tmtLEhxRTk:2gFUX1NE1T6
        - po:3ZfdHxbpXmRZ1TVmiYNPgcwEocBy:2gFUX1NDdqr
      - name: invertIds
        in: query
        description: Invert ids query - returns only payouts with ids not listed in the ids parameter.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
        example: false
      - name: statuses
        in: query
        description: Filters payouts by their statuses - returns only payouts with statuses listed in this parameter.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/PayoutStatus'
        example:
        - INITIATION_COMPLETED
        - INITIATION_REJECTED
      - name: invertStatuses
        in: query
        description: Invert statuses query - returns only payouts with statuses not listed in the statuses parameter.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
        example: true
      - name: refIds
        in: query
        description: Filters payouts by their `refId` values - returns only payouts with `refIds` listed in this parameter.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
        example:
        - ShBdcTeqFabqJJhUF
        - N5cJDFsQzVca3Q
      - name: onBehalfOfId
        in: query
        description: Filters payouts by their `onBehalfOfId` value - returns only payouts with the `onBehalfOfId` value specified in this parameter. This field is mandatory for unregulated TPPs.
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: c5a863bc-86f2-4418-a26f-25b24c7983c7
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutsResponse'
        '400':
          description: The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        '401':
          description: The authorization information is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_401'
        '403':
          description: Permission to access this endpoint is denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_403'
        '404':
          description: The requested entity, such as a payment, was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_404'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_429'
        '500':
          description: An unexpected or internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
        '501':
          description: The operation was not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_501'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_503'
        '504':
          description: Gateway has timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_504'
      deprecated: false
      security:
      - Bearer: []
      - BasicAuth: []
      x-hideTryItPanel: true
  /payouts/{id}:
    get:
      tags:
      - Payouts
      summary: Get a payout
      description: The `GET /payouts/{id}` endpoint retrieves a given payout.
      operationId: GetPayout
      x-internal: true
      parameters:
      - name: id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          description: The payout id.
          example: your payout id
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '400':
          description: The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        '401':
          description: The authorization information is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_401'
        '403':
          description: Permission to access this endpoint is denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_403'
        '404':
          description: The requested entity, such as a payment, was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_404'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_429'
        '500':
          description: An unexpected or internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
        '501':
          description: The operation was not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_501'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_503'
        '504':
          description: Gateway has timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_504'
      security:
      - Bearer: []
      - BasicAuth: []
components:
  schemas:
    ServiceUnavailableError:
      required:
      - paymentId
      type: object
      properties:
        errorCode:
          example: UNAVAILABLE
        paymentId:
          type: string
          description: The service is unavailable, likely due to a transient condition; this is usually corrected with a retry.
          example: Unavailable
      description: Service is unavailable, likely due to a transient condition; this is usually corrected with a retry.
      allOf:
      - $ref: '#/components/schemas/ErrorWithCode'
    Amount:
      description: The transaction amount and currency.
      required:
      - currency
      - value
      type: object
      properties:
        value:
          type: string
          description: The transaction amount with up to four digits after the decimal point.
          example: '10.23'
        currency:
          type: string
          description: The <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank">ISO 4217</a> three letter currency code.
          example: EUR
    inline_response_401:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    inline_response_504:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/GatewayTimeoutError'
    inline_response_400:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    ResolvedPayoutInitiation:
      required:
      - amount
      - creditor
      - debtor
      - paymentType
      - refId
      type: object
      properties:
        description:
          type: string
          description: The description for the payout.
          example: payout for some reason
        refId:
          $ref: '#/components/schemas/refId'
        amount:
          $ref: '#/components/schemas/Amount'
        debtor:
          oneOf:
          - $ref: '#/components/schemas/CorporateApiDebtorInformation'
        creditor:
          $ref: '#/components/schemas/CreditorInformationPayout'
      description: The Initiation payload for the refund.
    PaymentNotFoundError:
      required:
      - paymentId
      type: object
      properties:
        errorCode:
          example: NOT_FOUND
        paymentId:
          type: string
          description: The requested entity, the `paymentID`, was not found.
          example: pm2:12345abcd:abcde
      description: 'The error object returned when given payment cannot be found: ResourceNotFound.'
      allOf:
      - $ref: '#/components/schemas/ErrorWithCode'
    inline_response_403:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/PermissionDeniedError'
    inline_response_500:
      properties:
        error:
          allOf:
          - type: object
            properties:
              errorCode:
                type: string
                description: This is a textual error code categorising the error.
                example: InternalServerError
          - $ref: '#/components/schemas/ServerError'
    memberId:
      type: string
      description: The Token.io-assigned member id of the TPP.
      example: m:123456abcd:abcd
    inline_response_404:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/PaymentNotFoundError'
    refId:
      type: string
      description: The TPP-generated reference identifier for the token. This is not to be confused with the `requestId`. The `refId` maps to the `tppRefId` in the bank's `consentRequest`. This is needed to match/verify the originating token request with the bank's consent request. <br/>We recommend that the `refId` should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length.
      example: 9htio4a1sp2akdr1aa
    GatewayTimeoutError:
      required:
      - paymentId
      type: object
      properties:
        errorCode:
          example: DEADLINE_EXCEEDED
        paymentId:
          type: string
          description: The deadline expired before the operation could complete.
          example: Deadline exceeded.
      description: The deadline expired before the operation could complete.
      allOf:
      - $ref: '#/components/schemas/ErrorWithCode'
    ResourceExhaustedError:
      required:
      - paymentId
      type: object
      properties:
        errorCode:
          example: RESOURCE_EXHAUSTED
        paymentId:
          type: string
          description: The maximum number of requests has been reached.
          example: Resource exhausted. Check quota.
      description: Resource exhausted. Too many requests.
      allOf:
      - $ref: '#/components/schemas/ErrorWithCode'
    CreditorInformationPayout:
      type: object
      properties:
        name:
          type: string
          description: The owner's name for the creditor account.
          example: Customer Inc.
        ultimateCreditorName:
          type: string
          description: The ultimate creditor's name.
          example: Customer Inc.
        bankName:
          type: string
          description: The creditor's bank name.
        iban:
          type: string
          description: The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters.
          example: GB29NWBK60161331926819
        bic:
          type: string
          description: The Business Identifier Code (BIC), <a href="https://www.iso.org/standard/84108.html" target="_blank">ISO 9362</a>, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long.
          example: BOFIIE2D
        accountNumber:
          type: string
          description: The unique identifier for the bank account in the UK or Ireland.
          example: '12345678'
        sortCode:
          type: string
          description: The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland.
          example: 123456
        accountVerificationId:
          $ref: '#/components/schemas/AccountVerificationId'
      description: The payout creditor object.
    Payout:
      required:
      - createdDateTime
      - id
      - memberId
      - status
      - updatedDateTime
      type: object
      properties:
        id:
          type: string
          description: Token.io generated payout id.
          example: po:yj6sSEf7ZYFP8yxN6XWi1KkMEcB:2gFUX1NDget
        bankTransactionId:
          type: string
          description: The transaction id from the bank side. This can be empty if it is not available from the bank.
          example: 2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV
        memberId:
          $ref: '#/components/schemas/memberId'
        createdDateTime:
          type: string
          description: The date and time this payout object was created The time this payment object was created (in <a href="https://www.iso.org/iso-8601-date-and-time-format.html" target="_blank">ISO 8601</a> format).
          example: '2017-04-05T10:43:07.000+00:00'
        updatedDateTime:
          type: string
          description: The date and time the current status, sub status, status reason information and authentication were last updated (in <a href="https://www.iso.org/iso-8601-date-and-time-format.html" target="_blank">ISO 8601</a> format).
          example: '2017-04-05T10:45:07.000+00:00'
        status:
          $ref: '#/components/schemas/PayoutStatus'
        bankPaymentStatus:
          type: string
          description: The raw bank status. This can be the <a href="https://www.iso20022.org/" target="_blank">ISO 20022</a> payment status code. See <a href="https://developer.token.io/token_rest_api_doc/content/e-rest/iso-20022-statuses.htm" target="_blank">ISO 20022 payment status codes</a> for more information. This field can be empty if no payment status is available on bank side.
          example: ACPC
        statusReasonInformation:
          type: string
          description: A human-readable description of the reason for the reported status, which may include a message from the bank. This value should not exceed 256 characters in length.
          example: The payment is settled on debtor side.
        initiation:
          $ref: '#/components/schemas/ResolvedPayoutInitiation'
      description: The payout object.
    ServerError:
      type: object
      properties:
        message:
          type: string
          description: A description of the error.
          example: This is a description of the error.
        tokenTraceId:
          type: string
          description: The trace identifier for the given call.
          example: '5678912345'
      description: 'This could refer to either an error by the payment service provider or the bank. When the bank reports a 5xx error, `"token-external-error": "true"` is set as a header in the HTTP response, indicating that the "internal" error originates from the bank. When one of the payment service providers internal services fails or when the bank reports a 4xx error, this header is not populated. The absence of this response header should be interpreted as `"token-external-error": "false"`.'
      allOf:
      - $ref: '#/components/schemas/ErrorWithCode'
    inline_response_429:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ResourceExhaustedError'
    inline_response_501:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NotImplementedError'
    PayoutResponse:
      type: object
      properties:
        payout:
          $ref: '#/components/schemas/Payout'
    Error:
      type: object
      properties:
        message:
          type: string
          description: A description of the error.
          example: This is a description of the error.
        tokenTraceId:
          type: string
          description: The trace identifier for the given call.
          example: '5678912345'
      description: The request does not have valid authentication credentials needed to perform the operation.
    ErrorWithCode:
      required:
      - errorCode
      - message
      type: object
      properties:
        errorCode:
          type: string
          description: A textual error code categorising the error.
          example: InternalServerError
        message:
          type: string
          description: A description of the error that occurred and a possible way to fix it.
          example: '`RefId` should not be longer than 35 symbols.'
      description: Error object providing details about the error.
      allOf:
      - $ref: '#/components/schemas/Error'
    PayoutStatus:
      type: string
      description: The Token.io Payout Initiation Status. <br/><br/> INITIATION_PENDING - Token.io has received the payout initiation and the initiation passed Token.io validation. <br/><br/> INITIATION_PROCESSING - the payout is processing on the bank side. Status can be updated to one of INITIATION_COMPLETED, INITIATION_REJECTED or INITIATION_FAILED.<br/>If the status is never updated by the bank within certain period of time, the status will stay INITIATION_PROCESSING forever and the corresponding status reason information field will reflect this fact.<br/><br/> INITIATION_COMPLETED - the payout initiation is successful. This does not guarantee the payout is settled.<br/><br/> INITIATION_REJECTED - the payout is rejected by the bank. More details are shared in the corresponding status reason information.  <br/><br/> INITIATION_FAILED - Token.io failed to create the initiation due to failures on the bank side, e.g. the bank is not available at the moment.
      example: INITIATION_COMPLETED
      default: INITIATION_PENDING
      enum:
      - INITIATION_PENDING
      - INITIATION_PROCESSING
      - INITIATION_COMPLETED
      - INITIATION_REJECTED
      - INITIATION_FAILED
    inline_response_503:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ServiceUnavailableError'
    PayoutsResponse:
      type: object
      properties:
        payouts:
          type: array
          items:
            $ref: '#/components/schemas/Payout'
        paging:
          $ref: '#/components/schemas/PagingInfo'
    payouts_body:
      required:
      - initiation
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PayoutInitiation'
    PayoutInitiation:
      required:
      - amount
      - paymentType
      - refId
      - debtor
      - creditor
      - description
      type: object
      properties:
        description:
          type: string
          description: The payment reference, which must consist of at least 6 alphanumeric characters that are not all the same. Optional, uncounted characters include space, hyphen(-), full stop (.), ampersand(&), and forward slash (/). The total of all characters must be no greater than 18 for SCAN (Sort Code and Account Number) payments and 140 for iban payments.
          example: e49j-2145-sp17-k3h0
        refId:
          $ref: '#/components/schemas/refId'
        onBehalfOfId:
          type: string
          description: The OnBehalfOfId is validated against the sub-TPP id of the member before initiating the payout. This field is mandatory for unregulated TPPs.
          example: c5a863bc-86f2-4418-a26f-25b24c7983c7
        amount:
          $ref: '#/components/schemas/Amount'
        debtor:
          oneOf:
          - $ref: '#/components/schemas/CorporateApiDebtorInformation'
        creditor:
          $ref: '#/components/schemas/CreditorInformationPayout'
      description: The initiation payload for the payout.
    PagingInfo:
      type: object
      properties:
        limit:
          type: integer
          description: The limit (maximum number of records to return) that was sent in the request. If the actual number of returned records is less then the limit, there are no more records left to fetch. <br/>The maximum allowed limit is 200. If the passed limit is bigger than this, it will be set to 200.
          format: int32
        offset:
          type: string
          description: Offset for the next page.
          example: LerV6Jmex
    NotImplementedError:
      required:
      - paymentId
      type: object
      properties:
        errorCode:
          example: UNIMPLEMENTED
        paymentId:
          type: string
          description: The operation was not implemented,supported or enabled by the bank.
          example: Not implemented.
      description: The operation was not implemented, supported or enabled by the bank.
      allOf:
      - $ref: '#/components/schemas/ErrorWithCode'
    PermissionDeniedError:
      type: object
      properties:
        errorCode:
          example: PermissionDenied
      description: 'The error returned when the member is not authorized to perform the given operation: PermissionDenied. <br/>This error message will be accompanied by the reason from the bank. Typically this means the access token has expired and the user must re-authenticate with the bank.'
      allOf:
      - $ref: '#/components/schemas/ErrorWithCode'
    AccountVerificationId:
      type: string
      description: The Id returned from the /account-verifications endpoint and used to identify the account verification relating to the beneficiary of the payment. Only required for EUR payments.
    CorporateApiDebtorInformation:
      description: The debtor information.
      required:
      - accountId
      type: object
      properties:
        accountId:
          type: string
          description: The ID for the debtor settlement account.
          example: a12345
  securitySchemes:
    Bearer:
      type: http
      description: '**For Production and Sandbox environments.**<br />When using curl samples the authorization header is given as -H `''Authorization: Bearer + JWT''`<br/>Please substitute your Bearer key here.<br/>For example:<br/> -H `''Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjF4N2RmNHZ1RlVIWVFDYTciLCJtaWQiOiJtOlhUalhlMkFQZTRvdmVaalE4cHoyNGdEbUZEcTo1ekt0WEVBcSIsImhvc3QiOiJsb2NhbGhvc3Q6ODAwMCIsIm1ldGhvZCI6IlBPU1QiLCJwYXRoIjoiL2JhbmtzL2lyb24vdXNlcnMiLCJleHAiOjE1ODYyOTczNDQ3ODd9..bi3wxEoMHIul_F2f7gCDvgjHQKCjIyP9_SkQns-yXpS0UqoaOqSJrW89COexU71gt-mH3jH6mtp2aksEywvFDg''`<br/>Enter the JWT Bearer token only (see <a href="https://developer.token.io/token_rest_api_doc/content/e-rest/authentication.htm#JWT" target="_blank">JWT Authentication</a> for more information).'
      scheme: bearer
      bearerFormat: JWT
    BasicAuth:
      type: apiKey
      description: '**For Sandbox environment only.**<br />When using curl samples the authorization header is given as -H `''Authorization: YOUR_API_KEY_HERE''`<br/>Please substitute your Basic key here.<br/>For example:<br/> -H `''Authorization: Basic bS0zanhoS3pqRjRSWFQ1dHZLTlhMQU14cm80d0E1LTV6S3RYRUFxOmU1MWZjZDQ0LTM5MGQtNDYxZi04YjA0LTEyMjcxOTg4YWYwNg==''`'
      name: Authorization
      in: header
x-provenance:
  method: harvested
  publisher: Token.io
  source: https://docs.token.io/_bundle/products/tpp/api/reference/index.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)