openapi: 3.0.1
info:
title: Token.io's Open Banking API for TPPs Account on File Requests - for Payments v1 or AIS 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: Requests - for Payments v1 or AIS
description: These endpoints allow you to initiate a Payments v1 request or an AIS request, and retrieve the status of the request.
paths:
/token-requests:
post:
tags:
- Requests - for Payments v1 or AIS
summary: Initiate a token request
description: The `POST /token-requests` endpoint persists the required information used by AIS requests and PIS requests using the API and the Token.io Hosted Pages.
operationId: GatewayService.StoreTokenRequest
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoreTokenRequestRequest'
required: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/StoreTokenRequestResponse'
'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
/token-requests/{requestId}:
get:
tags:
- Requests - for Payments v1 or AIS
summary: Get a token request
description: The `GET /token-requests/{requestId}` endpoint retrieves a specific token request by its id.
operationId: GatewayService.RetrieveTokenRequest
parameters:
- name: requestId
in: path
description: The request id received in response to the original token request.
required: true
style: simple
explode: false
schema:
type: string
example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveTokenRequestResponse'
'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 token request, 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
/token-requests/{tokenRequestId}/result:
get:
tags:
- Requests - for Payments v1 or AIS
summary: Get a token request result
description: The `GET /token-requests/{tokenRequestId}/result` endpoint checks whether a token request result is available. This endpoint will return a `PENDING` status while the result is not available. The status will become `PROCESSED` once the result is available. If the request is rejected by the bank, the status will become `REJECTED`. The status will become `EXPIRED` if the request is not processed or rejected before the token request expiration.
operationId: GatewayService.GetTokenRequestResultWithStatus
parameters:
- name: tokenRequestId
in: path
description: The token request id received in response to the original token request.
required: true
style: simple
explode: false
schema:
type: string
example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetTokenRequestResultWithStatusResponse'
'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 token request, 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
/token-requests/{tokenRequestId}/authorization:
post:
tags:
- Requests - for Payments v1 or AIS
summary: Initiate bank authorization
description: The `POST /token-requests/{tokenRequestId}/authorization` endpoint initiates the bank authorization process with a given bank id and token request id.
operationId: GatewayService.InitiateBankAuthorization
x-internal: true
parameters:
- name: tokenRequestId
in: path
description: The token request id received in response to the original token request.
required: true
style: simple
explode: false
schema:
type: string
example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateBankAuthorizationRequest'
required: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateBankAuthorizationResponse'
'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).
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.
userRefId:
type: string
description: The Token.io-generated unique reference for the user.
example: 3jdaWmcewrj3MX0CDS
tokenId:
type: string
description: Identifies a unique authorization token for a transfer, standing order or account information access.
example: tt:8zK1dic95omjWb72gvc3z3ELKbTNfnGd89MbDnM73er4:ZhBVAJSH8DeU1
TokenRequestPayloadTransferBody:
type: object
required:
- currency
- lifetimeAmount
- instructions
properties:
confirmFunds:
type: boolean
description: If true, sufficient funds available for transfer are confirmed.
format: boolean
example: false
default: false
currency:
type: string
description: The <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank">ISO 4217</a> three letter currency code.
example: EUR
executionDate:
type: string
description: Specifies the execution date for the transfer (in <a href="https://www.iso.org/iso-8601-date-and-time-format.html" target="_blank">ISO 8601</a> format).
example: '2023-02-28'
instructions:
$ref: '#/components/schemas/TransferInstructions'
lifetimeAmount:
type: string
description: The total amount, with up to four digits after the decimal point, transferred over the life of the token.
example: '10000.00'
remittanceReference:
type: string
description: The creditor's reference for matching an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts receivable system.
example: MFt6s64vn6aDyMiwBA3
returnRefundAccount:
type: boolean
description: Requests that a refund account be returned in the response of `GET transfers` for any amounts refunded.
format: boolean
example: false
default: false
setTransferDestinationsUrl:
type: string
description: destination.url.com
description: Contains the financial details of the transfer.
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'.
CredentialFieldType:
type: string
description: Specifies the type of credential.
example: PASSWORD
enum:
- INVALID
- FIELD
- PASSWORD
- PSU_MESSAGE
- IMAGE
- FLICKER
- DECOUPLED
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
ScaStatus:
type: string
description: This status indicates whether the SCA process succeeded or failed.
example: AUTHENTICATED
enum:
- INVALID
- AUTHENTICATED
- AUTHENTICATION_FAILED
- DECLINED_BY_PSU
TokenRequestPayloadAccessBodyResourceType:
type: string
description: Specifies the account resources included in the request.<ul><li>ACCOUNTS – list of accounts with associated names</li><li>BALANCES – current balance of each requested account</li><li>TRANSACTIONS – recorded account activity in terms of debits and credits</li><li>TRANSFER_DESTINATIONS – account number and sort code, where applicable</li><li>STANDING_ORDERS – recorded account activity for the standing order</li></ul>
example: BALANCES
enum:
- ACCOUNTS
- BALANCES
- TRANSACTIONS
- TRANSFER_DESTINATIONS
- STANDING_ORDERS
StandingOrderBodyResponse:
title: PIS - Standing Orders
type: object
required:
- status
properties:
standingOrderSubmissionId:
type: string
description: The unique id of the standing order submission. This is populated for standing order token requests only, it is present if a standing order submission resource is created
example: so:89DSFAkvdfgreJuXmEDV5m2b8ZvLGE91ELf7PPw5BaDab98kMguu:3VMczfjkewrbniu5667
tokenId:
$ref: '#/components/schemas/tokenId'
signature:
$ref: '#/components/schemas/Signature'
status:
$ref: '#/components/schemas/TokenRequestResultStatus'
statusReasonInformation:
$ref: '#/components/schemas/statusReasonInformation'
bankId:
type: string
description: The bank identifier, identical to the `id` in the repsonse to `GET /banks`.
example: ob-modelo
description: Contains the details of the standing order response.
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'
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.
callbackState:
type: string
description: 'The developer-specified string allowing the state to be persisted between the request and callback phases of the flow; used for the signature in a `GET /token-requests/{tokenRequestId}/token-request-result` call, in which the signing payload for the signature is a combination of `state` and `tokenId`, and validates the `tokenId` against the callbackstate originally sent in the request.<br/>Note: The value of `callbackState` is added to the redirect URL and appended to the hash of the CSRF token.'
example: 6242e45e-3063-4c42-8376
TokenRequestOptions:
required:
- to
type: object
properties:
bankId:
$ref: '#/components/schemas/bankId'
from:
$ref: '#/components/schemas/TokenMember'
psuId:
type: string
description: The unique identifier for the bank customer (account holder) providing consent to initiate the request. Recommended to identify group payments initiated by the same user.
example: a:TASDo3124fcsmF0vsmdv4mf4mklsdwls3mcixz14fkasdv5
receiptRequested:
type: boolean
description: Requests email confirmation of the token request.
format: boolean
example: false
default: false
tokenInternal:
$ref: '#/components/schemas/TokenRequestOptionsTokenInternal'
description: Specifies optional request parameters.
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'
TokenRequest:
type: object
properties:
id:
type: string
description: Identifies the token request and is used by the TPP as `requestId`. Add to the base URL to define the endpoint for subsequent requests.
example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
requestOptions:
$ref: '#/components/schemas/TokenRequestOptions'
requestPayload:
$ref: '#/components/schemas/TokenRequestPayload'
description: Contains the response to the submitted request.
RetrieveTokenRequestResponse:
type: object
properties:
tokenRequest:
$ref: '#/components/schemas/TokenRequest'
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.
CredentialFields:
type: object
properties:
fields:
type: array
items:
$ref: '#/components/schemas/CredentialField'
description: Contains information used in embedded authentication flows. These are optional credential request fields. When provided, the TPP should call `initiateBankAuth` again to provide the credentials.
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
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:
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/token-io/refs/heads/main/openapi/token-io-requests-for-payments-v1-or-ais-api-openapi.yml