openapi: 3.0.1
info:
title: Token.io's Open Banking API for TPPs Account on File Tokens 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: Tokens
description: These endpoints retrieve all tokens, a filtered list of tokens, or a specific token, as well as allowing you to cancel an existing token.
paths:
/tokens:
get:
tags:
- Tokens
summary: Get tokens
description: The `GET /tokens` endpoint retrieves a list of all tokens for the authenticated member.
operationId: GatewayService.GetTokens
parameters:
- name: type
in: query
description: Specifies the type of token returned.
required: false
style: form
explode: true
schema:
type: string
example: ACCESS
default: INVALID
enum:
- INVALID
- ACCESS
- TRANSFER
- name: page.offset
in: query
description: The offset for the current page. If the offset has been provided in the request, this offset will be equal to the provided one. But if no offset was provided in the request (<i>i.e.</i> this is the first page) and the page is not empty, this field will be populated with a non-empty string. This may be helpful for loading the same page again, which might not always be possible with an empty offset due to a dynamic nature of the data. <br/>The offset is not visible to a user and should not be parsed and/or understood in any way.
required: false
style: form
explode: true
schema:
type: string
example: LerV6Jmex
- name: page.limit
in: query
description: The maximum number of records to return. This must be less than 200.
required: true
style: form
explode: true
schema:
type: integer
format: int32
example: 175
default: 1
- name: filter.sourceAccountId
in: query
description: Identifies the payer's account.
required: false
style: form
explode: true
schema:
type: string
example: a:J72REftaRoiaDYRDU7M9FDgf8jeh3eqek9DvKeyBWbuA:3VMczyq7r7b6HwC
- name: filter.destinationAccountId
in: query
description: Identifies the payee/beneficiary's account.
required: false
style: form
explode: true
schema:
type: string
example: a:f34VSeqwfWGTGH23vsa2cDgecew209jdvcd5vdfv4vds:5VSWVRqicm4Csa2
- name: filter.startTimeMs
in: query
description: The filtered list start timestamp in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000.
required: false
style: form
explode: true
schema:
type: string
format: string
example: 67505
- name: filter.endTimeMs
in: query
description: The filtered list end timestamp in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000.
required: false
style: form
explode: true
schema:
type: string
format: string
example: 365650
- name: filter.role
in: query
description: Filters by `accountHolder` role.
required: false
style: form
explode: true
schema:
type: string
example: ISSUER
default: ANY
enum:
- ANY
- FROM
- TO
- ISSUER
- name: filter.actingAsRefId
in: query
description: Filters the list by the sub-TPP identifier generated by Token.io once a TPP has been onboarded.
required: false
style: form
explode: true
schema:
type: string
example: 4kwl35c9sp3fwp4xq
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetTokensResponse'
'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
/tokens/{tokenId}:
get:
tags:
- Tokens
summary: Get a token
description: The `GET /tokens/{tokenId}` endpoint retrieves information about a specific token for the authenticated member.
operationId: GatewayService.GetToken
parameters:
- name: tokenId
in: path
description: Identifies a unique authorization token for a transfer, standing order, or account information access.
required: true
style: simple
explode: false
schema:
type: string
example: tt:8zK1dic95omjWb72gvc3z3ELKbTNfnGd89MbDnM73er4:ZhBVAJSH8DeU1
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetTokenResponse'
'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
/tokens/{tokenId}/cancel:
put:
tags:
- Tokens
summary: Cancel a token
description: The `PUT /tokens/{tokenId}/cancel` endpoint cancels a given token.
operationId: GatewayService.CancelToken
parameters:
- name: token-customer-ip-address
in: header
description: The user's IP address if the user is currently logged in with the TPP. If the customer IP address is supplied (recommended), it is inferred that the user is present during the session (<i>i.e.</i>, the request is user-initiated; adding a `customer-initiated` = `true` header makes this explicit). For AIS calls, if the customer's IP address is not provided in the request, the bank assumes it is a TPP-initiated request and may limit the TPP to 4 TPP-initiated access attempts within a given 24-hour period.
schema:
type: string
format: ipv4
required: false
example: 172.16.254.1
- name: customer-initiated
in: header
description: Informs the bank that the API call was explicitly initiated by the user. This is useful in circumnavigating bank restrictions that impose a 4-times-a-day (<i>i.e.</i>, within the same 24-hour period) access limit on the same AISP, in accordance with RTS regulations.
schema:
type: boolean
required: false
example: true
- name: token-customer-device-id
in: header
description: Obtained by the TPP from details in the user agent information of the user.
schema:
type: string
required: false
example: 00000000-00000000-01234567-89ABCDEF
- name: tokenId
in: path
description: Identifies a unique authorization token for a transfer, standing order, or account information access.
required: true
style: simple
explode: false
schema:
type: string
example: ta:3eYPU1BEKKunfmYgQuSKXFCeo851C5Y3XiZW3XA465TU:5zKtXEAq
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/CancelTokenResponse'
'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
components:
schemas:
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'
Signature:
type: object
properties:
keyId:
type: string
description: The id of the public key used to verify the signature. This is only present if a `tokenId` is present. It can be used to validate that the provided `tokenId` corresponds to the token request (this is needed for Hosted Pages flows only).
example: CqSTHPvWY_dgVh-f
memberId:
type: string
description: The Token.io member id of the signing member.
example: m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq
signature:
type: string
description: The Base64url-encoded ciphertext signature.
example: ODRWmM0xMRM7CKmK3bNl4e2Kb2btavTbZssCsrHsu8yopoKxBzouBrD9q5-E63tgdV1DpB7i31vwNDKywA0CAE
description: Contains information about the signing party. This is only present if a `tokenId` is present. It can be used to validate that the provided `tokenId` corresponds to the token request (this is needed for the Hosted Pages flows only).
CancelTokenResponse:
type: object
properties:
result:
$ref: '#/components/schemas/TokenOperationResult'
inline_response_400:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
AccountIdentifierPlusgiro:
type: object
properties:
plusgiroNumber:
type: string
description: The account number (minimum 2 and maximum 8 digits) for a PlusGiro account. The clearing code is not used.
example: '987654'
description: The domestic transaction clearing system in Sweden. The credit transfer function, which is part of <a href="https://www.nordea.com" target="blank">Nordea</a>, and used for mediating payments between accounts held by companies and individuals.
AccountIdentifierMsisdn:
type: object
properties:
msisdn:
type: string
description: The MSISDN is composed of the country code and the national destination code. Ensure you remove the + sign and any 0 before the mobile number.
example: '447949123456'
description: The Mobile Station International Subscriber Director Number (MSISDN) is the user's mobile phone number, used as a unique identifier to enable routing of voice and SMS traffic to and from a specific subscription/device on a wireless/mobile network.
TokenPayloadAuthorizationMetadataEntry:
type: object
additionalProperties:
type: string
description: Bank-defined authorization property.
description: Bank-defined additional authorization properties.
ActingAs:
type: object
properties:
displayName:
type: string
description: The name of the recipient shown to the user; required when specifying `actingAs`, optional otherwise.
example: The Great Baking Co.
refId:
$ref: '#/components/schemas/refId'
secondaryName:
type: string
description: The domain or email address of the recipient shown to the user along with the `displayName`.
example: jane.doe@company.com
description: Specifies another party for whom the token was created 'on behalf of'.
AccessBodyResourceAccountTransactions:
type: object
properties:
accountId:
type: string
description: The unique identifier for the bank account.
ChargeBearer:
type: string
description: The bearer of the charge, if any, for international transfers. <ul><li><b>CRED</b> - all charges are borne by the creditor.</li> <li><b>DEBT</b> - all charges are borne by the debtor.</li> <li><b>SHAR</b> - the parties share the charges.</li> <li><b>SLEV</b> - each party bears its own charges, recommended on SEPA payments.</li></ul>
example: CRED
default: INVALID_CHARGE_BEARER
enum:
- INVALID_CHARGE_BEARER
- CRED
- DEBT
- SHAR
- SLEV
AccessBodyResourceFundsConfirmation:
type: object
properties:
accountId:
type: string
description: The unique identifier for the bank account.
example: a:J72REftaRoiaDYRDU7M9FDgf8jeh3eqek9DvKeyBWbuA:3VMczyq7r7b6HwC
inline_response_429:
required:
- error
type: object
properties:
error:
$ref: '#/components/schemas/ResourceExhaustedError'
TransferDestinationSepaInstant:
title: sepaInstant
allOf:
- description: SEPA Instant Credit, the instant payment processing system with funds made available immediately for the recipient.
- $ref: '#/components/schemas/SepaInstantAccount'
GetTokensResponse:
type: object
properties:
offset:
type: string
description: The offset of the first item returned in the collection.
example: LerV6Jmex
tokens:
type: array
description: Contains the details of each requested token returned according to the request's filtering parameters.
items:
$ref: '#/components/schemas/Token'
TokenSignature:
type: object
properties:
action:
$ref: '#/components/schemas/TokenSignatureAction'
signature:
$ref: '#/components/schemas/Signature'
description: Contains the respective verified digital signatures for the payload.
AccountIdentifierPan:
type: object
properties:
pan:
type: string
description: The 14, 15, or 16 digit number generated as a unique identifier for a primary account.
example: '4658552288550023'
description: The Primary Account Number (PAN). The card identifier found on payment cards, such as credit cards and debit cards, as well as stored-value cards, gift cards and other similar card, sometimes referred to as a bank card number.
Type:
type: string
description: The types of alias available.
example: EMAIL
default: INVALID
enum:
- INVALID
- UNKNOWN
- EMAIL
- PHONE
- DOMAIN
- BANK
- CUSTOM
- EIDAS
AccountIdentifierBban:
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
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'
TransferDestinationFasterPayments:
title: fasterPayments
allOf:
- description: The interbank payment system in the UK, Full Payment Submission (FPS).
- $ref: '#/components/schemas/FasterPaymentsAccount'
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.
AccessBody:
type: object
properties:
resources:
type: array
items:
$ref: '#/components/schemas/AccessBodyResource'
transactionHistoryDays:
type: integer
description: The number of transaction history days.
format: int32
example: 4
description: Contains the request payload for a token representing account information access permissions.
StetClearingSystemMemberIdentification:
type: object
properties:
clearingSystemId:
type: string
description: The specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed.
memberId:
type: string
description: Identification of a member of a clearing system.
example: m:49DtA9CoF9qYzh77FA9nVrCn2jia:5zKtXEAq
description: Identifies a member within a clearing system; to be used for certain international credit transfers in order to identify the beneficiary bank.
ProviderTransferMetadata:
type: object
oneOf:
- title: CMA9 API
properties:
cma9TransferMetadata:
$ref: '#/components/schemas/Cma9TransferMetadata'
- title: NextGenPSD2
properties:
nextGenPsd2TransferMetadata:
$ref: '#/components/schemas/NextGenPsd2TransferMetadata'
- title: Polish API
properties:
polishApiTransferMetadata:
$ref: '#/components/schemas/PolishApiTransferMetadata'
- title: French PSD2
properties:
stetTransferMetadata:
$ref: '#/components/schemas/StetTransferMetadata'
description: The transfer metadata required under the Open Banking API standard adopted by the bank.
inline_response_501:
required:
- error
type: object
properties:
error:
$ref: '#/components/schemas/NotImplementedError'
StetPostalAddressCreditor:
type: object
properties:
addressLine:
type: array
description: Up to 4 lines that capture the mailing address.
items:
type: string
example: 47 La Grande Rue, Paris
country:
type: string
description: Two-letter country code in upper case (ISO 3166-1 alpha-2).
example: FR
description: Contains the mailing address of the creditor.
StetBeneficiary:
type: object
properties:
creditor:
$ref: '#/components/schemas/StetPartyIdentification'
creditorAccount:
$ref: '#/components/schemas/StetAccountIdentification'
creditorAgent:
$ref: '#/components/schemas/StetFinancialInstitutionIdentification'
id:
type: string
description: The unique identification of an account, a person, or an organisation assigned by an issuer.
description: The creditor or payee receiving the transfer.
Alias:
type: object
properties:
realmId:
type: string
description: Identifies a member created under the realm of a specific bank.
example: m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq
type:
$ref: '#/components/schemas/Type'
value:
type: string
description: The alias string representing the type.
example: e-sales@token.io
description: Alternate or additional member identification information.
TransferDestinationSepa:
title: sepa
allOf:
- description: The Single Euro Payments Area (SEPA), for bank transfers denominated in Euro. This consists of the 27 member states of the European Union, the four member states of the European Free Trade Association (Iceland, Liechtenstein, Norway and Switzerland) and the UK.
- $ref: '#/components/schemas/SepaAccount'
bankId:
type: string
description: The Token.io id of the bank where the consent is created. **This field is required if the customer is not using Token.io's Hosted Pages for bank selection, <i>i.e.</i>, API-only integration when `EMBEDDED_HOSTED_PAGES` is selected in `flowType`, or Hosted Pages embedded (modal) integration.**
example: ob-modelo
GetTokenResponse:
type: object
properties:
token:
$ref: '#/components/schemas/Token'
TransferDestinationBankgiro:
title: bankgiro
allOf:
- description: The identifier for domestic bank accounts in Sweden.
- $ref: '#/components/schemas/BankGiroAccount'
StetPaymentTypeInformation:
type: object
properties:
categoryPurpose:
type: string
description: Specifies the high level purpose of the instruction based on a set of pre-defined categories; used by the initiating party to provide information concerning the processing of the payment and is likely to trigger special processing by any of the agents involved in the payment chain. <ul><li><b>CASH</b> - CashManagementTransfer</li><li><b>CORT</b> - TradeSettlementPayment</li><li><b>DVPM</b> - DeliveryAgainstPayment</li><li><b>INTC</b> - IntraCompanyPayment</li><li><b>TREA</b> - TreasuryPayment</li><li><b>SUPP</b> - SupplierPayment</li></ul>
example: DVPM
default: CASH
enum:
- CASH
- CORT
- DVPM
- INTC
- TREA
- SUPP
instructionPriority:
type: string
description: Indicates the urgency or order of importance the instructing party would like to apply to processing; can be ignored for SCTInst (SEPA Instant).
example: SAMEDAY
localInstrument:
type: string
description: Used to specify a local instrument, local clearing option and/or further qualify the service or service level. For example, INST is used to ask for SEPA instant Payment (SCTInst). For International payments, this field may be valued with one of the <a href="https://www.iso.org/standard/55005.html" target="_blank">ISO 20022</a> external codes to specify which payment instrument should be used by the creditor's bank.
example: INST
serviceLevel:
type: string
description: Only SEPA is allowed.
example: SEPA
description: A set of elements used to further specify the type of transaction.
TransferDestinationToken:
title: token
type: object
properties:
accountId:
type: string
description: The bank account identifier for a linked account used by Token.io's Bank Integration Account Linking Service.
memberId:
type: string
description: The Token.io-generated member id for the user/account holder.
example: m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq
description: The primary account number. The cCard identifier found on payment cards, such as credit and debit cards, as well as stored-value cards, gift cards and other similar cards, somtimes referred to as a bank card number.
TokenPayload:
type: object
oneOf:
- title: PIS - Payments
properties:
transfer:
$ref: '#/components/schemas/TransferBody'
- title: PIS - Standing Orders
properties:
standingOrder:
$ref: '#/components/schemas/StandingOrderBody'
- title: AIS
properties:
access:
$ref: '#/components/schemas/AccessBody'
properties:
actingAs:
$ref: '#/components/schemas/ActingAs'
authorizationMetadata:
$ref: '#/components/schemas/TokenPayloadAuthorizationMetadataEntry'
description:
type: string
description: Description of the payment with the following qualifiers<ul><li>must not contain special characters</li> <li>length must be no greater than 255 characters</li><li>the description in a subsequent call must match description in originating request</li><li>the description omitted in originating request must also be omitted in subsequent calls</li><li>the description omitted in subsequent call will be replaced with `refId`, this field maps to the description in the bank's `consentRequest` presented to the user.<br/>**Warning** - If the description in a subsequent token request for lookups/changes/updates (retrieve, redeem, or cancel) doesn't match the description in the originating token request, an exception is thrown.</li></ul>
example: This describes the payment.
effectiveAtMs:
type: string
description: Sets when the token took effect in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000
format: string
example: '1523514000'
endorseUntilMs:
type: string
description: The token can be endorsed until this time in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000
format: string
example: '254800000'
expiresAtMs:
type: string
description: Token expiration date-time. Access tokens typically have a 90-day lifespan unless overridden by `tokenExpiration` in the original token request. For transfer tokens, this is a bank-optional expiration time. Note - Not all banks support the override of the 90-day default
format: string
example: '29671679919284586'
from:
$ref: '#/components/sche
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/token-io/refs/heads/main/openapi/token-io-tokens-api-openapi.yml