# Cancel a token

The PUT /tokens/{tokenId}/cancel endpoint cancels a given token.

Endpoint: PUT /tokens/{tokenId}/cancel
Security: Bearer, BasicAuth

## Header parameters:

  - `token-customer-ip-address` (string)
    The user's IP address if the user is currently logged in with the TPP. If the customer  IP address is supplied (recommended), it is inferred that the user is present during the session (i.e., the request is user-initiated; adding a customer-initiated = true header makes this explicit). For AIS calls, if the customer's IP address is not provided in the request, the bank assumes it is a TPP-initiated request and may limit the TPP to 4 TPP-initiated access attempts within a given 24-hour period.
    Example: "172.16.254.1"

  - `customer-initiated` (boolean)
    Informs the bank that the API call was explicitly initiated by the user. This is useful in circumnavigating bank restrictions that impose a 4-times-a-day (i.e., within the same 24-hour period) access limit on the same AISP, in accordance with RTS regulations.
    Example: true

  - `token-customer-device-id` (string)
    Obtained by the TPP from details in the user agent information of the user.
    Example: "00000000-00000000-01234567-89ABCDEF"

## Path parameters:

  - `tokenId` (string, required)
    Identifies a unique authorization token for a transfer, standing order, or account information access.
    Example: "ta:3eYPU1BEKKunfmYgQuSKXFCeo851C5Y3XiZW3XA465TU:5zKtXEAq"

## Response 200 fields (application/json):

  - `result` (object)
    Contains details about the canceled token.

  - `result.status` (string)
    Specifies the success or failure of the cancellation, the condition can be avoided by using a PRIVILEGED signature, rather than LOW or STANDARD.
    Enum: "INVALID", "SUCCESS", "MORE_SIGNATURES_NEEDED"

  - `result.token` (object)
    Contains the details of each requested token returned according to the request's filtering parameters

  - `result.token.id` (string)
    Identifies a unique authorization token for a transfer, standing order, or account information access.
    Example: "ta:3eYPU1BEKKunfmYgQuSKXFCeo851C5Y3XiZW3XA465TU:5zKtXEAq"

  - `result.token.payload` (object)
    Contains the details about the token specified by id.

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

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

  - `result.token.payload.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"

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

  - `result.token.payload.authorizationMetadata` (object)
    Bank-defined additional authorization properties.

  - `result.token.payload.description` (string)
    Description of the payment with the following qualifiersmust not contain special characters length must be no greater than 255 charactersthe description in a subsequent call must match description in originating requestthe description omitted in originating request must also be omitted in subsequent callsthe description omitted in subsequent call will be replaced with refId, this field maps to the description in the bank's consentRequest presented to the user.Warning - If the description in a subsequent token request for lookups/changes/updates (retrieve, redeem, or cancel) doesn't match the description in the originating token request, an exception is thrown.
    Example: "This describes the payment."

  - `result.token.payload.effectiveAtMs` (string)
    Sets when the token took effect in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000
    Example: "1523514000"

  - `result.token.payload.endorseUntilMs` (string)
    The token can be endorsed until this time in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000
    Example: "254800000"

  - `result.token.payload.expiresAtMs` (string)
    Token expiration date-time. Access tokens typically have a 90-day lifespan unless overridden by tokenExpiration in the original token request. For transfer tokens, this is a bank-optional expiration time. Note - Not all banks support the override of the 90-day default
    Example: "29671679919284586"

  - `result.token.payload.from` (object)
    Contains information identifying the Token.io member.

  - `result.token.payload.from.alias` (object)
    Alternate or additional member identification information.

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

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

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

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

  - `result.token.payload.initiatorId` (string)
    The memberId of the member that requested the token creation.
    Example: "m:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq"

  - `result.token.payload.issuer` (object)
    Contains information identifying the Token.io member.

  - `result.token.payload.issuer.alias` (object)
    Alternate or additional member identification information.

  - `result.token.payload.issuer.alias.realmId` (string)
    Identifies a member created under the realm of a specific bank.
    Example: "m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq"

  - `result.token.payload.issuer.alias.type` (string)
    The types of alias available.
    Enum: "INVALID", "UNKNOWN", "EMAIL", "PHONE", "DOMAIN", "BANK", "CUSTOM", "EIDAS"

  - `result.token.payload.issuer.alias.value` (string)
    The alias string representing the type.
    Example: "e-sales@token.io"

  - `result.token.payload.issuer.id` (string, required)
    The Token.io-assigned memberId of the TPP.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `result.token.payload.receiptRequested` (boolean)
    Indicates whether the TPP requested an email confirmation of the token request be sent to the user.

  - `result.token.payload.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"

  - `result.token.payload.to` (object)
    Contains information identifying the Token.io member.

  - `result.token.payload.to.alias` (object)
    Alternate or additional member identification information.

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

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

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

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

  - `result.token.payload.tokenRequestId` (string)
    Identifies the original token request. The value returned in the response to the original token request as the id.
    Example: "rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq"

  - `result.token.payload.version` (string)
    Token.io API version number
    Example: "1.0"

  - `result.token.payloadSignatures` (array)
    Contains information about the payload signatures.

  - `result.token.payloadSignatures.action` (string)
    Specifies the signature validation action.
    Enum: "INVALID", "ENDORSED", "CANCELED"

  - `result.token.payloadSignatures.signature` (object)
    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).

  - `result.token.payloadSignatures.signature.keyId` (string)
    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"

  - `result.token.payloadSignatures.signature.memberId` (string)
    The Token.io member id of the signing member.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `result.token.payloadSignatures.signature.signature` (string)
    The Base64url-encoded ciphertext signature.
    Example: "ODRWmM0xMRM7CKmK3bNl4e2Kb2btavTbZssCsrHsu8yopoKxBzouBrD9q5-E63tgdV1DpB7i31vwNDKywA0CAE"

  - `result.token.replacedByTokenId` (string)
    The id of the latest token replacing the original tokenId.
    Example: "ta:BzFCFwVt5zrt6rdcHJK5imf2HXbGdVdyHKpWQZbgzL5s:qXTkpBAZVbXMxk9vi"

  - `result.token.tokenRequestId` (string)
    Identifies the original token request.
    Example: "rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq"

## 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"