# Migrating from V1 source: https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-pay/accept-payments/v1/index.md The second generation of Accept Payments simplifies our APIs and introduces significant improvements while keeping the same level of customization. The main improvements of v2 are the following: * **An improved authentication mechanism for creating payments** : Modelled upon feedback, creating new accept-payments no longer require an active login token. Your `clientid` and `secret` can be used instead. * **Simplified API and better payment Statuses**: The API has been simplified to be flatter and easier to interact with. Payment statuses have been expanded to more precisely represent the progress of the payment and to support future feature expansions. * **More controls to manage operating in different countries** : The previous version of the API was supporting only domestic payments to Aiia Pay Accounts. With v2 we have enabled an easy way to control *how* the payments are implemented. The local scheme facility of our v2 API enables you to accept payments and manage reconciliation data for instant payments, SEPA and other country-specific payment schemes. * **Destinations** : The new version of Accept Payments no longer accepts a Hub account id, but will require a destination id instead. This allows Aiia Pay to support not only traditional bank accounts but also *Aliases* for an account as payment destination such as Danish FI-koder. ### Improved Authentication {#improved-authentication} The previous version of Accept Payments would require an active user session during payment creation. The new version of API does not require anymore an active user session to create an Accept-Payments payment, but instead it will accept the `clientid/secret` of your application. This means that after migration you can stop requiring your customers to reauthenticate regularly and you can simplify your integration by removing the token refresh mechanism. To migrate, you will have to pass in the Authorization header your API `clientId` and `secret` instead of an user token. These values can be found in the Developer Portal. ### Local Schemes {#local-schemes} Schemes give you an easy way to specify the way the payment needs to be created and executed in the Payer's bank. A scheme defines how the payment is moved from the sending to the receiving account. It therefore defines which: * Currency payments can be accepted in * Destination accounts you should use to be able to accept payments * Banks are supported * Rules apply for the reference you are allowed to send along
Here we use the DanishDomesticCreditTransfer scheme as an example: ![](https://static.developer.mastercard.com/content/open-finance-europe/uploads/danish-domestic-scheme-example.png) It defines that: * Only Danish Kroners, DKK, can be received using this scheme. * Only accounts connected to the Danish clearing system can be used as destination accounts. * The reference is allowed to be 20 alpha numeric characters. Note: More schemes will be added regularly and those schemes will support new countries and features. You should check the [Scheme Documentation](https://api.aiia.eu/schemedocumentation) page for more information on each scheme. If migrating from Accept Payments v1, we recommend using `DanishDomesticCreditTransfer` to maintain the previous set of features. ### Destinations {#destinations} Instead of using onboarded Account IDs, the new version of Accept Payments accepts only destination IDs. These destination IDs have been added to the Get Accounts API so, before using the new version of the Accept Payments, you need to retrieve the corresponding `destinationIds` of your payment recipients instead/in addition to the `accountID`. `destinationIds` will not expire nor change, so you can avoid refreshing the accounts after the data migration and you can continue using them for an indefinite amount of time after fetching them. `destinationIds` will also allow Aiia Pay in the future to support other kinds of accounts that cannot be onboarded to Aiia Pay (Alias accounts). An example of this are the Danish FI-koder. Note: we currently do not have any automatic validation if the destination account is connected to the correct clearing scheme. ### Simplified API {#simplified-api} The structure of our objects changed to be simpler and flatter. The previous fields can still be found in the new API under a different name or location. These diagrams show how to map the data from/to the previous version of our API. | **v1 Field name** | **v2 Field name** | **Description** | |------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `.culture` | `.language` | (unchanged) - The language of the user interface | | `.payment.amount.amount` | `.amount` | (unchanged) - The amount of the payment | | `.payment.amount.currency` | `.currency` | (unchanged) - The currency in which the payment amount is expressed | | `.payment.orderid` | `.reference` | (changed) - A description/id that is used to identify the payment on the statement. In v2, the meaning of the field is defined by the `schemeId` field | | `.payment.date` | `.date` | (unchanged) - The date when the payment should be sent. | | `.redirectUrl` | `.redirectUrl` | (unchanged) - A page where the Payer should be sent to after the payment authorization flow is completed. | | `.providerId` | `.providerId` | (unchanged) - An id of the provider (from `/v1/providers`) that will be pre-selected | | (implicit from the authorization header) | `.destinationId` | (changed) - Defines where the beneficiary of the payment. Previously it was automatically inferred from the Authorization header. In v2 it is explicitly passed. | | | `.schemeId` | (new) - The id of a scheme. See the next section on schemes for more details | | | `.preselectedCountry` | (new) - Which countries should be preseselected in the payment flow. This affects the initial banks that are shown to the Payer | This table shows how to map the fields from the previous version of Accept Payments into the new request. The extra unmapped fields are described in their corresponding sections of this document: "Schemes" and "Destinations" #### Status codes {#status-codes} The new version of the API has a refined set of payment statuses: * Additional statuses that reflect special cases. * Improved naming of these statuses to better express the state of the payment * More detailed sub-codes and also a message that can be shown directly to the payer, to inform them of the payment state. The table below shows the difference between the V1 and V2: | **Status V1** | **Status V2** | **Description** | |---------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Created | Requested | The payment request was accepted by Aiia Pay and the payment is ready to be performed by the payer. | | InProgress | InProgress | The Payer is going through the payment journey and authorizing the payment. | | Pending | Authorized | The Payer completed the authorization and Aiia Pay is now waiting for the bank's confirmation of the payment initiation. | | Succeeded | Initiated | The payment has been initiated from the payer's bank and has been scheduled for the provided payment date, or as soon as possible. | | - | Executed | (not currently in use) -- The payer's bank confirmed that the payment has been executed and that it cannot be stopped by the Payer anymore. | | - | Received | (not currently in use) -- Aiia Pay confirmed that the payment has been received in the destination bank account. | | - | OnHold | The Payer's bank requires further interaction from the Payer after the authorization. This might happen if a second confirmation is needed or if the bank stops the payment even after the payment was authorized. | | | InitiationNotConfirmable | The payment has been authorized, but Aiia Pay's access to the Payer's bank expired before Aiia Pay could get a confirmation of the payment initiation. | | Failed | Failed | The payment failed. The specific failure reason is available in the details.reason field | | - | Expired | The payment expired, or the Payer left the payment authorization page. The payment authorization has not been completed. | | Cancelled | Cancelled | The Payer cancelled the payment authorization process or the bank danishacceptselection. | You can read the description of the new status codes in the [API reference documentation](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-pay/api-references/index.md).