openapi: 3.0.1
info:
  title: Token.io's Open Banking API for TPPs Account on File API
  description: '<b>Token.io''s Open Banking API</b><br/><br/>Token.io Support: <a href="https://support.token.io" target="_blank">support.token.io</a><br/><br/>The Token.io Open Banking API enables you to connect securely with banks for a range of services.<br/><br/> Using our API you can: <ul><li>provide authorized access to an authenticated user''s account information</li><li>get information on specific banks</li><li>initiate authorization with a user-selected bank</li><li>initate and track single immediate payments and future dated payments</li><li>use variable recurring payments (VRP) to grant long-held consents to Payment Initiation Service Providers (PISPs) to initiate series of payments from users'' bank accounts</li><li>carry out settlements, payments and refunds using our settlement accounts</li></ul><br/>For more information see our <a href="https://developer.token.io/token_rest_api_doc/content/e-rest/dashboard-intro.htm" target="_blank">developer documentation</a>.'
  version: ''
servers:
- url: https://api.token.io
tags:
- name: Account on File
  description: These endpoints allow you to create and manage an Account on File from bank account details. The Account on File can then be used in other API requests instead of sending the full account details.
paths:
  /tokenized-accounts:
    post:
      tags:
      - Account on File
      summary: Create an Account on File
      description: Creates an Account on File from the provided bank account details. This can be used by Third Party Providers (TPPs) in future API requests to reference the account without resending the full account information.
      operationId: CreateTokenizedAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTokenizedAccountRequest'
        required: true
      x-badges:
      - name: Beta
        position: before
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTokenizedAccountResponse'
        '400':
          description: The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400_bad_request'
        '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_1'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_429'
        '500':
          description: An unexpected internal server error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500_internal'
        '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
  /tokenized-accounts/{tokenizedAccountId}:
    get:
      tags:
      - Account on File
      summary: Retrieve an Account on File
      description: Retrieves an Account on File using its tokenizedAccountId.
      operationId: GetTokenizedAccount
      parameters:
      - name: tokenizedAccountId
        description: The tokenized account id.
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      x-badges:
      - name: Beta
        position: before
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTokenizedAccountResponse'
        '400':
          description: The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400_bad_request'
        '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_1'
        '404':
          description: The requested entity, such as tokenized account, 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 internal server error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500_internal'
        '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
    delete:
      tags:
      - Account on File
      summary: Delete an Account on File
      description: Deletes an Account on File. After deletion, the tokenizedAccountId can no longer be used to reference the associated account details in API requests.
      operationId: DeleteTokenizedAccount
      parameters:
      - name: tokenizedAccountId
        description: The tokenized account id.
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      x-badges:
      - name: Beta
        position: before
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTokenizedAccountResponse'
        '400':
          description: The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400_bad_request'
        '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_1'
        '404':
          description: The requested entity, such as tokenized account, 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 internal server error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500_internal'
        '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
components:
  schemas:
    ElixirAccountDebtor:
      title: ElixirAccount
      oneOf:
      - $ref: '#/components/schemas/PLIbanAccount'
      description: The Elixir debtor account details.
    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'
    PLIbanAccount:
      title: PLIbanAccount
      required:
      - iban
      type: object
      properties:
        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 SWIFT 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 are often called SWIFT Codes and can be either 8 or 11 characters long."
          example: BOFIIE2D
      description: Polish account details where the iban is required and the bic is optional.
    inline_response_400_bad_request:
      type: object
      description: Response returned when the request contains invalid, missing, or improperly formatted parameters.
      properties:
        error:
          $ref: '#/components/schemas/BadRequestError'
    inline_response_504:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/GatewayTimeoutError'
    inline_response_501:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NotImplementedError'
    Address:
      type: object
      properties:
        addressLine:
          type: array
          items:
            type: string
            example: The Coach House
        streetName:
          type: string
          description: Street number
          example: 221B
        buildingNumber:
          type: string
          description: Building number
          example: 2C
        postCode:
          type: string
          description: Post Code
          example: TR26 1EZ
        townName:
          type: string
          description: Town name
          example: Saint Ives
        state:
          type: string
          description: State
          example: Cornwall
        district:
          type: string
          description: The district.
        country:
          type: string
          description: Two-letter country code in upper case (ISO 3166-1 alpha-2).
          example: GB
      description: Address
    EUDomesticNonEuroInstantAccountDebtor:
      title: EUDomesticNonEuroInstantAccount
      oneOf:
      - $ref: '#/components/schemas/EUIbanAccount'
      - $ref: '#/components/schemas/BbanAccount'
      - $ref: '#/components/schemas/ClearingNumberAccount'
      description: The instant payment system within a European country using that country's non-Euro domestic currency. An IBAN account will require an iban and an optional bic, a BBAN account will require a bban and an optional bic, a Clearing Number account will require a bban and a clearingNumber.
    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'
    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.
    GetTokenizedAccountResponse:
      type: object
      properties:
        accountDetails:
          $ref: '#/components/schemas/AccountInformation'
      description: Contains the response of the get tokenized account request.
    BadRequestError:
      type: object
      description: The request contains invalid, missing, or improperly formatted parameters.
      properties:
        message:
          type: string
          description: A description of the validation issue with the request.
          example: The field 'accountNumber' is missing or invalid.
        tokenTraceId:
          type: string
          description: The trace identifier for the given call.
          example: '5678912345'
    CreateTokenizedAccountResponse:
      type: object
      properties:
        tokenizedAccountId:
          type: string
          description: The tokenized account id of the provided account details.
          example: tai:4HoNxTfhn9EjwNnQmjGCsWsuYS7S:5zJAqBcE
      description: Contains the response of the create a tokenized account request.
    AccountInformation:
      description: The account information for the PSU or Business.
      allOf:
      - $ref: '#/components/schemas/DebtorAccountDetails'
      - type: object
        properties:
          name:
            type: string
            description: The owner's name of the debtor account.
            example: John Smith
          ultimateDebtorName:
            type: string
            description: The ultimate debtor's name.
            example: John Smith
          address:
            $ref: '#/components/schemas/Address'
    inline_response_404:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/PaymentNotFoundError'
    DebtorAccountDetails:
      description: 'The raw debtor account identifiers. Exactly one format must be used, depending on the payment instrument and jurisdiction.

        '
      oneOf:
      - $ref: '#/components/schemas/SepaAccount'
      - $ref: '#/components/schemas/SepaInstantAccount'
      - $ref: '#/components/schemas/FasterPaymentsAccount'
      - $ref: '#/components/schemas/ElixirAccountDebtor'
      - $ref: '#/components/schemas/EUDomesticNonEuroAccountDebtor'
      - $ref: '#/components/schemas/EUDomesticNonEuroInstantAccountDebtor'
      - $ref: '#/components/schemas/BankGiroAccount'
      - $ref: '#/components/schemas/PlusGiroAccount'
    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'
    CreateTokenizedAccountRequest:
      type: object
      required:
      - accountDetails
      properties:
        accountDetails:
          $ref: '#/components/schemas/AccountInformation'
        bankId:
          type: string
          description: Identifier of the bank where the account belongs.
          example: ob-modelo
    InternalServiceError:
      type: object
      description: The server encountered an unexpected internal condition while processing the request.
      properties:
        message:
          type: string
          description: A description of the internal failure.
          example: An unexpected error occurred while storing the account details.
        tokenTraceId:
          type: string
          description: The trace identifier for the given call.
          example: '5678912345'
    SepaAccount:
      title: SepaAccount
      required:
      - iban
      type: object
      properties:
        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
      description: SEPA account details where the iban is required and the bic is optional.
    ClearingNumberAccount:
      title: ClearingNumberAccount
      required:
      - bban
      type: object
      properties:
        bban:
          type: string
          description: Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers.
          example: NWBK60161331926819
        clearingNumber:
          type: string
          description: The bank clearing number or BC number is a number used for the identification of financial institutions in Switzerland and Liechtenstein. Bank clearing numbers are connected to the Swiss Interbank Clearing and the EuroSIC system.
          example: 87654321
      description: Account details where the bban is required and the clearing number is optional.
    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'
    BbanAccount:
      title: BbanAccount
      required:
      - bban
      type: object
      properties:
        bban:
          type: string
          description: Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers.
          example: NWBK60161331926819
        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 SWIFT 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 are often called SWIFT Codes and can be either 8 or 11 characters long."
          example: BOFIIE2D
      description: Account details where the bban is required and the bic is optional.
    FasterPaymentsAccount:
      title: FasterPaymentsAccount
      required:
      - accountNumber
      - sortCode
      type: object
      properties:
        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'
      description: A UK or Irish account where the sort code and account number are required.
    inline_response_429:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ResourceExhaustedError'
    inline_response_401:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    BankGiroAccount:
      title: BankGiroAccount
      required:
      - bankgiroNumber
      type: object
      properties:
        bankgiroNumber:
          type: string
          description: The unique identifier for the bank account in Sweden (known in Swedish as Bankgironummer), it consists of 7 or 8 digits.
          example: '56781234'
        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
      description: Account details where the bankgiroNumber is required and the bic is optional.
    DeleteTokenizedAccountResponse:
      type: object
      description: No data returned in the successful response.
    SepaInstantAccount:
      title: SepaInstantAccount
      required:
      - iban
      type: object
      properties:
        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
      description: SEPA Instant account details where the iban is required and the bic is optional.
    TokenizedPermissionDeniedError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ErrorWithCode'
      description: The error returned when the operation is not permitted for the tokenized account. Typically, this occurs when the member is not authorized to perform the given operation
      properties:
        errorCode:
          example: PermissionDenied
    EUDomesticNonEuroAccountDebtor:
      title: EUDomesticNonEuroAccount
      oneOf:
      - $ref: '#/components/schemas/EUIbanAccount'
      - $ref: '#/components/schemas/BbanAccount'
      - $ref: '#/components/schemas/ClearingNumberAccount'
      description: The payment system within a European country using that country's non-Euro domestic currency. An IBAN account will require an iban and an optional bic, a BBAN account will require a bban and an optional bic, a Clearing Number account will require a bban and a clearingNumber.
    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'
    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'
    PlusGiroAccount:
      title: PlusGiroAccount
      required:
      - plusgiroNumber
      type: object
      properties:
        plusgiroNumber:
          type: string
          description: The unique identifier for the Swedish money transaction system owned by <a href="https://www.nordea.com" target="blank">Nordea</a>.
          example: '67812345'
        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 SWIFT 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 are often called SWIFT Codes and can be either 8 or 11 characters long."
          example: BOFIIE2D
      description: Account details where the plusgiroNumber is required and the bic is optional.
    inline_response_503:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ServiceUnavailableError'
    inline_response_403_1:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TokenizedPermissionDeniedError'
    inline_response_500_internal:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/InternalServiceError'
      description: Returned when the server fails to complete the request due to an unexpected internal error.
    EUIbanAccount:
      title: EUIbanAccount
      required:
      - iban
      type: object
      properties:
        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 SWIFT 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 are often called SWIFT Codes and can be either 8 or 11 characters long."
          example: BOFIIE2D
      description: Account details where the iban is required and the bic is optional.
  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