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