# Payment Initiation source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/payment-initiation/index.md Our payment initiation service enables Third Party Providers (TPPs) to receive payments from Payment Service Users (PSUs) using an Account Servicing Payment Service Provider (ASPSP) of their choice. Guidance is given below on the following required steps: 1. How ASPSP selection works. 2. Request a payment. 3. Redirect the PSU to the authorisation flow. 4. Present the result to the PSU. If you have not set up an app yet, refer to our [Quick Start Guide](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/quickstart/index.md). The [Postman collection](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/testing/postman/index.md) is a useful tool when working through ths guide. ### How ASPSP selection works {#how-aspsp-selection-works} Our payment initiation product offers three ways the ASPSP can be chosen: 1. The ASPSP is pre-selected in the API request. The PSU will need to be guided to choose their ASPSP in your application. 2. The ASPSP is chosen by the PSU in our provider selection interface. 3. **Applicable only for Session Payments** The PSU will have already chosen their ASPSP as part of their previous AIS login flow. Therefore during the Session Payment flow, the solution pre-selects the PSU's provider and payer account, without the PSU needing to select it. Details for how to request payments using either approach are shown below. ##### TPP pre-selects ASPSP {#tpp-pre-selects-aspsp} The TPP pre-selects the ASPSP by populating the field `providerId`, as shown below API Reference: `POST /v1/payments/create` ```shell curl -X POST \ https://api.nordicapigateway.com/v1/payments/create \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -d '{ "providerId": "FI_TestBank", ... "request": { ... } }' ``` Note: On a regular basis, we may remove certain `providerId` values, and introduce new ones. This can happen for example when banks merge or close. We therefore recommend that your solution retrieves and validates these values from the `/v1/providers` endpoint. These values should not be hard-coded in your solution. The TPP needs to ensure that the ASPSP chosen can reach the recipient's account. The chosen ASPSP needs to support the recipient account's currency. To see how you can determine which currencies are supported by the ASPSP and which ASPSPs are available, refer to [provider functionality](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md). ##### ASPSP selection {#aspsp-selection} If the `providerId` field is not populated by the TPP, then our flow will guide the PSU to choose their ASPSP in our "bank selector" interface. The TPP can filter the list of ASPSPs that should be shown to the PSU based on country, by populating the providers attribute as shown below API Reference: `POST /v1/payments/create` ```shell curl -X POST \ https://api.nordicapigateway.com/v1/payments/create \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -d '{ "providers": ["FI"], ... "request": { ... } }' ``` ##### ASPSP selected at session creation {#aspsp-selected-at-session-creation} In a Session Payment, the PSU will have already chosen their ASPSP as part of their previous AIS login flow. Therefore during the Session Payment flow, the solution pre-selects the PSU's provider and payer account, without the PSU needing to select it. API Reference: `POST /v1/payments/create/session` ```shell curl -X POST \ https://api.nordicapigateway.com/v1/payments/create \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -H 'Authorization: ' \ -d '{ ... "request": {\ "sourceAccountId": "", ... } }' ``` ### Request a payment {#request-a-payment} To receive a payment to a specific destination account when no AIS session is in place with the user, call the create payment endpoint, as shown below. API Reference: `POST /v1/payments/create` ```shell curl -X POST \ https://api.nordicapigateway.com/v1/payments/create \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -d '{ "redirectUrl": "https://httpbin.org/anything", "language": "en", "userHash": "test-user-hash", "request": { "paymentMethod": "Domestic", "message": "This is the text that appears to the receiver", "transactionText": "This is the text that will appear in the payers own bank", "destination": { "name": "Payment Receiverson", "iban": { "ibanNumber": "DK9520000123456789" } }, "amount": { "value": 20.00, "currency": "EUR" }, "execution": { "type": "Instant" } } }' ``` The response returns `paymentId`, `redirectUrl` and `sessionId`. It is important that the TPP stores the `paymentId` and `sessionId`. The `paymentId` it will be needed later to look up the payment and `sessionId` can be used to look up the authentication status and obtain tokens. To receive a payment to a destination account when there is an AIS session is in place with the user, call the create session payment endpoint, as shown below. API Reference: `POST /v1/payments/create/session` ```shell curl -X POST \ https://api.nordicapigateway.com/v1/payments/create/session \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -H 'Authorization: ' \ -d '{ "redirectUrl": "https://httpbin.org/anything", "language": "en", "userHash": "test-user-hash", "request": { "sourceAccountId": "5d5bcLTPv-HH-pV26cT67lrIY8kwz59whYjEJasHyUc.5ef85601bc3b", "paymentMethod": "Domestic", "message": "This is the text that appears to the receiver", "transactionText": "This is the text that will appear in the payers own bank", "destination": { "name": "Payment Receiverson", "iban": { "ibanNumber": "DK9520000123456789" } }, "amount": { "value": 20.00, "currency": "EUR" }, "execution": { "type": "Instant" } } }' ``` The response returns `paymentId`, `redirectUrl`. It is important that the TPP stores the `paymentId`. The `paymentId` it will be needed later to look up the payment. The redirect URL is also needed in the next step. #### Authorising the payment {#authorising-the-payment} The next step is for the PSU to authorize the payment. 1. The TPP must redirect the PSU to the `redirectUrl` (received in the previous step). 2. The PSU must perform a [Supervised Login](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/connect/supervised/index.md). Note: The redirect URL must not be presented in an iframe and the redirect URL cannot be reused. Once it is been triggered, the redirect URL is no longer useable. ###### Example - Paying in a webshop {#example---paying-in-a-webshop} ![Step 1](https://static.developer.mastercard.com/content/open-finance-europe/uploads/Standalone_illustration_v3.png) #### Present the payment result {#present-the-payment-result} When the flow is completed, the PSU is redirected back to the application using the `redirectUrl`. The payment can have different outcomes. Each individual outcome must be handled separately. The payment state must be retrieved before displaying the outcome to the PSU. This is done by requesting an updated status of the payment: API Reference: `POST /v1/payments/{paymentId}/refresh-status` ```shell curl -X POST https://api.nordicapigateway.com/v1/payments/{paymentId}/refresh-status \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -H 'Authorization: ' \ -d '' ``` This returns the latest state on the payment. Different states that can be encountered are shown below. #### Payment state {#payment-state} Note: We have recently transitioned to a new set of payment statuses, designed to provide additional details about the payment status. For backwards compatibility, we have also still retained the original statuses in a separate field. ##### Payment state (original status codes) {#payment-state-original-status-codes} | **State** | **Description** | |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Succeeded` | The payment initiation was successfully accepted by the ASPSP. | | `Pending` | The payment initiation was successfully authorized by the PSU, but the ASPSP did not accept the payment order yet. Refresh payment until you receive a terminal state. | | `Cancelled` | The payment initiation was cancelled by the PSU. | | `Failed` | The authorisation of the payment initiation was not successful. For details, refer to the `status` object. | ##### Payment state (new status codes) {#payment-state-new-status-codes} | **State** | **Description** | |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `ProviderProcessing` | The ASPSP received the payment request. Our service is awaiting confirmation that the payment has been initiated. | | `Pending` | The ASPSP placed the payment in a pending state. Further action from the Payer may be required. | | `Initiated` | The ASPSP validated and accepted the payment request. The payment has been scheduled for the provided payment date, or as soon as possible. | | `PaymentExecutedDebited` | The payment has been settled on the Payer's account. | | `PaymentExecutedCredited` | The payment has been settled on the Payee's account. | | `Failed` | The authorisation of the payment initiation was not successful. More information about the cause of the failure may be available in the `reason` field of the status object. | | `Cancelled` | The Payer either cancelled the payment at the authorization stage, did not proceed before the payment expired, or cancelled a scheduled future payment before it reached its execution date. The payment has not been executed. | Note: The recipient can only be guaranteed the payment when it is been received on their account. Payment initiation status only reflects if the payment order was accepted for execution at the ASPSP. It does not reflect the actual settlement of the payment. #### Further information {#further-information} * Refer to [Payment Request Definition and Validation](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md) for information on how to define a payment, and how the validation of the request works. * Refer to the [Testing](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/testing/testing-payments/index.md) section for information on supported scenarios and how to test these scenarios. * Refer to [payerToken](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/payer-token/index.md) for information on how to optimise the second time payment for the PSU. * Refer to [Cross Border Payments](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/cross-border-payments/index.md) for information and guidance on requesting payments between source and destination IBANs in different countries.