# Get Domestic Payment Status source: https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/get-payment-status-request/index.md ## Request overview {#request-overview} The goal of this request is to retrieve from the Account Servicing Payment Service Provider (ASPSP), using the `consentId` which is part of previously obtained consent object, the settlement status of the previously initiated payment by `paymentId`. This flow assumes the PSU has already consented to this access and the ASPSP system stores this record of consent or `consentId`. For more information, see [Payment Initiation Consent Request](https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/payment-initiation-consent-request/index.md). ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |----------------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------|------------------------| | /payments/domestic-credit-transfers/payment-status | `POST` | CMA9, Polish API, NextGenPSD2, Budapest Bank, Czech Open Banking Standard API Profile, Slovak Banking API Standard API Profile | Returns payment status | The following sequence diagram shows the flow for getting a payment status. Diagram get_domestic_payment_status ## Request scenario {#request-scenario} API Reference: `POST /payments/domestic-credit-transfers/payment-status` #### Request header {#request-header} N/A #### Request body {#request-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| | `requestInfo` | Includes information about request being processed | MC | This element encapsulates all request information sent to the API Service | M | 1..1 | Object | Set of elements used to define the request details | N/A | | `xRequestId` | ID of the request, unique to the call, as determined by the TPP | TPP | A memorable ID could be used to support in a dispute | M | 1..1 | String UUID | Free field that allows for the addition of information that can be referenced for future use | 36 | | `consentId` | A unique reference to the payment initiation consent stored by the ASPSP. This is required to enable subsequent calls related to the payment (for example, to request payment status details) | ASPSP | Pass this value as part of the payment status requests related to the consent. | M | 1..1 | String | A unique reference to the payment initiation consent stored by the ASPSP. Please note that this is not the original value generated by the ASPSP but a generated 'proxy' value related to that. | 1-256 | | `aspspId` | ID of a financial institution servicing the Accounts of the PSU | ASPSP | Identification of ASPSP | M | 1..1 | String UUID | Specifies the identification code of a financial institution which holds PSU accounts | 36 | | `isLivePsuRequest` | Indicates if PSU actively initiated request. | ASPSP | Type of PSU request | O | 0..1 | Boolean | PSU request type | Boolean: true or false | | `psuIPAddress` | PSU's IP address if the PSU is currently logged in with the TPP. | ASPSP | If the customer IP address is supplied (recommended), it is inferred that the PSU is present during the session (that is, the request is PSU-initiated). | C | 0..1 | String | IP address of PSU's terminal device | 1-256 Required when isLivePsuRequest=true | | `psuAgent` | Indicates the user-agent for the PSU. If the PSU is using the TPP's mobile app, make sure the mobile app user-agent string is different than browser-based user-agent strings. | ASPSP | If user-agent is supplied to ASPSP, then this information can be used by ASPSP's security mechanisms. To avoid rejections, it is recommended to include this field when providing `isLivePsuRequest` and `psuIPAddress`. | O | 0..1 | String | PSU's browser agent details | 1-256 | | `merchant` | Collect merchant data for reporting purposes | MC | Merchant data used for reporting or reconciliation purposes | O | 0..1 | Object | Set of elements used to define the merchant details | N/A | | `id` | Merchant identification code to identify the merchant | MC | Unique Merchant identifier per TPP, which could be used for reporting/reconciliation purposes | M | 1..1 | String | Field is available for TPPs to enable capturing of a merchant ID | 1-256 | | `name` | Merchant name to identify the merchant | MC | Name of merchant | M | 1..1 | String | Field is available for TPPs to enable capturing of a merchant name | 1-256 | | `paymentId` | Unique identification to uniquely identify the payment resource. | TPP | This value is used to make subsequent payment specific requests | M | 1..1 | String | Payment identification. Please note that this is not the original value generated by the ASPSP but a generated 'proxy' value related to that. | 1-256 | Tip: For an explanation of notations used, refer to **Open Banking General FAQ** in our [Frequently Asked Questions](https://developer.mastercard.com/open-banking-connect/documentation/frequently-asked-questions/index.md) section. Tip: 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, contact the Open Banking Support team to reconcile the transaction and identify any issues which may be preventing payment. ### Response -- Success {#response--success} HTTP Response Code = 200, OK Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). For specific error codes for this feature see **Feature specific error codes** below. #### Response header {#response-header} N/A #### Response body {#response-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------|---------------|------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `originalRequestInfo` | Returns original request information to the TPP | MC | This object contains original request information | M | 1..1 | Object | Original request information received from the TPP | N/A | | `xRequestId` | A memorable ID which could be used to support in a dispute | TPP | This element could be used for request-response tracking | M | 1..1 | String UUID | Original `xRequestId` given by the client on request | 36 | | `payments` | Specifies payments information in returned data | TPP | This element encapsulates all payments information | M | 1..1 | Object | Set of elements used to reference a payment instruction | N/A | | `paymentId` | Unique identification as assigned by the Connectivity Partner to uniquely identify the payment resource. | TPP | This value should be used to make subsequent payment specific requests | M | 1..1 | String | Payment identification returned by Connectivity Partner | 1-256 | | `transactionStatus` | Specifies the status of the payment information group | TPP | Transaction Status of the payment resource | M | 1.1 | String | Transaction status. Please note that this is not the original value generated by the ASPSP but a generated 'proxy' value related to that | One of the following ISO 20022 statuses: · `ACCP` · `ACSC` · `ACSP` · `ACTC` · `ACWC` · `ACWP` · `PDNG` · `RCVD` · `RJCT` · `CANC` | | `statusReasonCode` | Provides detailed information on the status reason. | TPP | Can only be used in case the status is equal to "RJCT" | O | 0..1 | String | Status Reason Code is used to add more information when a generic status code is returned by transaction Status field. | The codes for `statusReasonCode` are defined in ISO20022 - "ExternalStatusReason1Code". The following codes could be returned when `RJCT` status is raised: · `AM04` · `CURR` · `AM12` · `DS24` · `DS02` · `AG08` | | `originalPaymentId` | Unique identification as assigned by the ASPSP to uniquely identify the payment resource. | TPP | Could be used to support in a dispute | O | 0..1 | String | Payment identification returned by ASPSP | 1-256 | | `originalPaymentStatus` | Specifies the status of the payment information group. Value returned by ASPSP. | TPP | Could be used to support in a dispute | O | 0..1 | String | Status of the payment returned by ASPSP | 1-256 | | `refundAccount` | refundAccount object is available in the response only when PSU has provided consent to share account details with the TPP. It includes PSU's account details. | TPP | This element encapsulates refund account details | O | 0..1 | Object | Object encapsulating refund account details | | | `schemeName` | Name of the scheme, used to specify the account identification type. | TPP | This field is used to specify the account identification type | O | 0..1 | String | Account scheme name | Example values: `UK.AccountNumber`, `IBAN` | | `identification` | Account identification number. It can be used on payload-level to mention specific account. | TPP | Details received in this field can be used for creditor account details in the reversed payment | O | 0..1 | String | Account identification which can be used on payload-level to address specific accounts | | | `name` | This field is used to send the name of debtor account owner. | TPP | The data from this field should be used in the `creditorName` field for refund payments. | O | 0..1 | String | The account name is the name or names of the account owner(s) represented at an account level as it was assigned by the ASPSP. | | | `refundAgent` | refundAgent object is available in the response only when PSU has provided consent to share account details with the TPP. It includes details of the financial institution servicing the refund account. | TPP | This element encapsulates refund agent details | O | 0..1 | String | Object encapsulating refund agent details | Example: `UK.SortCode` | | `clearingSystemIdentification` | Denomination of the system, used to specify agent identification type. | TPP | Used to specify agent identification type. | O | 0..1 | String | Clearing system identification | Example: `UK.SortCode` | | `memberIdentification` | Identification code of the financial institution as assigned by the ISO 9362 Registration Authority. | TPP | This element is used to specify the financial institution identification code | O | 0..1 | String | Identification code to identify the financial institution. | | ## Feature specific error codes {#feature-specific-error-codes} Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------------|-----------------|------------------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------|-------------------------------------| | "Access Token associated with the Request has expired" | `INVALID_TOKEN` | Access Token associated with the Request has expired | n/a | Typically occurs when the consent that the TPP has previously obtained from a PSU has expired. | PSU needs to provide a new consent. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " INVALID_TOKEN ", "Description": "Access Token associated with the Request has expired" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------------------|-----------------|----------------------------------------------------------|-----------------------|-------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Access Token associated with the Request is invalid or has been revoked" | `INVALID_TOKEN` | The consent id used in the request is invalid or revoked | n/a | Typically occurs when the consent id is invalid or revoked. | Ensure a valid consent id is used in the request. If you think the specified consent id is valid please contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_TOKEN", "Description": "Access Token associated with the Request is invalid or has been revoked" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------------------------------------------|-----------------|-----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | Conditional field `psuIPAddress` is expected when `isLivePsuRequest`='true' | `FORMAT_ERROR` | `IP address` field is mandatory if parameter `isLivePsuRequest`=true. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, etc. for each element that failed the validation | Typically occurs because the TPP has provided in request `isLivePsuRequest`=true and didn't provide the IP address value. | Provide IP address of PSU in the request when providing `isLivePsuRequest`=true. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Conditional field psuIPAddress is expected when isLivePsuRequest='true'", "Details": "path[0]=/requestInfo/psuIPAddress" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------|-----------------|-----------------------|-----------------------|--------------------------------------------------------|-------------------------------------| | "Invalid Input" | `FORMAT_ERROR` | The input is invalid. | N/A | Occurs when invalid input was included in the request. | Adjust the request and resubmit it. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": "Invalid Input" } ] } } ```