--- title: "Get a token request" method: GET path: "/token-requests/{requestId}" tags: ["Requests - for Payments v1 or AIS"] --- # Get a token request `GET /token-requests/{requestId}` The `GET /token-requests/{requestId}` endpoint retrieves a specific token request by its id. ## Path parameters - `requestId` string, required ## Response `200` Successful response - RetrieveTokenRequestResponse - `tokenRequest` TokenRequest — Contains the response to the submitted request. - `id` string — Identifies the token request and is used by the TPP as `requestId`. Add to the base URL to define the endpoint for subsequent requests. - `requestOptions` TokenRequestOptions — Specifies optional request parameters. - `bankId` string — 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.e., API-only integration when `EMBEDDED_HOSTED_PAGES` is selected in `flowType`, or Hosted Pages embedded (modal) integration.** - `from` TokenMember — Contains information identifying the Token.io member. - `alias` Alias — Alternate or additional member identification information. - `realmId` string — Identifies a member created under the realm of a specific bank. - `type` 'INVALID' | 'UNKNOWN' | 'EMAIL' | 'PHONE' | 'DOMAIN' | 'BANK' | 'CUSTOM' | 'EIDAS' — The types of alias available. - `value` string — The alias string representing the type. - `id` string, required — The Token.io-assigned `memberId` of the TPP. - `psuId` string — 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. - `receiptRequested` boolean — Requests email confirmation of the token request. - `tokenInternal` TokenRequestOptionsTokenInternal — Contains information about the redirect url and Hosted Pages. - `redirectUrl` string — This URL redirects the user after bank authentication. - `usingWebApp` boolean — If true, this launches the Hosted Pages credentials URL instead of the bank authorization URL. - `requestPayload` union — Contains the details for obtaining the requested token. - object - `transferBody` TokenRequestPayloadTransferBody, required — Contains the financial details of the transfer. - `confirmFunds` boolean — If true, sufficient funds available for transfer are confirmed. - `currency` string, required — The ISO 4217 three letter currency code. - `executionDate` string — Specifies the execution date for the transfer (in ISO 8601 format). - `instructions` TransferInstructions, required — Contains the transfer instructions for each payment. - `metadata` Metadata — Information governing or otherwise related to the transfer instructions. - … - `source` TransferDebtorEndpoint — Contains information about the payer account. - … - `transferDestinations` TransferDestination[], required — The beneficiary account specifying the transfer destination, i.e., TPP/merchant/creditor bank account. - … - `lifetimeAmount` string, required — The total amount, with up to four digits after the decimal point, transferred over the life of the token. - `remittanceReference` string — 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. - `returnRefundAccount` boolean — Requests that a refund account be returned in the response of `GET transfers` for any amounts refunded. - `setTransferDestinationsUrl` string — destination.url.com - `actingAs` ActingAs — Specifies another party for whom the token was created 'on behalf of'. - `displayName` string — The name of the recipient shown to the user; required when specifying `actingAs`, optional otherwise. - `refId` string — The TPP-generated reference identifier for the token. This is not to be confused with the `requestId`. The `refId` maps to the `tppRefId` in the bank's `consentRequest`. This is needed to match/verify the originating token request with the bank's consent request.
We recommend that the `refId` should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length. - `secondaryName` string — The domain or email address of the recipient shown to the user along with the `displayName`. - `callbackState` string — 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.
Note: The value of `callbackState` is added to the redirect URL and appended to the hash of the CSRF token. - `countries` string[] — Specifies the destination country or countries, using the two-letter country code in upper case (ISO 3166-1 alpha-2). This is used to limit the number of countries displayed in the Hosted Pages for user selection. - `description` string — Description of the payment with the following qualifiers: - `disableFutureDatedPaymentConversion` boolean — This field determines whether a payment can been converted from a single immediate payment to a future dated payment. If set to false, payments can be converted. - `redirectUrl` string, required — This URL redirects the user after bank authentication. - `refId` string, required — The TPP-generated reference identifier for the token. This is not to be confused with the `requestId`. The `refId` maps to the `tppRefId` in the bank's `consentRequest`. This is needed to match/verify the originating token request with the bank's consent request.
We recommend that the `refId` should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length. - `to` TokenMember, required — Contains information identifying the Token.io member. - `alias` Alias — Alternate or additional member identification information. - `realmId` string — Identifies a member created under the realm of a specific bank. - `type` 'INVALID' | 'UNKNOWN' | 'EMAIL' | 'PHONE' | 'DOMAIN' | 'BANK' | 'CUSTOM' | 'EIDAS' — The types of alias available. - `value` string — The alias string representing the type. - `id` string, required — The Token.io-assigned `memberId` of the TPP. - `userRefId` string — The Token.io-generated unique reference for the user. - object - `standingOrderBody` StandingOrderBody, required — Contains the request payload for a token representing a standing order/recurring payment. - `amount` string, required — Specifies the transaction amount, with up to four digits after the decimal point, for payments scheduled according to frequency. - `currency` string, required — The ISO 4217 three letter currency code. - `endDate` string — Date when regularly scheduled payments end, in ISO 8601 format. - `frequency` string — Specifies the ISO 20022 code for the scheduled frequency of standing order payments occurring between the first and final payments. Options: - `instructions` TransferInstructions, required — Contains the transfer instructions for each payment. - `metadata` Metadata — Information governing or otherwise related to the transfer instructions. - … - `source` TransferDebtorEndpoint — Contains information about the payer account. - … - `transferDestinations` TransferDestination[], required — The beneficiary account specifying the transfer destination, i.e., TPP/merchant/creditor bank account. - … - `remittanceReference` string — 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. - `returnRefundAccount` boolean — Requests that a refund account be returned in the response of `GET transfers` for any amounts refunded. - `startDate` string — The date when the regularly scheduled payments will start; uses YYYY-MM-DD or YYYYMMDD format. - `actingAs` ActingAs — Specifies another party for whom the token was created 'on behalf of'. - `displayName` string — The name of the recipient shown to the user; required when specifying `actingAs`, optional otherwise. - `refId` string — The TPP-generated reference identifier for the token. This is not to be confused with the `requestId`. The `refId` maps to the `tppRefId` in the bank's `consentRequest`. This is needed to match/verify the originating token request with the bank's consent request.
We recommend that the `refId` should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length. - `secondaryName` string — The domain or email address of the recipient shown to the user along with the `displayName`. - `callbackState` string — 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.
Note: The value of `callbackState` is added to the redirect URL and appended to the hash of the CSRF token. - `countries` string[] — Specifies the destination country or countries, using the two-letter country code in upper case (ISO 3166-1 alpha-2). This is used to limit the number of countries displayed in the Hosted Pages for user selection. - `description` string — Description of the payment with the following qualifiers: - `disableFutureDatedPaymentConversion` boolean — This field determines whether a payment can been converted from a single immediate payment to a future dated payment. If set to false, payments can be converted. - `redirectUrl` string, required — This URL redirects the user after bank authentication. - `refId` string, required — The TPP-generated reference identifier for the token. This is not to be confused with the `requestId`. The `refId` maps to the `tppRefId` in the bank's `consentRequest`. This is needed to match/verify the originating token request with the bank's consent request.
We recommend that the `refId` should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length. - `to` TokenMember, required — Contains information identifying the Token.io member. - `alias` Alias — Alternate or additional member identification information. - `realmId` string — Identifies a member created under the realm of a specific bank. - `type` 'INVALID' | 'UNKNOWN' | 'EMAIL' | 'PHONE' | 'DOMAIN' | 'BANK' | 'CUSTOM' | 'EIDAS' — The types of alias available. - `value` string — The alias string representing the type. - `id` string, required — The Token.io-assigned `memberId` of the TPP. - `userRefId` string — The Token.io-generated unique reference for the user. - object - `accessBody` TokenRequestPayloadAccessBody, required — Contains the request payload for a token representing account information access permissions. - `resourceTypeList` TokenRequestPayloadAccessBodyResourceTypeList — Contains the account resources being requested for access related to multiple accounts. - `resources` TokenRequestPayloadAccessBodyResourceType[], required — Specifies the account resources included in the request. When `resourceTypeList` is used, the `resources` array is required and can’t be empty. - `source` TokenRequestPayloadAccessBodyResourceTypeListSourceAccount - … - `transactionHistoryDays` integer — The number of transaction history days. - `tokenExpiration` string, string — Sets the requested consent expiration for access requests in Unix epoch format. Not all banks support customising the consent expiration or overriding the default. For banks in the EU, the PSD2 regulations specify a default consent period of 180 days. For UK banks, the tokens are long-lived with no default expiry date. The TPP must confirm with the end user every 90 days to ensure that access should continue. We recommend sending this parameter to UK banks to ensure an appropriate consent expiry period is set. - `actingAs` ActingAs — Specifies another party for whom the token was created 'on behalf of'. - `displayName` string — The name of the recipient shown to the user; required when specifying `actingAs`, optional otherwise. - `refId` string — The TPP-generated reference identifier for the token. This is not to be confused with the `requestId`. The `refId` maps to the `tppRefId` in the bank's `consentRequest`. This is needed to match/verify the originating token request with the bank's consent request.
We recommend that the `refId` should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length. - `secondaryName` string — The domain or email address of the recipient shown to the user along with the `displayName`. - `callbackState` string — 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.
Note: The value of `callbackState` is added to the redirect URL and appended to the hash of the CSRF token. - `countries` string[] — Specifies the destination country or countries, using the two-letter country code in upper case (ISO 3166-1 alpha-2). This is used to limit the number of countries displayed in the Hosted Pages for user selection. - `description` string — Description of the payment with the following qualifiers: - `disableFutureDatedPaymentConversion` boolean — This field determines whether a payment can been converted from a single immediate payment to a future dated payment. If set to false, payments can be converted. - `redirectUrl` string, required — This URL redirects the user after bank authentication. - `refId` string, required — The TPP-generated reference identifier for the token. This is not to be confused with the `requestId`. The `refId` maps to the `tppRefId` in the bank's `consentRequest`. This is needed to match/verify the originating token request with the bank's consent request.
We recommend that the `refId` should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length. - `to` TokenMember, required — Contains information identifying the Token.io member. - `alias` Alias — Alternate or additional member identification information. - `realmId` string — Identifies a member created under the realm of a specific bank. - `type` 'INVALID' | 'UNKNOWN' | 'EMAIL' | 'PHONE' | 'DOMAIN' | 'BANK' | 'CUSTOM' | 'EIDAS' — The types of alias available. - `value` string — The alias string representing the type. - `id` string, required — The Token.io-assigned `memberId` of the TPP. - `userRefId` string — The Token.io-generated unique reference for the user. ## Other responses - `400` — The client specified an invalid argument - `401` — The authorization information is missing or invalid - `403` — Permission to access this endpoint is denied - `404` — The requested entity, such as a token request, was not found - `429` — Too many requests - `500` — An unexpected or internal server error - `501` — The operation was not implemented - `503` — Service is unavailable - `504` — Gateway has timed out --- [API](https://skmtc.net/token/apis/token-io-s-open-banking-api-for-tpps.md) · [All operations](https://skmtc.net/token/apis/token-io-s-open-banking-api-for-tpps/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/token/token-io-s-open-banking-api-for-tpps/versions/5e8d6d2c24a1/schema)