# Token.io's Open Banking API for TPPs Token.io's Open Banking API

Token.io Support: support.token.io

The Token.io Open Banking API enables you to connect securely with banks for a range of services.

Using our API you can:
For more information see our developer documentation. ## Servers ``` https://api.token.io ``` ## Security ### Bearer **For Production and Sandbox environments.**
When using curl samples the authorization header is given as -H `'Authorization: Bearer + JWT'`
Please substitute your Bearer key here.
For example:
-H `'Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjF4N2RmNHZ1RlVIWVFDYTciLCJtaWQiOiJtOlhUalhlMkFQZTRvdmVaalE4cHoyNGdEbUZEcTo1ekt0WEVBcSIsImhvc3QiOiJsb2NhbGhvc3Q6ODAwMCIsIm1ldGhvZCI6IlBPU1QiLCJwYXRoIjoiL2JhbmtzL2lyb24vdXNlcnMiLCJleHAiOjE1ODYyOTczNDQ3ODd9..bi3wxEoMHIul_F2f7gCDvgjHQKCjIyP9_SkQns-yXpS0UqoaOqSJrW89COexU71gt-mH3jH6mtp2aksEywvFDg'`
Enter the JWT Bearer token only (see JWT Authentication for more information). Type: http Scheme: bearer Bearer Format: JWT ### BasicAuth **For Sandbox environment only.**
When using curl samples the authorization header is given as -H `'Authorization: YOUR_API_KEY_HERE'`
Please substitute your Basic key here.
For example:
-H `'Authorization: Basic bS0zanhoS3pqRjRSWFQ1dHZLTlhMQU14cm80d0E1LTV6S3RYRUFxOmU1MWZjZDQ0LTM5MGQtNDYxZi04YjA0LTEyMjcxOTg4YWYwNg=='` Type: apiKey In: header Name: Authorization ## Download OpenAPI description [Token.io's Open Banking API for TPPs](https://docs.token.io/_bundle/products/tpp/api/reference/index.yaml) ## Payments v2 Creates and initiates a single immediate payment or a future-dated payment. Also supports initiating a Variable Recurring Payment (VRP) using an existing VRP mandate that has been created and authorised via the `/vrp-consent` endpoint. ### Initiate a payment - [POST /v2/payments](https://docs.token.io/products/tpp/api/reference/payments-v2/initiatepayment.md): The POST /v2/payments endpoint enables you to initiate a payment with a bank.Once the payment has been initiated, the end user needs to authenticate themselves with their bank.Check payment status:If the status in the initiation response is INITIATION_PENDING_REDIRECT_AUTH or INITIATION_PENDING_REDIRECT_HP, redirect the user to the redirect url found in the authentication payload of the payment, to authenticate at the bank or at Token.io's Hosted Pages.If the status in the initiation response is INITIATION_PENDING_REDIRECT_PBL, redirect the user to the payment link (redirect URL) found in the authentication payload. The user will be taken to Token.io’s Hosted Pages, where any missing information (such as amount or reference) can be provided before proceeding with payment authentication.If the status in the initiation response is INITIATION_PENDING_EMBEDDED_AUTH, collect the requested data listed in the authentication payload of the payment and use the POST /v2/payments/{paymentId}/embedded-auth endpoint to provide the requested field values.If the status in the initiation response is INITIATION_PENDING, Token.io needs more time to process this request with the bank. In the case of a successful scenario, the status will be updated to INITIATION_PENDING_REDIRECT_AUTH, INITIATION_PENDING_EMBEDDED_AUTH or INITIATION_PENDING_DECOUPLED_AUTH when the authentication details are ready. The update can be checked by the GET /v2/payments/{paymentId} endpoint or received via a webhook (see Webhooks).If the status is INITIATION_PENDING_DECOUPLED_AUTH, the bank has requested a decoupled authentication from the user and Token.io is awaiting the result. No further action is required.request-timeout header:Banks may take some time to respond when a request is made. Therefore, Token.io recommends that you set a request-timeout header in your API-only POST /v2/payments requests to match the timeout of your client and avoid DEADLINE_EXCEEDED errors. If this is set, Token.io sends a response when this timeout period has passed and will update payment status as soon as the bank has responded.The following example demonstrates what happens when you set a timeout of 10 seconds and the call to the bank takes 15 seconds:The TPP makes a POST /v2/payments call.Token.io creates a resource with the status INITIATION_PENDING.Token.io starts the call to the bank.After 10 seconds from (1): Token.io returns the payment status INITIATION_PENDING.After 15 seconds from (3): Token.io receives a response from the bank and changes the status to, for example, INITIATION_PENDING_REDIRECT_AUTH. The update will be sent in a webhook, if TPP is subscribed for webhooks.The TPP makes the GET /v2/payments/{id} call and receives the payment with the status INITIATION_PENDING_REDIRECT_AUTH. ### Get payments - [GET /v2/payments](https://docs.token.io/products/tpp/api/reference/payments-v2/getpayments.md): The GET /v2/payments endpoint provides you with a list of payments and their details. ### Get a payment - [GET /v2/payments/{paymentId}](https://docs.token.io/products/tpp/api/reference/payments-v2/getpayment.md): The GET /v2/payments/{paymentId} endpoint provides you with details of an individual payment and checks the payment status for the next step, if any. ### Provide information for embedded authentication - [POST /v2/payments/{paymentId}/embedded-auth](https://docs.token.io/products/tpp/api/reference/payments-v2/provideembeddedfields.md): The POST /v2/payments/{paymentId}/embedded-auth endpoint provides you with the requested information when the payment status is INITIATION_PENDING_EMBEDDED_AUTH. The requested information can be found in the authentication field of the payment. It's possible that some banks might request the user's input multiple times. In this case you might need to call this endpoint again for a new field set. ### Generate QR code - [GET /qr-code](https://docs.token.io/products/tpp/api/reference/payments-v2/getqrcode.md): The GET /qr-code endpoint generates a QR code in fixed SVG format (240x240 px). This allows TPPs to programmatically obtain a scannable QR code . ## Account on File 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. ### Create an Account on File - [POST /tokenized-accounts](https://docs.token.io/products/tpp/api/reference/account-on-file/createtokenizedaccount.md): 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. ### Retrieve an Account on File - [GET /tokenized-accounts/{tokenizedAccountId}](https://docs.token.io/products/tpp/api/reference/account-on-file/gettokenizedaccount.md): Retrieves an Account on File using its tokenizedAccountId. ### Delete an Account on File - [DELETE /tokenized-accounts/{tokenizedAccountId}](https://docs.token.io/products/tpp/api/reference/account-on-file/deletetokenizedaccount.md): Deletes an Account on File. After deletion, the tokenizedAccountId can no longer be used to reference the associated account details in API requests. ## Requests - for Payments v1 or AIS These endpoints allow you to initiate a Payments v1 request or an AIS request, and retrieve the status of the request. ### Initiate a token request - [POST /token-requests](https://docs.token.io/products/tpp/api/reference/requests-for-payments-v1-or-ais/gatewayservice.storetokenrequest.md): 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. ### Get a token request - [GET /token-requests/{requestId}](https://docs.token.io/products/tpp/api/reference/requests-for-payments-v1-or-ais/gatewayservice.retrievetokenrequest.md): The GET /token-requests/{requestId} endpoint retrieves a specific token request by its id. ### Get a token request result - [GET /token-requests/{tokenRequestId}/result](https://docs.token.io/products/tpp/api/reference/requests-for-payments-v1-or-ais/gatewayservice.gettokenrequestresultwithstatus.md): 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. ### Initiate bank authorization - [POST /token-requests/{tokenRequestId}/authorization](https://docs.token.io/products/tpp/api/reference/requests-for-payments-v1-or-ais/gatewayservice.initiatebankauthorization.md): The POST /token-requests/{tokenRequestId}/authorization endpoint initiates the bank authorization process with a given bank id and token request id. ## Transfers - for Payments v1 These endpoints relate to transfers, which are requests to move money between accounts. ### Redeem a transfer token - [POST /transfers](https://docs.token.io/products/tpp/api/reference/transfers-for-payments-v1/gatewayservice.createtransfer.md): The POST /transfers endpoint is only required when you explicitly redeem the request token, i.e., auto-redeem is not enabled. ### Get transfers - [GET /transfers](https://docs.token.io/products/tpp/api/reference/transfers-for-payments-v1/gatewayservice.gettransfers.md): The GET /transfers endpoint retrieves information for all transfers. ### Get a transfer - [GET /transfers/{transferId}](https://docs.token.io/products/tpp/api/reference/transfers-for-payments-v1/gatewayservice.gettransfer.md): The GET /transfers/{transferId} endpoint retrieves information about a specific transfer in a given account. ## Variable Recurring Payments These endpoints enable you to initiate Variable Recurring Payments (VRP). Note, that VRP is also available in Payments v2 API. ### Create a VRP consent - [POST /vrp-consents](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/createvrpconsent.md): The POST /vrp-consents endpoint creates a new VRP consent. ### Get VRP consents - [GET /vrp-consents](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/getvrpconsents.md): The GET /vrp-consents endpoint retrieves all VRP consents created by the calling member. ### Get a VRP consent - [GET /vrp-consents/{id}](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/getvrpconsent.md): The GET /vrp-consents/{id} endpoint retrieves the details for an individual VRP consent. ### Revoke a VRP consent - [DELETE /vrp-consents/{id}](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/revokevrpconsent.md): The DELETE /vrp-consents/{id} endpoint revokes an individual VRP consent. ### Get payments under a VRP consent - [GET /vrp-consents/{id}/payments](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/getvrpconsentpayments.md): The GET /vrp-consents/{id}/payments endpoint retrieves the payments under a given VRP consent. ### Initiate a VRP payment - [POST /vrps](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/createvrp.md): The POST /vrps initiates a new VRP payment. ### Get VRP payments - [GET /vrps](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/getvrps.md): The GET /vrps endpoint provides you with a list of vrp payments and their details. ### Get a VRP payment - [GET /vrps/{id}](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/getvrp.md): The GET /vrps/{id} endpoint retrieves the details for an individual VRP payment. ### Verify if funds are available or not - [GET /vrps/{id}/confirm-funds](https://docs.token.io/products/tpp/api/reference/variable-recurring-payments/confirmfunds.md): The GET /vrps/{id}/confirm-funds endpoint confirms whether the funds are available to initiate VRP. ## Refunds These endpoints allow you to handle registration, posting, and retrieval of refunds associated with original transaction account information. ### Initiate a refund - [POST /refunds](https://docs.token.io/products/tpp/api/reference/refunds/initiaterefund.md): The POST /refunds endpoint initiates a refund. After the refund is settled, the refund status of the original transfer will be updated. The debtor field can be optional if you're using the debtor in registration. The creditor field can be optional if the information is available in the original payment. ### Get refunds - [GET /refunds](https://docs.token.io/products/tpp/api/reference/refunds/getrefunds.md): The GET /refunds endpoint retrieves a complete or filtered list of refunds. ### Get a refund - [GET /refunds/{id}](https://docs.token.io/products/tpp/api/reference/refunds/getrefund.md): The GET /refunds/{id} endpoint retrieves a given refund. ### Get all refunds by transfer - [GET /transfers/{id}/refunds](https://docs.token.io/products/tpp/api/reference/refunds/gettransferrefunds.md): The GET /transfers/{id}/refunds endpoint retrieves all refunds associated with a given transfer. ## Payouts These endpoints allow you to make payouts. ### Initiate a payout - [POST /payouts](https://docs.token.io/products/tpp/api/reference/payouts/initiatepayout.md): The POST /payouts endpoint initiates a payout. ### Get payouts - [GET /payouts](https://docs.token.io/products/tpp/api/reference/payouts/getpayouts.md): The GET /payouts endpoint retrieves a complete or filtered list of payouts. ### Get a payout - [GET /payouts/{id}](https://docs.token.io/products/tpp/api/reference/payouts/getpayout.md): The GET /payouts/{id} endpoint retrieves a given payout. ## Settlement Accounts These endpoints provide authorized access to an authenticated user's settlement account information, enabling you to create settlement accounts, retrieve settlement account details, transactions and payouts, and manage settlement rules. ### Create a settlement account - [POST /virtual-accounts](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.createvirtualaccount.md): The POST /virtual-accounts endpoint creates a settlement account. ### Get settlement accounts - [GET /virtual-accounts](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.getvirtualaccounts.md): The GET /virtual-accounts endpoint retrieves information for all settlement accounts. ### Get a settlement account - [GET /virtual-accounts/{accountId}](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.getvirtualaccountbyid.md): The GET /virtual-accounts/{accountId} endpoint the information, for a given settlement account. ### Get settlement account transactions - [GET /virtual-accounts/{accountId}/transactions](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.getvirtualaccounttransactions.md): The GET /virtual-accounts/{accountId}/transactions endpoint retrieves transcation information in a given settlement account. ### Get a settlement account transaction - [GET /virtual-accounts/{accountId}/transactions/{providerPaymentId}](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.getvirtualaccounttransaction.md): The GET /virtual-accounts/{accountId}/transactions/{providerPaymentId} endpoint retrieves information for a specific transaction in a given settlement account. ### Create a settlement rule - [POST /virtual-accounts/{accountId}/settlement-rule](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.createvirtualaccountsettlementrule.md): The POST /virtual-accounts/{accountId}/settlement-rule endpoint creates a settlement rule, for a given settlement account. ### Get settlement rules - [GET /virtual-accounts/{accountId}/settlement-rules](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.getvirtualaccountsettlementrules.md): The GET /virtual-accounts/{accountId}/settlement-rules endpoint retrieves information about settlement rules, for a given settlement account, according to the settlement rule status in the request. If no status is provided, the endpoint retrieves all settlement rules for the settlement account. ### Get a settlement rule - [GET /virtual-accounts/{accountId}/settlement-rules/{settlementRuleId}](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.getvirtualaccountsettlementrule.md): The GET /virtual-accounts/{accountId}/settlement-rules/{settlementRuleId} endpoint retrieves information for a specific settlement rule, for a given settlement account. ### Delete a settlement rule - [DELETE /virtual-accounts/{accountId}/settlement-rules/{settlementRuleId}](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.deletevirtualaccountsettlementrule.md): The DELETE /virtual-accounts/{accountId}/settlement-rules/{settlementRuleId} endpoint delete an active settlement rule, for a given settlement account. ### Get settlement account payouts - [GET /virtual-accounts/{accountId}/settlement-rule-payouts](https://docs.token.io/products/tpp/api/reference/settlement-accounts/gatewayservice.getvirtualaccountsettlementpayouts.md): The GET /virtual-accounts/{accountId}/settlement-rule-payouts endpoint retrieves information about payouts created by a settlement rule, for a given settlement account. ## Accounts These endpoints provide authorized access to an authenticated user's account information. ### Get information for all accounts - [GET /accounts](https://docs.token.io/products/tpp/api/reference/accounts/gatewayservice.getaccounts.md): The GET /accounts endpoint retrieves information for all bank accounts. ### Get account information - [GET /accounts/{accountId}](https://docs.token.io/products/tpp/api/reference/accounts/gatewayservice.getaccount.md): The GET /accounts/{accountId} endpoint retrieves the information for a specific bank account. ### Get account balances - [GET /account-balance](https://docs.token.io/products/tpp/api/reference/accounts/gatewayservice.getbalances.md): The GET /account-balance endpoint retrieves the balances for multiple bank accounts. ### Get an account balance - [GET /accounts/{accountId}/balance](https://docs.token.io/products/tpp/api/reference/accounts/gatewayservice.getbalance.md): The GET /accounts/{accountId}/balance endpoint retrieves the balance for a given bank account. ### Get information for all standing orders - [GET /accounts/{accountId}/standing-orders](https://docs.token.io/products/tpp/api/reference/accounts/gatewayservice.getstandingorders.md): The GET /accounts/{accountId}/standing-orders endpoint retrieves information for all standing orders in a given account, once consent has been given. ### Get standing order information - [GET /accounts/{accountId}/standing-orders/{standingOrderId}](https://docs.token.io/products/tpp/api/reference/accounts/gatewayservice.getstandingorder.md): The GET /accounts/{accountId}/standing-orders/{standingOrderId} endpoint retrieves information for a specific standing order in a given account, once consent has been given. ### Get account transactions - [GET /accounts/{accountId}/transactions](https://docs.token.io/products/tpp/api/reference/accounts/gatewayservice.gettransactions.md): The GET /accounts/{accountId}/transactions endpoint retrieves information for all transactions in a given account. ### Get transaction information - [GET /accounts/{accountId}/transaction/{transactionId}](https://docs.token.io/products/tpp/api/reference/accounts/gatewayservice.gettransaction.md): The GET /accounts/{accountId}/transaction/{transactionId} endpoint retrieves information for a specific transaction in a given account. ## Tokens These endpoints retrieve all tokens, a filtered list of tokens, or a specific token, as well as allowing you to cancel an existing token. ### Get tokens - [GET /tokens](https://docs.token.io/products/tpp/api/reference/tokens/gatewayservice.gettokens.md): The GET /tokens endpoint retrieves a list of all tokens for the authenticated member. ### Get a token - [GET /tokens/{tokenId}](https://docs.token.io/products/tpp/api/reference/tokens/gatewayservice.gettoken.md): The GET /tokens/{tokenId} endpoint retrieves information about a specific token for the authenticated member. ### Cancel a token - [PUT /tokens/{tokenId}/cancel](https://docs.token.io/products/tpp/api/reference/tokens/gatewayservice.canceltoken.md): The PUT /tokens/{tokenId}/cancel endpoint cancels a given token. ## Banks v1 These endpoints filter and fetch the list of connected banks, get information on specific banks, and initiate authorization with user-selected banks using Payments v1. ### Get banks v1 - [GET /banks](https://docs.token.io/products/tpp/api/reference/banks-v1/gatewayservice.getbanks.md): The GET /banks endpoint retrieves a list of connected banks matching the parameters specified. ### Get bank countries - [GET /bank/countries](https://docs.token.io/products/tpp/api/reference/banks-v1/gatewayservice.getbankscountries.md): The GET /banks/countries endpoint retrieves the list of countries that have connected banks which match the parameters specified. ## Banks v2 This endpoint filters and fetches the list of connected banks, gets information on specific banks, and initiates authorization with user-selected banks using Payments v2. ### Get banks v2 - [GET /v2/banks](https://docs.token.io/products/tpp/api/reference/banks-v2/getbanksv2.md): The GET /v2/banks endpoint retrieves a list of connected banks matching the parameters specified. ## Sub-TPPs These endpoints are for resellers using Token.io's licence to create, retrieve and delete sub-TPPs. ### Create a sub-TPP - [POST /member/sub-tpps](https://docs.token.io/products/tpp/api/reference/sub-tpps/gatewayservice.createsubtpp.md): The POST /member/sub-tpps endpoint creates a new sub-TPP for a reseller. ### Get sub-TPPs - [GET /member/sub-tpps](https://docs.token.io/products/tpp/api/reference/sub-tpps/gatewayservice.retrievesubtpps.md): The GET /member/sub-tpps endpoint retrieves a list of all sub-TPPs for a reseller. ### Get sub-TPP information - [GET /member/sub-tpps/{subTppId}](https://docs.token.io/products/tpp/api/reference/sub-tpps/gatewayservice.retrievesubtpp.md): The GET /member/sub-tpps/{subTppId} endpoint retrieves the details of the specified sub-TPP for a reseller. ### Delete a sub-TPP - [DELETE /member/sub-tpps/{subTppId}](https://docs.token.io/products/tpp/api/reference/sub-tpps/gatewayservice.deletesubtpp.md): The DELETE /member/sub-tpps/{subTppId} endpoint deletes an existing sub-TPP for a reseller. ### Get sub-TPP children - [GET /member/sub-tpps/{subTppId}/children](https://docs.token.io/products/tpp/api/reference/sub-tpps/gatewayservice.retrievesubtppchildren.md): The GET /member/sub-tpps/{subTppId}/children endpoint retrieves the sub-TPP children for given sub-TPP. ## Authentication keys These endpoints are for managing the public keys that are used for JWT authentication. ### Submit a public key - [POST /member/{memberId}/keys](https://docs.token.io/products/tpp/api/reference/authentication-keys/gatewayservice.addmemberkey.md): The POST /member/{memberId}/keys endpoint submits a public key for authentication, for the specified member. ### Get public keys - [GET /member/{memberId}/keys](https://docs.token.io/products/tpp/api/reference/authentication-keys/gatewayservice.getmemberkeys.md): The GET /member/{memberId}/keys endpoint retrieves a list of all public keys, for the specified member. ### Get a public key - [GET /member/{memberId}/keys/{keyId}](https://docs.token.io/products/tpp/api/reference/authentication-keys/gatewayservice.getmemberkey.md): The GET /member/{memberId}/keys/{keyId} endpoint retrieves the details of a specific public key, for the specified member. ### Delete a public key - [DELETE /member/{memberId}/keys/{keyId}](https://docs.token.io/products/tpp/api/reference/authentication-keys/gatewayservice.deletememberkey.md): The DELETE /member/{memberId}/keys/{keyId} endpoint deletes an existing public key, for the specified member. ## Reports These endpoints retrieve the current AIS and PIS status of connected banks. ### Get bank statuses - [GET /reports/banks/status](https://docs.token.io/products/tpp/api/reference/reports/gatewayservice.getbanksstatus.md): The GET /reports/banks/status endpoint returns the current AIS and PIS service status along with server status for all banks. ### Get a bank status - [GET /reports/banks/{bankId}/status](https://docs.token.io/products/tpp/api/reference/reports/gatewayservice.getbankstatus.md): The GET /reports/banks/{bankId}/status endpoint returns the current AIS and PIS service status for a specific bank. ## Webhooks These endpoints configure, retrieve and remove webhooks. See Webhooks for more details. ### Set webhook config - [PUT /webhook/config](https://docs.token.io/products/tpp/api/reference/webhooks/gatewayservice.setwebhookconfig.md): The PUT /webhook/config endpoint sets the webhook configuration. ### Get webhook config - [GET /webhook/config](https://docs.token.io/products/tpp/api/reference/webhooks/gatewayservice.getwebhookconfig.md): The GET /webhook/config endpoint retrieves the webhook configuration. ### Delete webhook config - [DELETE /webhook/config](https://docs.token.io/products/tpp/api/reference/webhooks/gatewayservice.deletewebhookconfig.md): The DELETE /webhook/config endpoint deletes the webhook configuration. ## Verification ### Initiate an account verification check - [POST /account-verifications](https://docs.token.io/products/tpp/api/reference/verification/post-verification.md): This endpoint allows clients to verify whether the provided account details (such as sort code and account number or IBAN) match the name of the intended account holder, whether an individual or a business