Notice of change - Additional validations required for v1 payments

Issued: 17th July 2023 | TB-1136

What's changing?

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

New validation rules for the POST /token-requests 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 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 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 call for these constraints.

Fields no longer supported

Please refer to v1 fields no longer supported 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 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} will no longer be populated.

• The payloadSignatures object in the transfers that are returned in the responses of POST /transfers , GET /transfers and GET /transfers/{tranfer_id} 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 , GET /transfers and GET /transfers/{tranfer_id} will no longer be populated:

  • orderId

  • method

  • scaStatus

Alternative fields

If you're using any of the deprecated fields for the POST /token-requests call in the requestPayload object, you'll need to map to alternative fields.

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.