Migrating from Payments v1 to Payments v2

Migrating from Payments v1 to Payments v2 has the following benefits:

• a single endpoint, /payments, instead of separate /token-requests and /transfers endpoints

• more granular status information

• credentials fields are sent upfront for embedded SCA flow

• enhanced filters for GET v2/payments calls compared with GET /transfers

• support for sending a customer-generated state parameter to the bank

When migrating from Payments v1 to Payments v2 , you should consider the following :

• your current integration

• ID format

• payment statuses

• webhooks

• dashboard

• auto redeem

• mapping payment initiation fields

• Payments v1 fields not present in Payments v2

Who can migrate?

The following table indicates whether you can migrate to Payments v2 based on your current integration.

What are you currently using?

API-only	Hosted Pages v1	Hosted Pages v1 for embedded authentication handling only	Settlement accounts	Can you use Payments v2?
		NA
		NA

ID format

The format for ids in Payments v1 changes from:

• tokenId – e.g., tt:BzFCFwVt5zrt6rdcHJK5imf2HXbGdVdyHKpWQZbgzL5s:qXTkpBAZVbXMxk9vi

• transferId – e.g., t:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV

• transfer id - e.g., tt: 83KiRJuXmEDV5m2b8ZvLGE91ELf7PPw5BaDab98kMguu:3VMczyq7r7b6HwC

• requestId – e.g., rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq

to a generic prefix of pm2 for Payments v2:

• all ids – e.g., pm2:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq

Payment statuses

The statuses for Payments v2 differ from the statuses for Payments v1.

Some of these statuses are for information only, whereas others need to be considered triggers for TPP actions.

The following table contains the mappings for converting Payment v1 statuses to Payment v2 statuses.

Webhooks

In Payments v2 you'll receive webhook notifications for status at an earlier stage in the user journey, not just for the transfer object.

For example, if you've configured webhooks, you'll receive a webhook when the payment is first initiated using the POST /v2/payments call and when the GET /v2/payments/{paymentId} request is used to check whether the payment has completed.

Dashboard

If you're using the dashboard to view transactions, Token.io must turn on the dashboard tabs for Payments v2.

Auto redeem

In Payments v2 it's not possible to manually redeem a token; you must have auto redeem turned on. Note that auto redeem is turned on by default for all new TPPs since 22nd February 2023.

Mapping Payments v1 initiation fields to Payments v2 initiation fields

The following table contains the mappings for converting Payments v1 initiation fields to corresponding Payments v2 initiation fields.

Payments v1 fields not present in Payments v2

The following Payments v1 fields do not have a corresponding field in Payments v2 and cannot be mapped to a Payments v2 field.

If you have any feedback about the developer documentation, please contact devdocs@token.io