# Notice of change - Additional validations required for v1 payments

Issued: 17th July 2023 | TB-1136

The changes detailed in this Technical Bulletin will become effective in conjunction with [TB-1069 - Changes to id format for Single Immediate Payments and Future Dated Payments](../tech-bulletins/tb-1069)

### What's changing?

We're making the following improvements to Token.io's platform:

#### New validation rules for the [POST /token-requests](../../api/reference/Requests-for-Payments-v1-or-AIS#operation/GatewayService.StoreTokenRequest) call

We're introducing the following validation rules:

- If you set a source, you must have the correct account identifiers for the chosen payment rail, if the `destination` type requires it, *e.g.*, for `sepa`, you should include `iban` and `bic` (optional); for `fasterPayments`, you should include `accountNumber` and `sortCode`.
- If the account identifier in the `requestPayload.transferBody.instructions.transferDestinations` object is missing or does not match the specified payment rail, Token.io will return an error.
- The `currency` code is checked to ensure it is a 3 letter code corresponding to ISO-4217.
- The `lifetimeAmount` is checked to ensure that it's positive.
- The payment type (SIP/FDP) is checked to determine whether the bank supports it.
- An `INVALID_ARGUMENT` error is returned when a bank is not found or does not support a feature.
- An `INVALID_ARGUMENT` error is returned when an `iban` is invalid.
- Only the first entry in the `transferDestinations` list will be sent to the bank.


#### Recommendations for the [POST /token-requests](../../api/reference/Requests-for-Payments-v1-or-AIS#operation/GatewayService.StoreTokenRequest) call

Token.io also recommends the following to minimize the number of errors as a result of passing incorrect values in the [POST /token-requests](../../api/reference/Requests-for-Payments-v1-or-AIS#operation/GatewayService.StoreTokenRequest) call

- Avoid using the Token.io callback url if you're setting your own callback url for the `requestPayload.redirectUrl` field.
- The `requestPayload.refId` and `requestPayload.transferBody.remittanceReference` fields should not exceed 18 characters.
- The `description` field should not exceed 140 characters. Many banks have constraints on the description field that are less than 140 characters. You should check the [GET /banks](../../api/reference/Banks-v1#operation/GatewayService.GetBanks) call for these constraints.


#### Fields no longer supported

Please refer to [v1 fields no longer supported](https://developer.token.io/token_rest_api_doc/content/e-rest/v1-deprecated.htm) for more information on fields that will no longer be supported.

From the 17th October 2023, if a deprecated field is populated its value might be ignored and when a TokenRequest is retrieved, the field might be not be populated, even if it has been populated in the [POST /token-requests](../../api/reference/Requests-for-Payments-v1-or-AIS#operation/GatewayService.StoreTokenRequest) request.

Deprecated enum values will be ignored for optional fields and an error might be thrown for mandatory fields.

In addition, the following will apply:

- The `payloadSignatures` object in the token that is returned in the response of [GET /tokens/{token_id}](../../api/reference/Tokens#operation/GatewayService.GetToken) will no longer be populated.
- The `payloadSignatures` object in the transfers that are returned in the responses of [POST /transfers](../../api/reference/Transfers-for-Payments-v1#operation/GatewayService.CreateTransfer) , [GET /transfers](../../api/reference/Transfers-for-Payments-v1#operation/GatewayService.GetTransfers) and [GET /transfers/{tranfer_id}](../../api/reference/Transfers-for-Payments-v1#operation/GatewayService.GetTransfer) will no longer be populated.
- `GET /tokens` will only be supported for `type = ACCESS` ; `type = TRANSFER` is deprecated and will no longer be supported.
- The following fields in the transfers that are returned in the responses of [POST /transfers](../../api/reference/Transfers-for-Payments-v1#operation/GatewayService.CreateTransfer) , [GET /transfers](../../api/reference/Transfers-for-Payments-v1#operation/GatewayService.GetTransfers) and [GET /transfers/{tranfer_id}](../../api/reference/Transfers-for-Payments-v1#operation/GatewayService.GetTransfer) will no longer be populated:
  - `orderId`
  - `method`
  - `scaStatus`


#### Alternative fields

If you're using any of the deprecated fields for the [POST /token-requests](../../api/reference/Requests-for-Payments-v1-or-AIS#operation/GatewayService.StoreTokenRequest) call in the `requestPayload` object, you'll need to map to alternative fields.

| Deprecated field | Alternative field |
|  --- | --- |
| `transferBody.instructions.source.account` | `transferBody.instructions.source.accountIdentifier` |
| `transferBody.destinationstransferBody.instructions.destinations` | `transferBody.instructions.transferDestinations` |
| `transferBody.amount` | `transferBody.lifetimeAmount` |
| `transferBody.instructions.metadata.merchantCustomerId` | `transferBody.instructions.metadata.providerTransferMetadata.cma9TransferMetadata.risk.merchantCustomerIdentification` |


### What problem will this solve?

These changes will help improve your integration to Token.io and reduce the number of potential failures.

### Does this change affect you?

This change will affect you if you're using any of the fields above that are no longer supported.

This change will affect any TPP using Token.io's v1 endpoints.

### What action do I need to take?

If you are using any of the deprecated fields you'll need to map to alternative fields. Check for backward compatibility.

TPPs will also need to make sure they validate fields along the same lines as Token.io and can handle any validation errors returned by Token.io.

### When will this change apply to all impacted customers?

This change will become effective from 17th October 2023.

### Where can I get further information?

For assistance with the above and other operational aspects of the Token.io Account-to-Account Infrastructure, please contact [Token.io Support](https://support.token.io/).