# Monitoring payments source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/monitoring-payments/index.md The service offers methods to retrieve the status of an initiated payment, allowing you to monitor its progress. When a payment has been initiated, it is not always guaranteed that the money has been transferred from the account - it depends on the requested payment type, the bank, etc. The monitoring endpoints can be used to fetch the latest status of an initiated payment from the provider, as well as fetching ongoing and historical payment initiations. ## Checking the status of an initiated payment {#checking-the-status-of-an-initiated-payment} Refreshing the status of an initiated payment is possible using the Refresh payment status endpoint. API Reference: `POST /v1/payments/{paymentId}/refresh-status` This endpoint retrieves the latest status from the bank. After the API has updated the payment with the newest status from the bank, the full payment object - containing the updated status - is returned. Below is a sample cURL request for refreshing the latest status of a payment initiation with the ID `1234567890abcedfg`: ```shell curl -X POST \ https://api.nordicapigateway.com/v1/payments/1234567890abcedfg/refresh-status \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -H 'Authorization: ' \ -d '' ``` The `accessToken` and a `loginToken` to maintain connectivity to that user session need to be obtained by following the steps detailed in [Codes and Tokens](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/api-basics/code-and-tokens/index.md) after a user session is created for AIS consent or after a payment has been authorised. The API response to this request will contain the following fields inside the `status` object: | **Name** | **Type** | **Description** | |---------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `terminal` | `bool` | True, if further changes in status code are not expected. This may be because the payment reached a terminal state, or because access to the provider has expired and the payment status can no longer be refreshed. | | `code` | `string` | The current status code. | | `lastUpdated` | `datetime` | When the status code was last fetched from the provider. | | `details` | `object` | Contains further details about the payment, if available. | ## Payment state {#payment-state} When a non-terminal state is returned in the API response, we recommend polling to refresh payment status as follows: Note: We are currently in the process of rolling out a new set of payment statuses, designed to provide additional details about the payment status - for example: * a new status of `Initiated` for payments which have been accepted by the sending bank, but not yet executed; * a new status of `Unknown` to make clear when access to refresh a payment has expired; * a new field of `lastKnownStatus` to retrieve the last known status a payment reached, before access expired Preview Release available for use in select markets only - please consult your Mastercard support representative for further details To start using the new payment statuses, if they are available in your market, your application should consume the new status value from the field `Payment.Status.CodeV2`, and (where applicable) the value from the field `Payment.Status.Details.LastKnownStatus`. For backwards compatibility, we have also still retained the original statuses in the field `Payment.Status.Code`. If you do not wish to transition to the new statuses, you do not need to take any action. #### Payment state (original status codes) {#payment-state-original-status-codes} | **State** | **Action** | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Preparing` | Refresh at a frequency of every two minutes, up to a maximum of 90 minutes. | | `ReadyForAuthorize` | Refresh at a frequency of every ten seconds, up to a maximum of 90 minutes. | | `Authorizing` | Refresh at a frequency of every ten seconds, up to a maximum of 90 minutes. | | `Pending` | Refresh at a frequency of every two minutes, until 90 minutes have passed. After 90 minutes, refresh with an exponential backoff delay. If there has been no further status change after seven days, we advise contacting the provider to reconcile the transaction and identify any issues which may be preventing payment execution. | #### Payment state (new status codes) {#payment-state-new-status-codes} | **State** | **Action** | |----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Preparing` | Refresh at a frequency of every two minutes, up to a maximum of 90 minutes. | | `Authorizing` | Refresh at a frequency of every ten seconds, up to a maximum of 90 minutes. | | `ProviderProcessing` | Refresh at a frequency of every two minutes, until 90 minutes have passed. After 90 minutes, refresh with an exponential backoff delay. If there has been no further status change after seven days, we advise contacting the provider to reconcile the transaction and identify any issues which may be preventing payment execution. | | `Pending` | Refresh at a frequency of every two minutes, until 90 minutes have passed. After 90 minutes, refresh with an exponential backoff delay. If there has been no further status change after seven days, we advise contacting the provider to reconcile the transaction and identify any issues which may be preventing payment execution. | A full overview of potential status codes, and how a payment initiation can transition between them, can be found [below](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/monitoring-payments/index.md#payment-status-flowchart). An example of the full payment initiation model can be found [below](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/monitoring-payments/index.md#the-payment-initiation-model). ##### Status object example (Authorizing) {#status-object-example-authorizing} For a payment initiation that awaits the user's final authorisation, the `status` object of the returned payment initiation might look like this: ```json "status": { "terminal": false, "code": "Authorizing", "lastUpdated": "2019-09-10T08:13:23.8293259+00:00", "details": null } ``` ##### Status object example (Failed) {#status-object-example-failed} In case of a failed payment initiation, the `details` object might contain additional information detailing *why* the initiation failed. The payment initiation shown in the example below failed due to insufficient funds: ```json "status": { "terminal": true, "code": "Failed", "lastUpdated": "2019-09-10T08:13:23.8293259+00:00", "details": { "providerStatusCode": null, "reason": "PaymentFailed_InsufficientFunds", "providerMessage": null } } ``` ##### Error code examples {#error-code-examples} Error codes can also occur during the authentication flow, such as: * `AuthenticationFailed_CredentialsBlocked` - The login has been blocked by the bank. * `AuthenticationFailed_CredentialRenewalNeeded` - The user needs to change login information, such as passwords. Authorization tokens to refresh the status of a payment expire after a period of time (which varies by provider). Once the token expires, it will not be possible to retrieve further updates on payment status, and the `terminal` field will read `true`. When this happens, if Third Party Providers (TPPs) want to confirm payment execution, they should perform reconciliation of payments with transactions on the destination account. ## Fetching payment initiations {#fetching-payment-initiations} Ongoing and historical payment initiations can be fetched from the Get Payments endpoints. API Reference: `GET /v1/payments` In contrast to the refresh-status endpoint, this endpoint will not fetch the latest status from the banks. Below is a sample cURL request for fetching the payment initiation with the ID `1234567890abcedfg`: ```shell curl -X GET \ https://api.nordicapigateway.com/v1/payments/1234567890abcedfg \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -d '' ``` Multiple payment initiations can be fetched for a period of time specified by the `from` and `to` parameters in a query, as seen in the sample cURL command below. ```shell curl -X GET \ 'https://api.nordicapigateway.com/v1/payments?from=2019-01-01&to=2020-01-01' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -d '' ``` Example response: ```json { "payments": [ // Payment initiations ], "pagingToken": "8yab3vy4uwb4ryhj4w98e5urbjven9wphsvaufisn" } ``` | **Name** | **Type** | **Description** | |---------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `payments` | `object` | Payment initiations corresponding to the query. | | `pagingToken` | `string` | If there are more payment initiations than possible to fetch with a single request, you can fetch more by providing this token in a new request. | ## The payment initiation model {#the-payment-initiation-model} The payment initiation model returned by any of the payments endpoints looks like this: ```json { "paymentId": "8fb9acf2-4159-443b-849a-350a2894251b", "userHash": "test-user-hash", "providerId": "DemoBank", "request": { "sourceAccountId": "V4MAy4rsrtKwNMFePVobSnfr3UAwOdylo6g92sep35E.0", "destination": { "bban": null, "iban": { "ibanNumber": "DK9520000123456789" }, "ownAccount": null, "name": "Payment Receiverson" }, "amount": { "value": 20.0, "currency": "EUR" }, "execution": { "type": "Instant" }, "message": "This is a test payment!", "transactionText": "This is a test payment!", "endToEndId": null }, "status": { "terminal": true, "code": "Succeeded", "lastUpdated": "2019-09-10T08:13:23.8293259+00:00", "details": null }, "created": "2019-09-10T08:13:20.2208449+00:00", "source": { "bban": { "bankCode": "204386946", "accountNumber": "204386946" }, "iban": null, "ownAccount": null, "name": null }, "execution": { "type": "Instant", "date": null, "fee": "Unknown", "feeAmount": null }, "message": "This is a test payment!", "transactionText": "This is a test payment!" } ``` | **Name** | **Type** | **Description** | |-------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `paymentId` | `string` | The ID of the payment initiation. | | `userHash` | `string` | The user hash supplied when the payment initiation flow was initialised. | | `providerId` | `string` | The ID of the provider (e.g. a bank) that will execute the payment. | | `request` | `object` | The payment request itself, including the amount, destination account, etc. | | `status` | `object` | The latest status of the payment initiation, including when it was last updated. | | `created` | `string` | When the payment initiation was created. | | `source` | `object` | Information about the used payment account. | | `message` | `string` | Remittance text, shown on the transaction on the destination account. | | `transactionText` | `string` | Transaction text, shown on the transaction on the source account. For OP Financial Group only: This field should contain the name of the final beneficiary, aka the ultimate creditor. The final beneficiary information is required for OP payment providers if funds are not directly transferred to the final beneficiary account, but rather processed through an intermediate account. | \*(Other properties might be present in real-life responses to preserve backwards compatibility) ## Payment Status Codes {#payment-status-codes} Below you can see our payment status codes. For reference we also show how ISO20022 status codes, which are used by many providers, map to our status codes. Note: We are currently in the process of rolling out a new set of payment statuses, designed to provide additional details about the payment status - for example: * a new status of `Initiated` for payments which have been accepted by the sending bank, but not yet executed; * a new status of `Unknown` to make clear when access to refresh a payment has expired; * a new field of `lastKnownStatus` to retrieve the last known status a payment reached, before access expired Preview Release available for use in select markets only - please consult your Mastercard support representative for further details. To start using the new payment statuses, if they are available in your market, your application should consume the new status value from the field `Payment.Status.CodeV2`, and (where applicable) the value from the field `Payment.Status.Details.LastKnownStatus`. For backwards compatibility, we have also still retained the original statuses in the field `Payment.Status.Code`. If you do not wish to transition to the new statuses, you do not need to take any action. #### Payment state (original status codes) {#payment-state-original-status-codes-1} | **Name** | **Description** | **ISO 20022 status codes** | |---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Preparing` | Authorization flow in progress. | - | | `ReadyForAuthorize` | Authorization flow in progress. | - | | `Authorizing` | Authorization flow in progress. | - | | `Pending` | Payment initiation was successfully authorized by the user, but it has not been settled yet by the provider. In this state, we are waiting for final status from the provider, and the payment initiation can either succeed or fail. | `PDNG` -- Pending `ACTC` -- AcceptedTechnicalValidation `ACCP` -- AcceptedCustomerProfile `ACFC` -- AcceptedFundsChecked `ACWC` -- AcceptedWithChange `ACSP` -- AcceptedSettlementInProcess `PATC` -- PartiallyAcceptedTechnicalCorrect | | `Succeeded` | The payment has been debited from the Payer account.. | `ACSC` -- AcceptedSettlementCompleted `ACCC` -- AcceptedCreditSettlementCompleted | | `Failed` | The payment initiation failed. Failures can happen for a number of reasons, see above. | `RJCT` -- Rejected | | `Cancelled` | Payment initiation was cancelled by the user. | `CANC` -- Cancelled | #### Payment state (new status codes) {#payment-state-new-status-codes-1} | **Name** | **Description** | **ISO 20022 status codes** | |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------| | `Preparing` | The payment request details have been captured and the payment is ready to be authorized by the Payer. | - | | `Authorizing` | The Payer is going through the payment authorization journey. | - | | `ProviderProcessing` | The Account Servicing Payment Service Provider (ASPSP) received the payment request. The service is awaiting confirmation that the payment has been initiated. | RCVD, PATC, ACTC, ACCP, ACFC | | `Pending` | The ASPSP placed the payment in a pending state. Further action from the Payer may be required. | PDNG | | `Initiated` | The ASPSP validated and accepted the payment request. The payment has been scheduled for the provided payment date, or as soon as possible. | ACWC, ACSP, ACWP | | `PaymentExecutedDebited` | The payment has been settled on the Payer's account. | ACSC | | `PaymentExecutedCredited` | The payment has been settled on the Payee's account. | ACCC | | `Failed` | The payment failed. More information about the cause of the failure may be available in the `errorCode` and `errorType` fields of the status object. | RJCT, BLCK | | `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. | CANC | | `AuthorizationFlowIncomplete` | The payment authorization URL expired, or the Payer left the payment authorization page. ​The payment authorization has not been completed. | - | | `Unknown` | Our access to refresh the payment status at the ASPSP has expired. Refer to the "lastKnownStatus" field to find the last known status of the payment, before access was lost. For confirmation of payment execution, perform reconciliation against transactions in the destination account. | | Note: Our status codes correspond to the payment status reported by the initiating provider (i.e. the Payer account), and do not provide full guarantees for the receipt of the payment in the destination account. It is important to note that due to other factors, such as fraud and regulatory screening at the receiving bank, or intervention by the Payer to cancel the payment, some payments may still fail after reaching the ACSC(Succeeded) status. For absolute guarantees of receipt, perform reconciliation of payments with transactions on the destination account. In cases where an expected payment has not been received, the following steps may help: * Refresh the status of the payment using the Refresh payment status endpoint, as [described above](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/monitoring-payments/index.md#checking-the-status-of-an-initiated-payment) * Check the details field of the status object in the response: if further information has been sent by the provider, this field will be populated with details such as the ISO status code and message, which may provide clarity on whether and why a payment may have been delayed or rejected. * If you still cannot reconcile the payment at this point, complete the [Contact Us](https://openbankingeu.mastercard.com/contact-us) form for assistance. ### Payment status flowchart {#payment-status-flowchart} The flowcharts below are a conceptual depiction of how the payment transitions between statuses. Note: We are currently in the process of rolling out a new set of payment statuses, designed to provide additional details about the payment status - for example: * a new status of `Initiated` for payments which have been accepted by the sending bank, but not yet executed; * a new status of `Unknown` to make clear when access to refresh a payment has expired; * a new field of `lastKnownStatus` to retrieve the last known status a payment reached, before access expired Preview Release available for use in select markets only - please consult your Mastercard support representative for further details To start using the new payment statuses, if they are available in your market, your application should consume the new status value from the field `Payment.Status.CodeV2`, and (where applicable) the value from the field `Payment.Status.Details.LastKnownStatus`. For backwards compatibility, we have also still retained the original statuses in the field `Payment.Status.Code`. If you do not wish to transition to the new statuses, you do not need to take any action. #### Payment state (original status codes) {#payment-state-original-status-codes-2} ![](https://static.developer.mastercard.com/content/open-finance-europe/uploads/payment-states.svg) #### Payment state (new status codes) {#payment-state-new-status-codes-2} ![](https://static.developer.mastercard.com/content/open-finance-europe/uploads/payment-states-new_2.png) Note: Depending on the payment type and provider, it is possible for payments which have reached a successful `terminal` state to undergo further status changes (this is indicated by a dashed line on the diagram). For example, most single immediate payments will reach a final state of `PaymentExecutedDebited`. However there are a small number of providers which may subsequently report a state of `PaymentExecutedCredited` (ACCC), confirming that funds have been received in the payee account. We recommend that customers cease polling to refresh payment status once a terminal and/or successful state is reached, but customers should also consider what level of payment outcome certainty is required for their use case, when determining their polling logic.