openapi: 3.0.1
info:
title: Token.io's Open Banking API for TPPs Account on File Sub-TPPs 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: Sub-TPPs
description: These endpoints are for resellers using Token.io's licence to create, retrieve and delete sub-TPPs.
paths:
/member/sub-tpps:
post:
tags:
- Sub-TPPs
summary: Create a sub-TPP
description: The `POST /member/sub-tpps` endpoint creates a new sub-TPP for a reseller.
operationId: GatewayService.CreateSubTpp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubTppRequest'
required: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubTppResponse'
'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 sub-tpp, 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:
- Sub-TPPs
summary: Get sub-TPPs
description: The `GET /member/sub-tpps` endpoint retrieves a list of all sub-TPPs for a reseller.
operationId: GatewayService.RetrieveSubTpps
parameters:
- 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.byCompanyNames
in: query
description: Filters the sub-TPPs by the list of company names submitted.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
example: '["Company A","Company B","Company C"]'
- name: filter.byRegistrationDates
in: query
description: Filters the sub-TPPs by the list of registration dates submitted.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
example: '["22-03-21","19-05-21","27-07-21"]'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSubTppsResponse'
'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 sub-tpp, 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
/member/sub-tpps/{subTppId}:
get:
tags:
- Sub-TPPs
summary: Get sub-TPP information
description: The `GET /member/sub-tpps/{subTppId}` endpoint retrieves the details of the specified sub-TPP for a reseller.
operationId: GatewayService.RetrieveSubTpp
parameters:
- name: subTppId
in: path
description: This id specifies the sub-TPP to be retrieved.
required: true
style: simple
explode: false
schema:
type: string
example: 8d54f066-c14a-47c0-b58b-fec6b0ed6b4c
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSubTppResponse'
'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 sub-tpp, 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
delete:
tags:
- Sub-TPPs
summary: Delete a sub-TPP
description: The `DELETE /member/sub-tpps/{subTppId}` endpoint deletes an existing sub-TPP for a reseller.
operationId: GatewayService.DeleteSubTpp
parameters:
- name: subTppId
in: path
description: This id specifies the sub-TPP to delete.
required: true
style: simple
explode: false
schema:
type: string
example: 8d54f066-c14a-47c0-b58b-fec6b0ed6b4c
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSubTppResponse'
'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 sub-tpp, 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
/member/sub-tpps/{subTppId}/children:
get:
tags:
- Sub-TPPs
summary: Get sub-TPP children
description: The `GET /member/sub-tpps/{subTppId}/children` endpoint retrieves the sub-TPP children for given sub-TPP.
operationId: GatewayService.RetrieveSubTppChildren
parameters:
- name: subTppId
in: path
description: This id specifies the sub-TPP for which the children are to be retrieved.
required: true
style: simple
explode: false
schema:
type: string
example: 8d54f066-c14a-47c0-b58b-fec6b0ed6b4c
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSubTppChildrenResponse'
'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 sub-tpp, 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:
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'
member.TokenLicensedNonSoleTraderPrivateMerchantGB:
type: object
required:
- merchantJurisdiction
- legalEntityName
- companyRegistrationNumber
- primaryUseCase
- accountNumber
- sortCode
- ubos
- directors
properties:
merchantJurisdiction:
type: string
description: The 'merchantJurisdiction' field specifies the jurisdiction in which the merchant operates. Previously, this field was referred to as the 'domicile country'.
example: GB
legalEntityName:
type: string
description: Full name of the merchant legal entity.
example: Test Merchant Entity Name
companyRegistrationNumber:
type: string
description: Company registration number of merchant legal entity.
example: '123456789'
primaryUseCase:
type: string
description: 'Merchant primary use case. Possible values include: AIS: Accounting package integration, AIS: Cash flow management, AIS: Credit risk analysis, AIS: Customer onboarding / verification, AIS: Personal finance management, PIS: eCommerce merchant payment, PIS: Funding an account, PIS: In store merchant payment, PIS: Paying a bill, PIS: Paying off debt'
example: 'AIS: Accounting package integration'
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'
merchantType:
type: string
description: Type of merchant being onboarded. Determines compliance requirements during onboarding. <ul><li><b>TOKEN_LICENSED_SOLE_TRADER</b>Individually operated business.</li><li><b>LICENSED_TPP_SOLE_TRADER</b>Individually operated business Licensed by TPP.</li><li><b>LICENSED_TPP_NON_SOLE_TRADER</b>Publicly listed company. May require Signatories depending on sub-TPP type.</li><li> <b>TOKEN_LICENSED_NON_SOLE_TRADER_PUBLIC</b>Publicly listed company. May require Signatories depending on sub-TPP type.</li><li><b>TOKEN_LICENSED_NON_SOLE_TRADER_PRIVATE</b>Privately held company. UBOs, Directors, and Signatories will be required depending on sub-TPP type.</li></ul>
example: TOKEN_LICENSED_NON_SOLE_TRADER_PRIVATE
enum:
- TOKEN_LICENSED_NON_SOLE_TRADER_PRIVATE
mccSubType:
type: string
description: Merchant Category Code Subtype, for certain industry this field needs to be provided.
ubos:
type: array
items:
$ref: '#/components/schemas/member.PersonDetail'
directors:
type: array
items:
$ref: '#/components/schemas/member.PersonDetail'
description: Contains information about the merchant member.
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'
inline_response_504:
required:
- error
type: object
properties:
error:
$ref: '#/components/schemas/GatewayTimeoutError'
inline_response_400:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
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_501:
required:
- error
type: object
properties:
error:
$ref: '#/components/schemas/NotImplementedError'
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.
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'
OldMerchantOnboarding:
title: Old Merchant Onboarding Flow
type: object
required:
- name
- domain
- merchant
properties:
domain:
type: string
description: The fully qualified domain name of the sub-TPP, also referred to as the absolute domain name. This specifies an exact location in the tree hierarchy of the Domain Name System (DNS). It must include all domain levels, including the top-level domain and the root zone.
example: somehost.example.com
logo:
pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
type: string
description: This field specifies the image file containing the sub-TPP's logo as a byte array (click <a href="https://thewebdev.info/2021/08/01/how-to-convert-a-file-input-value-to-a-byte-array-with-javascript" target="_blank">here</a> for the JavaScript FileReader instance needed to convert the selected file into a byte array).
format: byte
example: b0Y5cVl6aDc3RkE5blZyQ24yamlh
merchant:
$ref: '#/components/schemas/member.Merchant'
name:
type: string
description: The recognised business name or DBA of the sub-TPP.
example: Sub-TPP Business Ltd
parentSubTppId:
$ref: '#/components/schemas/parentSubTppId'
mccCode:
type: string
description: Merchant Category Code is a four-digit number that classifies the type of goods or services a business offers.
useNewFlow:
type: boolean
example: false
description: When useNewFlow is set to true, the request is handled by the new merchant onboarding flow, rather than by the old flow.
CreateSubTppRequest:
type: object
oneOf:
- $ref: '#/components/schemas/OldMerchantOnboarding'
- $ref: '#/components/schemas/OldMerchantOnboardingGB'
- $ref: '#/components/schemas/TokenLicensedSoleTrader'
- $ref: '#/components/schemas/LicensedTppNonSoleTrader'
- $ref: '#/components/schemas/LicensedTppSoleTrader'
- $ref: '#/components/schemas/TokenLicensedNonSoleTraderPublic'
- $ref: '#/components/schemas/TokenLicensedNonSoleTraderPrivate'
- $ref: '#/components/schemas/TokenLicensedSoleTraderGB'
- $ref: '#/components/schemas/LicensedTppNonSoleTraderGB'
- $ref: '#/components/schemas/LicensedTppSoleTraderGB'
- $ref: '#/components/schemas/TokenLicensedNonSoleTraderPublicGB'
- $ref: '#/components/schemas/TokenLicensedNonSoleTraderPrivateGB'
member.SubTpp.Status:
type: string
example: ACTIVATED
default: INVALID_STATUS
enum:
- INVALID_STATUS
- ACTIVATED
- REJECTED
- AWAITING_APPROVAL
- DEACTIVATED
description: The status of the sub-TPP.
member.TokenLicensedNonSoleTraderPublicMerchantGB:
type: object
required:
- merchantJurisdiction
- legalEntityName
- companyRegistrationNumber
- primaryUseCase
- iban
properties:
merchantJurisdiction:
type: string
description: The 'merchantJurisdiction' field specifies the jurisdiction in which the merchant operates. Previously, this field was referred to as the 'domicile country'.
example: GB
legalEntityName:
type: string
description: Full name of the merchant legal entity.
example: Test Merchant Entity Name
companyRegistrationNumber:
type: string
description: Company registration number of merchant legal entity.
example: '123456789'
primaryUseCase:
type: string
description: 'Merchant primary use case. Possible values include: AIS: Accounting package integration, AIS: Cash flow management, AIS: Credit risk analysis, AIS: Customer onboarding / verification, AIS: Personal finance management, PIS: eCommerce merchant payment, PIS: Funding an account, PIS: In store merchant payment, PIS: Paying a bill, PIS: Paying off debt'
example: 'AIS: Accounting package integration'
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'
merchantType:
type: string
description: Type of merchant being onboarded. Determines compliance requirements during onboarding. <ul><li><b>TOKEN_LICENSED_SOLE_TRADER</b>Individually operated business.</li><li><b>LICENSED_TPP_SOLE_TRADER</b>Individually operated business Licensed by TPP.</li><li><b>LICENSED_TPP_NON_SOLE_TRADER</b>Publicly listed company. May require Signatories depending on sub-TPP type.</li><li> <b>TOKEN_LICENSED_NON_SOLE_TRADER_PUBLIC</b>Publicly listed company. May require Signatories depending on sub-TPP type.</li><li><b>TOKEN_LICENSED_NON_SOLE_TRADER_PRIVATE</b>Privately held company. UBOs, Directors, and Signatories will be required depending on sub-TPP type.</li></ul>
example: TOKEN_LICENSED_NON_SOLE_TRADER_PUBLIC
enum:
- TOKEN_LICENSED_NON_SOLE_TRADER_PUBLIC
mccSubType:
type: string
description: Merchant Category Code Subtype, for certain industry this field needs to be provided.
description: Contains information about the merchant member.
inline_response_503:
required:
- error
type: object
properties:
error:
$ref: '#/components/schemas/ServiceUnavailableError'
RetrieveSubTppsResponse:
type: object
properties:
offset:
type: string
description: The offset of the first item returned in the collection.
example: LerV6Jmex
subTpps:
type: array
description: Contains each sub-TPP member onboarded by the reseller.
items:
$ref: '#/components/schemas/member.SubTpp'
subTppId:
type: string
description: The Token.io-generated identifier for the sub-TPP used by the reseller as the `actingAs.refId` in token requests.
example: 8d54f066-c14a-47c0-b58b-fec6b0ed6b4c
inline_response_404:
required:
- error
type: object
properties:
error:
$ref: '#/components/schemas/PaymentNotFoundError'
TokenLicensedNonSoleTraderPublic:
title: Token Licensed Tpp Non Sole Trader Public
type: object
required:
- name
- domain
- merchant
properties:
domain:
type: string
description: The fully qualified domain name of the sub-TPP, also referred to as the absolute domain name. This specifies an exact location in the tree hierarchy of the Domain Name System (DNS). It must include all domain levels, including the top-level domain and the root zone.
example: somehost.example.com
logo:
pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
type: string
description: This field specifies the image file containing the sub-TPP's logo as a byte array (click <a href="https://thewebdev.info/2021/08/01/how-to-convert-a-file-input-value-to-a-byte-array-with-javascript" target="_blank">here</a> for the JavaScript FileReader instance needed to convert the selected file into a byte array).
format: byte
example: b0Y5cVl6aDc3RkE5blZyQ24yamlh
merchant:
$ref: '#/components/schemas/member.TokenLicensedNonSoleTraderPublicMerchant'
name:
type: string
description: The recognised business name or DBA of the sub-TPP.
example: Sub-TPP Business Ltd
parentSubTppId:
$ref: '#/components/schemas/parentSubTppId'
mccCode:
type: string
description: Merchant Category Code is a four-digit number that classifies the type of goods or services a business offers.
useNewFlow:
type: boolean
description: When useNewFlow is set to true, the request is handled by the new merchant onboarding flow, rather than by the old flow.
LicensedTppNonSoleTrader:
title: Licensed Tpp Non Sole Trader
type: object
required:
- name
- domain
- merchant
properties:
domain:
type: string
description: The fully qualified domain name of the sub-TPP, also referred to as the absolute domain name. This specifies an exact location in the tree hierarchy of the Domain Name System (DNS). It must include all domain levels, including the top-level domain and the root zone.
example: somehost.example.com
logo:
pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
type: string
description: This field specifies the image file containing the sub-TPP's logo as a byte array (click <a href="https://thewebdev.info/2021/08/01/how-to-convert-a-file-input-value-to-a-byte-array-with-javascript" target="_blank">here</a> for the JavaScript FileReader instance needed to convert the selected file into a byte array).
format: byte
example: b0Y5cVl6aDc3RkE5blZyQ24yamlh
merchant:
$ref: '#/components/schemas/member.LicensedTppNonSoleTraderMerchant'
name:
type: string
description: The recognised business name or DBA of the sub-TPP.
example: Sub-TPP Business Ltd
parentSubTppId:
$ref: '#/components/schemas/parentSubTppId'
mccCode:
type: string
description: Merchant Category Code is a four-digit number that classifies the type of goods or services a business offers.
useNewFlow:
type: boolean
description: When useNewFlow is set to true, the request is handled by the new merchant onboarding flow, rather than by the old flow.
member.LicensedTppSoleTraderMerchantGB:
type: object
required:
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/token-io/refs/heads/main/openapi/token-io-sub-tpps-api-openapi.yml