Skip to content
/
TB-1236 - Recommended hea...
Last updated

Notice of change - Recommended header fields for GET /accounts endpoints and the PUT /tokens/{tokenId}/cancel endpoint

Issued: 24th October 2023 | TB-1236

Updated: 10th November 2023

Updated: 5th April 2024

Updated: 11th July 2024

What's changing?

Token.io recommends that when a user has logged in to a TPP’s application and is initiating a request, the TPP should include the user's IP address in the token-customer-ip-address header field.

curl --location 'https://api.token.io/accounts' \
--header 'Authorization: Basic <AUTH_TOKEN>' \
--header 'Content-Type : application/json' \
--header 'token-customer-ip-address: 192.0.2.1' \

**Providing public user IP addresses is a useful for TPPs, as in many cases validation is applied on the bank's side.
If the user IP address is not provided for AIS use cases, they may be treated as a user-offline. In this scenario, consent will only be given for three (or similar) requests per day.
It is not Token.io's policy to collect user IP addresses for all API clients/banks, as this information is rarely contained in the bank documentation. Moreover, banks may be implementing this validation without notifying Token.io, so this information will become outdated, if collected.
According to NextGen 2 standards, it is mandatory that the forwarded IP address header field consists of the corresponding HTTP request IP address field between the user and TPP. If not available, the TPP should use the IP address used by the TPP when submitting the request.
**

This recommendation applies to the following /accounts endpoints, for AIS requests:

and the following /tokens endpoint, for AIS and PIS requests:

In addition, the following header fields are recommended for use with the PUT /tokens/{tokenId}/cancel endpoint, for both AIS and PIS requests:

  • customer-initiated

  • token-customer-device-id

curl --location 'https://api.token.io/tokens'
--header 'Authorization: Basic <AUTH_TOKEN>' \
--header 'Content-Type : application/json' \
--header 'token-customer-ip-address: 192.0.2.1' \
--header 'customer-initiated: true' \
--header 'token-customer-device-id: 00000000-00000000-01234567-89ABCDEF' \

Please refer to the Common request headers section in API Basics and the API reference for further information about these fields.

What problem will this solve?

Using the token-customer-ip-address header field will enable Token.io to send the correct IP address to the bank, and will therefore improve conversion rates. In addition, some banks require this information for their Anti Money Laundering (AML) policies.

Using the customer-initiated and token-customer-device-id header fields will let the bank know whether the API call was explicitly initiated by the user and provide further information about the user's device. This information will help in tracking fraudulent transactions.

Does this change affect you?

This change will impact any customer initiating a request to Token.io when the user is in session.

What action do I need to take?

This is an optional change and you can implement none or any combination of the headers. To apply the change you'll need to:

  • capture the user's IP address and present it in the token-customer-ip-address header field.

  • determine whether the API call was initiated by the user and present this information in the customer-initiated header field, in Boolean format.

  • capture the id of the users device and present this in the token-customer-device-id header field.

When will this change apply to all impacted customers?

This change is effective immediately.

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.

Previous page
Next page