# Get a token request

The GET /token-requests/{requestId} endpoint retrieves a specific token request by its id.

Endpoint: GET /token-requests/{requestId}
Security: Bearer, BasicAuth

## Path parameters:

  - `requestId` (string, required)
    The request id received in response to the original token request.
    Example: "rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq"

## Response 200 fields (application/json):

  - `tokenRequest` (object)
    Contains the response to the submitted request.

  - `tokenRequest.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.
    Example: "rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq"

  - `tokenRequest.requestOptions` (object)
    Specifies optional request parameters.

  - `tokenRequest.requestOptions.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.
    Example: "ob-modelo"

  - `tokenRequest.requestOptions.from` (object)
    Contains information identifying the Token.io member.

  - `tokenRequest.requestOptions.from.alias` (object)
    Alternate or additional member identification information.

  - `tokenRequest.requestOptions.from.alias.realmId` (string)
    Identifies a member created under the realm of a specific bank.
    Example: "m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq"

  - `tokenRequest.requestOptions.from.alias.type` (string)
    The types of alias available.
    Enum: "INVALID", "UNKNOWN", "EMAIL", "PHONE", "DOMAIN", "BANK", "CUSTOM", "EIDAS"

  - `tokenRequest.requestOptions.from.alias.value` (string)
    The alias string representing the type.
    Example: "e-sales@token.io"

  - `tokenRequest.requestOptions.from.id` (string, required)
    The Token.io-assigned memberId of the TPP.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `tokenRequest.requestOptions.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.
    Example: "a:TASDo3124fcsmF0vsmdv4mf4mklsdwls3mcixz14fkasdv5"

  - `tokenRequest.requestOptions.receiptRequested` (boolean)
    Requests email confirmation of the token request.

  - `tokenRequest.requestOptions.tokenInternal` (object)
    Contains information about the redirect url and Hosted Pages.

  - `tokenRequest.requestOptions.tokenInternal.redirectUrl` (string)
    This URL redirects the user after bank authentication.
    Example: "http://psu-redirect.com"

  - `tokenRequest.requestOptions.tokenInternal.usingWebApp` (boolean)
    If true, this launches the Hosted Pages credentials URL instead of the bank authorization URL.

  - `tokenRequest.requestPayload` (object)
    Contains the details for obtaining the requested token.

  - `tokenRequest.requestPayload.actingAs` (object)
    Specifies another party for whom the token was created 'on behalf of'.

  - `tokenRequest.requestPayload.actingAs.displayName` (string)
    The name of the recipient shown to the user; required when specifying actingAs, optional otherwise.
    Example: "The Great Baking Co."

  - `tokenRequest.requestPayload.actingAs.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.
    Example: "9htio4a1sp2akdr1aa"

  - `tokenRequest.requestPayload.actingAs.secondaryName` (string)
    The domain or email address of the recipient shown to the user along with the displayName.
    Example: "jane.doe@company.com"

  - `tokenRequest.requestPayload.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.
    Example: "6242e45e-3063-4c42-8376"

  - `tokenRequest.requestPayload.countries` (array)
    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.
    Example: ["DE","IT","RO"]

  - `tokenRequest.requestPayload.description` (string)
    Description of the payment with the following qualifiers:must comply with the constraint imposed by the banklength must be no greater than 255 charactersdescription in a subsequent call must match description in originating requestdescription omitted in originating request must also be omitted in subsequent callsdescription omitted in subsequent call will be replaced with refIdthe description field maps to description in the bank's consentRequest presented to the user
    Example: "A regular payment"

  - `tokenRequest.requestPayload.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.

  - `tokenRequest.requestPayload.redirectUrl` (string, required)
    This URL redirects the user after bank authentication.
    Example: "http://psu-redirect.com"

  - `tokenRequest.requestPayload.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.
    Example: "9htio4a1sp2akdr1aa"

  - `tokenRequest.requestPayload.to` (object, required)
    Contains information identifying the Token.io member.

  - `tokenRequest.requestPayload.to.alias` (object)
    Alternate or additional member identification information.

  - `tokenRequest.requestPayload.to.alias.realmId` (string)
    Identifies a member created under the realm of a specific bank.
    Example: "m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq"

  - `tokenRequest.requestPayload.to.alias.type` (string)
    The types of alias available.
    Enum: "INVALID", "UNKNOWN", "EMAIL", "PHONE", "DOMAIN", "BANK", "CUSTOM", "EIDAS"

  - `tokenRequest.requestPayload.to.alias.value` (string)
    The alias string representing the type.
    Example: "e-sales@token.io"

  - `tokenRequest.requestPayload.to.id` (string, required)
    The Token.io-assigned memberId of the TPP.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `tokenRequest.requestPayload.userRefId` (string)
    The Token.io-generated unique reference for the user.
    Example: "3jdaWmcewrj3MX0CDS"

## Response 400 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 401 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 403 fields (application/json):

  - `error` (object, required)
    The error returned when the member is not authorized to perform the given operation: PermissionDenied. This error message will be accompanied by the reason from the bank. Typically this means the access token has expired and the user must re-authenticate with the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 404 fields (application/json):

  - `error` (object, required)
    The error object returned when given payment cannot be found: ResourceNotFound.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The requested entity, the paymentID, was not found.
    Example: "pm2:12345abcd:abcde"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 429 fields (application/json):

  - `error` (object, required)
    Resource exhausted. Too many requests.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The maximum number of requests has been reached.
    Example: "Resource exhausted. Check quota."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 500 fields (application/json):

  - `error` (object)
    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".

  - `error.errorCode` (string, required)
    This is a textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 501 fields (application/json):

  - `error` (object, required)
    The operation was not implemented, supported or enabled by the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The operation was not implemented,supported or enabled by the bank.
    Example: "Not implemented."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 503 fields (application/json):

  - `error` (object, required)
    Service is unavailable, likely due to a transient condition; this is usually corrected with a retry.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The service is unavailable, likely due to a transient condition; this is usually corrected with a retry.
    Example: "Unavailable"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 504 fields (application/json):

  - `error` (object, required)
    The deadline expired before the operation could complete.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The deadline expired before the operation could complete.
    Example: "Deadline exceeded."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"