# Business Rule Errors source: https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/code-and-formats/business-rule-errors/index.md Business rule errors are listed per API. Note: If Mastercard fails to validate the content of an incoming message, it will send a JSON response with an error body that contains an error code and an error description to indicate the reason for the message failure. The participant is then expected to fix the issue and send a new message. ### Update Agreement {#update-agreement} | Error Code | Error Description | Resolution Tips | |------------|-------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | AGRM-0001 | X-Participant-ID must be a valid and active participant | Verify that the X-Participant-ID header contains a valid and active participant identifier. Ensure the participant is enabled and authorized before resubmitting the request. | | AGRM-0003 | initiatingPartyId must be the same as X-Participant-ID | Ensure the initiatingPartyId value exactly matches the X-Participant-ID provided in the request header. Check for any mismatched, missing, or incorrectly formatted values. | | AGRM-0004 | businessType must be valid | Validate that the businessType field contains a supported value. Review the request payload and replace any invalid or unsupported business type entries. | | AGRM-0030 | debtorId or debtorServiceProviderId is invalid | Verify that the provided debtorId or debtorServiceProviderId is valid and exists in the system. Ensure the identifiers are correctly formatted and associated with the intended participant. | | AGRM-0033 | Agreement Id in path param should match with the agreement Id in request | Confirm that the Agreement ID specified in the URL path matches the agreementId included in the request body. Use the same agreement reference throughout the request. | | AGRM-0034 | agreementId must be valid | Check that the agreementId is valid, correctly formatted, and associated with an existing agreement record. Avoid using invalid, expired, or incorrect agreement identifiers. | | AGRM-0038 | Agreements in progress can only be approved or rejected | Ensure only agreements that are currently in progress are updated with an approval or rejection status. Review the agreement's current status before submitting the update request. | | AGRM-0037 | Only approved or rejected agreements can be deleted | Verify that the agreement has already been approved or rejected before attempting to delete it. Requests to delete agreements in other states will be rejected. | | AGRM-0039 | accountNickname must be sent for agreements being approved otherwise not | Include the accountNickname field only when approving an agreement. Remove this field for requests involving any other agreement status. | | AGRM-0040 | agreementStatusReason must be sent for agreements being rejected, otherwise not, and reason should be valid | Provide a valid agreementStatusReason when rejecting an agreement and ensure the reason code is supported. Do not send this field when the agreement is being approved or updated to other statuses. | | AGRM-0041 | accountNickname can only be updated for approved agreements | Ensure that updates to accountNickname are performed only for agreements that are already approved. Verify the agreement status before submitting the update request. | | AGRM-0043 | Agreement confirmation timed out | The agreement confirmation was not completed within the allowed timeframe. Initiate a new agreement request and ensure all required actions are completed before the timeout period expires. | ### Agreement Retrievals {#agreement-retrievals} | Error Code | Error Description | Resolution Tips | |------------|---------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | AGRM-0001 | X-Participant-ID must be a valid and active participant | Verify that the X-Participant-ID header contains a valid and active participant identifier. Ensure the participant is authorized and active before resubmitting the request. | | AGRM-0003 | initiatingPartyId must be the same as X-Participant-ID | Ensure the initiatingPartyId value exactly matches the X-Participant-ID provided in the request header. Review the request for any mismatched or incorrectly formatted identifiers. | | AGRM-0004 | businessType must be valid | Validate that the businessType field contains a supported and correctly formatted value. Replace any invalid business type entries before retrying the request. | | AGRM-0026 | Please present either agreementReferenceNumber or agreementId to retrieve agreement details | Provide either a valid agreementReferenceNumber or agreementId when requesting agreement details. Ensure at least one of these identifiers is included in the retrieval request. | | AGRM-0027 | Invalid agreementId or agreementReferenceNumber or agreement is in an invalid state | Verify that the supplied agreementId or agreementReferenceNumber exists and is associated with a valid agreement. Also confirm that the agreement is in a state that supports retrieval requests. | | AGRM-0029 | Agreement retrieval timed out | The agreement retrieval request was not completed within the allowed processing window. Retry the request using a valid agreement reference and confirm that the agreement remains available for retrieval. | ### Agreement Searches {#agreement-searches} | Error Code | Error Description | Resolution Tips | |------------|---------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | AGRM-0001 | X-Participant-ID must be a valid and active participant | Verify that the X-Participant-ID provided in the request header is correct and belongs to an active participant. Update the request with a valid participant identifier before retrying. | | AGRM-0003 | initiatingPartyId must be the same as X-Participant-ID | Ensure that the initiatingPartyId in the request payload exactly matches the value of the X-Participant-ID header. Review the request for any mismatched or incorrectly formatted identifiers. | | AGRM-0004 | businessType must be valid | Validate that the businessType field contains a supported value. Replace any invalid or unsupported business type with a valid value and resubmit the request. | ### Step Up Advices {#step-up-advices} | Error Code | Error Description | Resolution Tips | |------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | RFPX-0001 | X-Participant-ID must be a valid and active participant | Verify that the X-Participant-ID provided in the request header is correct and belongs to an active participant. Update the request with a valid participant identifier before retrying. | | RFPX-0004 | ServiceProviderId must match with X-Participant-ID and initiatingPartyId | Ensure that the ServiceProviderId, X-Participant-ID, and initiatingPartyId contain the same value. Review the request payload and headers for any mismatched identifiers. | | RFPX-0005 | businessType must be valid | Validate that the businessType field contains a supported value. Replace any invalid or unsupported business type with a valid value and resubmit the request. | | RFPX-0025 | paymentRequestLifecycleId or payment_request_lifecycle_id is invalid | Verify that the payment request lifecycle identifier is correct, properly formatted, and associated with an existing payment request. Use a valid lifecycle ID before retrying the request. | | RFPX-0061 | Step up notification is only allowed for agreement type AOF | Ensure that step-up notifications are submitted only for agreements with type AOF. Review the agreement type and remove the step-up notification or use a valid AOF agreement as applicable. | ### Payment Confirmation {#payment-confirmation} | Error Code | Error Description | Resolution Tips | |------------|---------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | RFPX-0001 | X-Participant-ID must be a valid and active participant | Verify that the X-Participant-ID provided in the request header is correct and belongs to an active participant. Update the request with a valid participant identifier before retrying. | | RFPX-0004 | ServiceProviderId must match with X-Participant-ID and initiatingPartyId | Ensure that the ServiceProviderId, X-Participant-ID, and initiatingPartyId contain the same value. Review the request payload and headers for any mismatched identifiers. | | RFPX-0005 | businessType must be valid | Validate that the businessType field contains a supported value. Replace any invalid or unsupported business type with a valid value and resubmit the request. | | RFPX-0025 | paymentRequestLifecycleId in path param or paymentRequestLifecycleId in request is invalid | Verify that the paymentRequestLifecycleId is correct, properly formatted, and associated with an existing payment request. Ensure the same valid identifier is used throughout the request. | | RFPX-0038 | debtorId is invalid | Check that the debtorId provided in the request is valid and exists in the system. Correct any formatting issues and ensure the identifier references the intended debtor. | | RFPX-0040 | creditAccountUsed is invalid | Ensure that the creditAccountUsed field contains a valid and supported value. Review the request payload and update any incorrect account usage indicators. | | RFPX-0031 | transactionStatus is invalid | Validate that the transactionStatus field contains a supported status value. Replace any invalid status codes before resubmitting the request. | | RFPX-0032 | transactionStatusReason is invalid | Verify that the transactionStatusReason field contains a valid reason code applicable to the selected transaction status. Update unsupported or incorrect values as needed. | | RFPX-0042 | paymentDateTime must be present | Include the paymentDateTime field in the request and ensure it is populated with a valid date and time value in the expected format. | | RFPX-0039 | Payment amount must be present for Authorised payments | Ensure that payment amount details are provided whenever the transaction status is Authorised. Verify that the amount field is populated and correctly formatted. | | RFPX-0012 | currency must be a valid ISO-4217 alpha currency code | Confirm that the currency field contains a valid three-letter ISO-4217 currency code. Replace unsupported or incorrectly formatted currency values before retrying. | | RFPX-0013 | Amount must have valid number of fraction digits | Verify that the payment amount follows the correct decimal precision for the selected currency. Adjust the amount format to comply with currency-specific fraction digit requirements. | | RFPX-0048 | agreementConfirmed must be present for Pay and Link journeys when transaction is Authorised | Include the agreementConfirmed field when submitting an authorised Pay and Link transaction. Ensure the field is populated with an appropriate value before resubmitting the request. | | RFPX-0049 | accountNickName must be present for Pay and Link journeys when Transaction is Authorised | Provide a valid accountNickName when submitting an authorised Pay and Link transaction. Ensure the nickname is included and properly formatted in the request. | | RFPX-0050 | Payment Block should not be present if Transaction is not Approved | Remove the Payment Block section when the transaction status is not approved. Ensure payment details are included only for applicable transaction states. | | RFPX-0051 | Invalid paymentRequestStatusRetrievalLifecycleId | Verify that the paymentRequestStatusRetrievalLifecycleId is valid and associated with an existing status retrieval request. Correct any invalid or malformed identifier values. | | RFPX-0052 | Payment Confirmation Details must match with the first Payment Confirmation sent | Ensure that any subsequent payment confirmation uses the same key details as the original confirmation. Review transaction references, amounts, and related information for consistency. | | RFPX-0055 | Payment amount value must be the same as the amount in the associated payment request | Confirm that the payment amount exactly matches the amount specified in the original payment request. Update any discrepancies before resubmitting the confirmation. | | RFPX-0059 | Approved agreements must have accountNickname populated. Otherwise, agreementStatusReason should be populated for rejected agreements | Provide accountNickname when the agreement is approved. For rejected agreements, ensure a valid agreementStatusReason is included instead. | | RFPX-0058 | Invalid agreementStatusReason | Verify that the agreementStatusReason contains a valid and supported value. Replace any unsupported or incorrectly formatted reason codes before retrying the request. | ### Retrieve Payment {#retrieve-payment} | Error Code | Error Description | Resolution Tips | |------------|-------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | RFPX-0001 | X-Participant-ID must be a valid and active participant | Verify that the X-Participant-ID provided in the request header is correct and belongs to an active participant. Update the request with a valid participant identifier before retrying. | | RFPX-0004 | ServiceProviderId must match with X-Participant-ID and initiatingPartyId | Ensure that the ServiceProviderId, X-Participant-ID, and initiatingPartyId contain the same value. Review the request payload and headers for any mismatched identifiers. | | RFPX-0005 | businessType must be valid | Validate that the businessType field contains a supported value. Replace any invalid or unsupported business type with a valid value and resubmit the request. | | RFPX-0022 | retrieveInitMethod must be valid | Verify that the retrieveInitMethod field contains a supported and correctly formatted value. Replace any invalid retrieval initiation method before retrying the request. | | RFPX-0046 | Either paymentRequestLifecycleId (for INTENT) OR paymentRequestReferenceNumber (for PRN) must be populated and not both | Provide only one identifier based on the retrieval type being used. Use paymentRequestLifecycleId for INTENT retrievals or paymentRequestReferenceNumber for PRN retrievals, but do not include both in the same request. | | RFPX-0023 | Incorrect paymentRequestReferenceNumber | Verify that the paymentRequestReferenceNumber is correct and associated with an existing payment request. Check for data entry errors or invalid reference values before resubmitting. | | RFPX-0024 | Incorrect paymentRequestLifecycleId | Ensure that the paymentRequestLifecycleId is valid, properly formatted, and linked to an existing payment request. Use the correct lifecycle identifier when submitting the retrieval request. | | RFPX-0047 | Payment Request already retrieved or in an incorrect state | Check the current status of the payment request before attempting retrieval. Ensure the request has not already been retrieved and is in a state that supports the retrieval operation. | | RFPX-0045 | Transaction retrieval has timed out | The transaction retrieval request was not completed within the allowed timeframe. Initiate a new retrieval request using valid transaction reference information and retry the operation. | ### Refunds {#refunds} | Error Code | Error Description | Resolution Tips | |------------|-----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | RFND-0001 | X-Participant-ID must be a valid and active participant | Verify that the X-Participant-ID provided in the request header is correct and belongs to an active participant. Update the request with a valid participant identifier before retrying. | | RFND-0002 | InitiatingPartyId must be same as X-Participant-ID | Ensure that the InitiatingPartyId in the request payload exactly matches the value of the X-Participant-ID header. Review the request for any mismatched or incorrectly formatted identifiers. | | RFND-0026 | refundRequestStatusReason is invalid | Verify that the refundRequestStatusReason contains a valid and supported value. Replace any unsupported or incorrectly formatted reason codes before resubmitting the request. | | RFND-0034 | Debtor block must only be present if refundRequestStatus is APPR | Include the Debtor block only when the refundRequestStatus is APPR. Remove this block for all other refund request statuses. | | RFND-0025 | Either debtor account block or debtor Accounts with valid account details must be present for approved refund requests | Ensure that approved refund requests include debtor account information. Provide either the debtor account block or valid debtor account details before submitting the request. | | RFND-0022 | Must provide either IBAN or Other Account details | Include either a valid IBAN or complete alternative account details in the debtor account information. Verify that the selected account information is populated and correctly formatted. | | RFND-0023 | debtorAccountType should be from allowed account type values and should always be provided when refundRequestStatus is APPR | Ensure that debtorAccountType contains a supported account type value and is included whenever the refundRequestStatus is APPR. Review the account type for validity before retrying the request. | | RFND-0035 | accountNumber must only be present if refundRequestStatus is APPR and other block is present | Include accountNumber only when the refund request is approved and the corresponding account details block is provided. Remove the field if these conditions are not met. | ### Refund Status Retrievals {#refund-status-retrievals} | Error Code | Error Description | Resolution Tips | |------------|----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | RFND-0001 | X-Participant-ID must be a valid and active participant | Verify that the X-Participant-ID provided in the request header is correct and belongs to an active participant. Update the request with a valid participant identifier before retrying. | | RFND-0004 | ServiceProvider Id must match with X-Participant-ID and InitiatingParty Id | Ensure that the ServiceProviderId, X-Participant-ID, and InitiatingPartyId contain the same value. Review the request payload and headers for any mismatched identifiers. | | RFND-0003 | businessType must be valid | Validate that the businessType field contains a supported value. Replace any invalid or unsupported business type with a valid value and resubmit the request. | | RFND-0016 | refundRequestLifecycleId must be valid | Verify that the refundRequestLifecycleId is correctly formatted and associated with an existing refund request. Use a valid lifecycle identifier before retrying the request. | | RFND-0019 | refundRequestLifecycleId in the path parameter and refundRequestLifecycleId in the request should match | Ensure that the refundRequestLifecycleId in the URL path matches the value provided in the request body. Use the same identifier consistently throughout the request. | | RFND-0032 | paymentRequestLifecycleId in the path parameter should match paymentRequestLifecycleId in the request and be linked refundRequestLifecycleId | Verify that the paymentRequestLifecycleId in the path parameter matches the value in the request payload. Also confirm that the payment request is correctly linked to the specified refundRequestLifecycleId. | ### Retrieve CSPs {#retrieve-csps} | Error Code | Error Description | Resolution Tips | |------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | CSPL-0001 | X-Product-ID must be valid | Verify that the X-Product-ID header contains a valid product identifier supported by the service. Update the request with the correct product ID before retrying. | | CSPL-0002 | X-Participant-ID must be a valid and active participant | Ensure that the X-Participant-ID belongs to a valid and active DSP participant. Verify the participant status and update the request with a valid identifier if required. | | CSPL-0003 | categoryPurpose must be valid | Verify that the categoryPurpose field contains a supported value. Use IEXS as the category purpose and resubmit the request. | ### Request Alias Resolution {#request-alias-resolution} | Error Code | Error Description | Resolution Tips | |------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ALRE-0001 | X-Product-ID must be valid | X-Product-ID value should be- "IEXS". | | ALRE-0002 | X-Participant-ID must be a valid and active participant | Ensure that the X-Participant-ID belongs to a valid and active DSP participant. Verify the participant status before resubmitting the request. | | ALRE-0003 | initiatingPartyId must be the same as X-Participant-ID | Ensure that the initiatingPartyId exactly matches the X-Participant-ID provided in the request header. Correct any mismatched values before retrying. | | ALRE-0004 | creditorServiceProviderId must be a valid and active participant | Verify that the creditorServiceProviderId is valid and currently active. Update the request with a valid Creditor Service Provider identifier if necessary. | | ALRE-0017 | Creditor details type must be valid | PERS should be provided as creditor type. | | ALRE-0019 | nationality must be a valid ISO 3166-1 alpha-3 country code | Verify that the nationality field contains a valid ISO 3166-1 alpha-3 country code. Replace any invalid or unsupported country codes before resubmitting the request. | | ALRE-0020 | addressCountry must be a valid ISO 3166-1 alpha-3 country code | Ensure that the addressCountry value is a valid ISO 3166-1 alpha-3 country code. Correct any invalid country code entries in the request. | | ALRE-0021 | originatingCountry must be a valid ISO 3166-1 alpha-3 country code | Verify that the originatingCountry field contains a valid ISO 3166-1 alpha-3 country code. Update the value if it is missing or incorrectly formatted. | | ALRE-0024 | categoryPurpose must be valid | "IEXS" categoryPurpose should be provided. | | ALRE-0025 | debtorServiceProviderId must be a valid and active participant | Verify that the debtorServiceProviderId is valid and active. Use a valid Debtor Service Provider identifier in the request. | | ALRE-0026 | Debtor service provider must be enrolled for provided categoryPurpose | Ensure that the Debtor Service Provider is enrolled for the specified category purpose. For IEXS transactions, verify that the DSP is enabled for the IEXS use case. | | ALRE-0027 | Creditor service provider must be enrolled for provided categoryPurpose | CVerify that the Creditor Service Provider is enrolled for the specified category purpose. For IEXS transactions, ensure the CSP is enabled for the IEXS use case. | | ALRE-0028 | Alias type must be valid and supported by the creditor service provider | Ensure that the alias type is supported by the Creditor Service Provider. Use a supported alias such as email, phone number, account name, or another permitted alias type. | | ALRE-0029 | personDetails is supported with creditor type PERS | Include the personDetails block when aliasDetails -\> creditorDetails -\> type is set to PERS. Ensure all required person information is provided. | | ALRE-0030 | Debtor details type must be valid | Ensure that the debtor details type contains a supported value. Use PERS when submitting person-based debtor details. | | ALRE-0031 | personDetails must be provided when debtorDetails type is PERS | Include the personDetails block whenever debtorDetails.type is set to PERS. Verify that all mandatory person information is populated. | | ALRE-0032 | currency must be a valid ISO-4217 alpha currency code | Verify that the currency field contains a valid ISO-4217 three-letter currency code. Replace invalid or unsupported currency values before retrying. | | ALRE-0033 | Amount must have valid number of fraction digits as per currency | Ensure that the amount uses the correct number of decimal places for the specified currency. Adjust the amount precision to comply with currency standards before resubmitting the request. | #### Sample Business Rule Error Message {#sample-business-rule-error-message} { "Errors": { "Error": [ { "Source": "ZAPP", "ReasonCode": "RFPX-0023", "Description": "Incorrect Payment Reference number", "Recoverable": false, "Details": "NA" } ] } }