# 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](../../api/reference/Payments-v2#operation/GetPayments) calls compared with [GET /transfers](../../api/reference/Transfers-for-Payments-v1#operation/GatewayService.GetTransfers) - 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](#Who_can_migrate) - [ID format](#ID_format) - [payment statuses](#Payment_statuses) - [webhooks](#Webhooks) - [dashboard](#Dashboard) - [auto redeem](#Auto_redeem) - [mapping payment initiation fields](#Mapping) - [Payments v1 fields not present in Payments v2](#Deprecated) ### 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 See [Technical Bulletin - 1069 - Changes to id format for Single Immediate Payments and Future Dated Payments](../tech-bulletins/tb-1069) for more information. ### Payment statuses The statuses for [Payments v2](./sip-v2-considerations#payment-status) differ from the statuses for [Payments v1](..//sip-v1/sip-v1-considerations#payment-initiation-status). 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. | Payments v1 status | Payments v2 status | | --- | --- | | `PENDING` | `INITIATION_PENDING` | | `PENDING_EXTERNAL_AUTHORIZATION` | `INITIATION_PENDING_REDIRECT_AUTH` | | `PROCESSING` | `INITIATION_PROCESSING` | | `SUCCESS` | `INITIATION_COMPLETED` | | `INITIATED` | `INITIATION_NO_FINAL_STATUS_AVAILABLE` | | `FAILURE_GENERIC` | `INITIATION_REJECTED` or `INITIATION_FAILED` | | `FAILURE_PERMISSION_DENIED` | `INITIATION_REJECTED` | | `FAILURE_CANCELED` | `INITIATION_DECLINED` | | `FAILURE_EXPIRED` | `INITIATION_EXPIRED` | | `FAILURE_INSUFFICIENT_FUNDS` | `INITIATION_REJECTED_INSUFFICIENT_FUNDS` | | `FAILURE_DECLINED` | `INITIATION_DECLINED` | | `SETTLEMENT_IN_PROGRESS` | `SETTLEMENT_IN_PROGRESS` | | `SETTLEMENT_INCOMPLETE` | `SETTLEMENT_INCOMPLETE` | | `SETTLEMENT_COMPLETED` | `SETTLEMENT_COMPLETED` | ### 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](../../api/reference/Payments-v2#operation/InitiatePayment) call and when the [GET /v2/payments/{paymentId}](../../api/reference/Payments-v2#operation/GetPayment) request is used to check whether the payment has completed. See [API-only integration](./sip-v2-api-intro) in [Payments v2](./sip-v2-intro) for more information. ### 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. See [Technical Bulletin - 022123 - Enhancement to provide Auto redeem for 2-step payments](../tech-bulletins/tb-022123) for more information about auto redeem. ### 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 initiation field | Payments v2 initiation field | | --- | --- | | POST /token-requests request | POST /v2/payments request | | requestOptions.bankId | initiation.bankId | | requestPayload.to | initiation.refId | | requestPayload.actingAs | initiation.onBehalfOf | | requestPayload.description | initiation.remittanceInformationSecondary | | requestPayload.redirectUrl | initiation.callbackUrl | | requestPayload.refId | initiation.refId | | requestPayload.transferbody.amount | initiation.amount.value | | requestPayload.transferbody.confirmFunds | initiation.confirmFunds | | requestPayload.transferbody.currency | initiation.amount.currency | | requestPayload.transferbody.executionDate | initiation.executionDate | | requestPayload.transferbody.instructions.metadata.chargeBearer | initiation.chargeBearer | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.cma9TransferMetadata.endToEndIdentification | initiation.refId | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.cma9TransferMetadata.remittanceInformation | initiation.remittanceInformationPrimary | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.cma9TransferMetadata.risk | initiation.risk | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.nextGenPsd2TransferMetadata.endToEndIdentification | initiation.refId | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.nextGenPsd2TransferMetadata.remittanceInformationStructured | initiation.remittanceInformationPrimary | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.stetTransferMetadata.beneficiary | initiation.creditor | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.stetTransferMetadata.endtoendId | initiation.refId | | requestPayload.transferbody.instructions.metadata.purposeCode | initiation.risk.paymentPurposeCode | | requestPayload.transferbody.instructions.metadata.ultimateCreditor | initiation.creditor.ultimateCreditorName | | requestPayload.transferbody.instructions.metadata.ultimateDebtor | initiation.debtor.ultimateDebtorName | | requestPayload.transferbody.instructions.source.accountIdentifier | initiation.debtor | | requestPayload.transferbody.instructions.source.bic | initiation.debtor | | requestPayload.transferbody.instructions.source.customerData | initiation.debtor | | requestPayload.transferbody.instructions.transferDestinations | initiation.localInstrument | | transferbodty.remittanceReference* | initiation.remittanceInformationPrimary | | POST /transfers response | POST /v2/payments response | | transfer.createdAtMs | payment.createdDateTime | | transfer.executionDate | payment.initiation.executionDate | | transfer.id | payment.initiation.amount.value | | transfer.payload.amount | payment.id | | transfer.payload.confirmFunds | payment.initiation.confirmFunds | | transfer.payload.description | payment.initiation.remittanceInformationSecondary | | transfer.payload.metadata.chargeBearer | payment.initiation.chargeBearer | | transfer.payload.metadata.providerTransferMetadata.cma9TransferMetadata.endToEndIdentification | payment.initiation.refId | | transfer.payload.metadata.providerTransferMetadata.cma9TransferMetadata.remittanceInformation* | payment.initiation.remittanceInformationPrimary | | transfer.payload.metadata.providerTransferMetadata.cma9TransferMetadata.risk | payment.initiation.risk | | transfer.payload.metadata.providerTransferMetadata.nextGenPsd2TransferMetadata.endToEndIdentification | payment.initiation.refId | | transfer.payload.metadata.providerTransferMetadata.nextGenPsd2TransferMetadata.remittanceInformationStructured* | payment.initiation.remittanceInformationPrimary | | transfer.payload.metadata.providerTransferMetadata.stetTransferMetadata.beneficiary | payment.initiation.creditor | | transfer.payload.metadata.providerTransferMetadata.stetTransferMetadata.endtoendId | payment.initiation.refId | | transfer.payload.metadata.purposeCode | payment.initiation.risk.paymentPurposeCode | | transfer.payload.metadata.ultimateCreditor | payment.initiation.creditor.ultimateCreditorName | | transfer.payload.metadata.ultimateDebtor | payment.initiation.debtor.ultimateDebtorName | | requestPayload.transferbody.instructions.transferDestinations | payment.initiation.localInstrument | | transfer.payload.refId | payment.initiation.refId | | transfer.payload.tokenId | payment.id | | transfer.providerDetails.id | payment.bankPaymentId | | transfer.provideDetails.status | payment.bankPaymentStatus | | transfer.source | payment.initiation.debtor | | transfer.status | payment.status | | transfer.statusInformationReason | payment.statusInformationReason | | transfer.transactionid | payment.bankTransactionId | ### 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. | Payments v1 fields not present in Payments v2 | | --- | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.cma9TransferMetadata.instructionIdentification | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.nextGenPsd2TransferMetadata.creditorAgent | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.nextGenPsd2TransferMetadata.creditorAgentName | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.polishApiTransferMetadata.deliveryMode | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.polishApiTransferMetadata.hold | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.stetTransferMetadata.debtorAgent | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.stetTransferMetadata.executionRule | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.stetTransferMetadata.paymentTypeInformation | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.stetTransferMetadata.regulatoryReportingCodes | | transfer.payload.metadata.providerTransferMetadata.cma9TransferMetadata.instructionIdentification | | transfer.payload.metadata.providerTransferMetadata.nextGenPsd2TransferMetadata.creditorAgent | | transfer.payload.metadata.providerTransferMetadata.nextGenPsd2TransferMetadata.creditorAgentName | | requestPayload.transferbody.instructions.metadata.providerTransferMetadata.polishApiTransferMetadata.deliveryMode | | transfer.payload.metadata.providerTransferMetadata.polishApiTransferMetadata.hold | | transfer.payload.metadata.providerTransferMetadata.stetTransferMetadata.debtorAgent | | transfer.payload.metadata.providerTransferMetadata.stetTransferMetadata.executionRule | | transfer.payload.metadata.providerTransferMetadata.stetTransferMetadata.paymentTypeInformation | | transfer.payload.metadata.providerTransferMetadata.stetTransferMetadata.regulatoryReportingCodes | | transfer.payloadSignature | If you have any feedback about the developer documentation, please contact [devdocs@token.io](mailto:devdocs@token.io)