# Business Rule Errors source: https://developer.mastercard.com/account-to-account-commerce-for-csp/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 error description to indicate the reason for the message failure. The participant is then expected to fix the issue and send a new message. ### Create Agreement {#create-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 exists in the participant registry. Confirm that the participant status is active in the correct environment. | | AGRM-0003 | initiatingPartyId must be the same as X-Participant-ID | Ensure the initiatingPartyId value exactly matches the X-Participant-ID. Check for case sensitivity and formatting mismatches in the request. | | AGRM-0004 | businessType must be valid | Use a businessType value supported by the A2AC specification. Validate the value against the allowed enum list before sending the request. | | AGRM-0006 | The creditor must be active and associated to the Creditor Service Provider | Confirm that the creditor is active in the system. Verify that the creditor is correctly linked to the specified CSP. | | AGRM-0007 | agreementType must be valid | Provide an agreementType value defined in the agreement configuration. Ensure the value matches the supported agreement types for A2AC flows. | ### 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 exists in the participant registry. Confirm that the participant status is active in the correct environment. | | AGRM-0003 | initiatingPartyId must be the same as X-Participant-ID | Ensure the initiatingPartyId exactly matches the X-Participant-ID. Check for case sensitivity or formatting mismatches. | | AGRM-0004 | businessType must be valid | Use a businessType value supported by the A2AC specification. Validate the value against the allowed list before sending the request. | | AGRM-0006 | The creditor must be active and associated to the Creditor Service Provider | Confirm that the creditor status is active. Verify that the creditor is correctly associated with the specified CSP. | | AGRM-0033 | Agreement Id in path param should match with the agreement Id in request | Ensure the agreementId in the path matches the agreementId in the request body. Update the request to use a single, consistent agreementId. | | AGRM-0034 | agreementId must be valid | Provide an agreementId that exists in the system. Verify that the agreementId format and value are correct. | | AGRM-0035 | Agreement Id is not associated with creditor Id | Verify that the agreementId belongs to the specified creditorId. Use an agreement that is correctly linked to the creditor. | | AGRM-0036 | agreementStatus can only be DELT | Ensure the agreement status is set to DELT before performing this action. Update the agreement status if it does not meet this requirement. | | AGRM-0037 | Only approved or rejected agreements can be deleted | Confirm that the agreement status is either APPROVED or REJECTED. Change the status before attempting to delete the agreement. | ### Agreement Status Retrievals {#agreement-status-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 account is enabled and correctly registered 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 formatting issues, spaces, or incorrect identifiers. | | AGRM-0004 | businessType must be valid | Validate that the businessType provided in the request is supported and correctly formatted. Replace invalid or unsupported values with an approved business type. | | AGRM-0033 | Agreement Id in path param should match with the agreement Id in request | Confirm that the Agreement ID in the request URL matches the agreementId present in the request payload. Use a consistent agreement reference throughout the request. | | AGRM-0034 | agreementId must be valid | Check that the agreementId is valid, correctly formatted, and available in the system. Avoid using deleted, expired, or incorrect agreement references. | | AGRM-0035 | Agreement Id is not associated with creditor Id | Verify that the Agreement ID is linked to the correct creditor ID. Review the agreement and creditor association details before retrying the transaction. | | AGRM-0006 | The creditor must be active and associated to the Creditor Service Provider | Ensure the creditor is active and properly associated with the related Creditor Service Provider. Update or activate the creditor relationship if required before submitting the request again. | ### Create Payment {#create-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 header contains a valid and active participant identifier. Ensure the participant account is correctly registered and enabled before retrying the request. | | RFPX-0004 | ServiceProviderId must match with X-Participant-ID and initiatingPartyId | Ensure the ServiceProviderId, X-Participant-ID, and initiatingPartyId values are identical across the request. Review the request payload and header values for mismatches or formatting issues. | | RFPX-0005 | businessType must be valid | Validate that the businessType field contains a supported and correctly formatted value. Replace invalid entries with an approved business type before resubmitting the request. | | RFPX-0006 | creditorId must be active and linked to creditor service provider | Check that the creditorId is active and linked to the correct creditor service provider. Update the creditor association or activate the creditor account if required. | | RFPX-0007 | creditorReturnString must be provided when purpose is ONLN | Ensure the creditorReturnString field is included whenever the purpose value is set to ONLN. Provide a valid return string in the request payload before retrying. | | RFPX-0010 | paymentRequestType must be valid | Verify that the paymentRequestType value provided in the request is valid and supported. Correct any invalid or unsupported request type values before submission. | | RFPX-0012 | currency must be a valid ISO-4217 alpha currency code | Confirm that the currency field uses a valid ISO-4217 three-letter currency code, such as USD or EUR. Remove unsupported or incorrectly formatted currency values. | | RFPX-0013 | Amount must have valid number of fraction digits | Ensure the payment amount contains the correct number of decimal or fraction digits for the selected currency. Review the amount format and comply with standard currency precision rules. | | RFPX-0014 | purpose must be valid | Validate that the purpose value provided in the request is supported and correctly formatted. Replace invalid values with an approved purpose code before retrying. | | RFPX-0015 | categoryPurpose must be valid | Check that the categoryPurpose field contains a valid and supported value. Review the request payload and update any incorrect category purpose codes. | | RFPX-0017 | restriction must be valid | Verify that the restriction field contains a supported restriction type or code. Remove unsupported restrictions or replace them with valid values. | | RFPX-0019 | Must be an active and valid agreement | Ensure the agreement linked to the request is active, valid, and not expired or suspended. Use a valid agreement reference before submitting the payment request. | | RFPX-0020 | agreementType must be valid | Confirm that the agreementType field contains a valid and supported agreement type. Review the request values and update any invalid agreement type entries. | | RFPX-0056 | creditorAccount must be present when categoryPurpose is MTOM | Include the creditorAccount field in the request whenever the categoryPurpose is set to MTOM. Verify that the account information is complete and correctly formatted. | ### Status Retrievals {#status-retrievals} | Error Code | Error Description | Resolution Tips | |------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | RFPX-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 account is active and properly configured before retrying the request. | | RFPX-0004 | ServiceProviderId must match with X-Participant-ID and initiatingPartyId | Ensure the ServiceProviderId, X-Participant-ID, and initiatingPartyId values match exactly across the request. Review the request payload and header data for inconsistencies or formatting errors. | | RFPX-0005 | businessType must be valid | Validate that the businessType field contains a supported and correctly formatted value. Replace invalid entries with an approved business type before resubmitting the request. | | RFPX-0006 | creditorId must be active and linked to creditor service provider | Check that the creditorId is active and linked to the correct creditor service provider. Update the creditor mapping or activate the creditor account if necessary before retrying. | | RFPX-0053 | payment_request_lifecycle_id is invalid | Verify that the payment_request_lifecycle_id provided in the request is valid and exists in the system. Ensure the identifier is correctly formatted and associated with an active payment request. | | RFPX-0054 | paymentRequestLifecycleId is invalid | Confirm that the paymentRequestLifecycleId value is correct, properly formatted, and linked to a valid payment lifecycle record. Avoid using expired, incorrect, or incomplete lifecycle identifiers. | ### 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 header contains a valid and active participant identifier. Ensure the participant account is active and properly registered before retrying the request. | | RFND-0004 | ServiceProvider Id must match with X-Participant-ID and InitiatingParty Id | Ensure the ServiceProviderId, X-Participant-ID, and InitiatingPartyId values match exactly in the request. Review the payload and headers for mismatched or incorrectly formatted identifiers. | | RFND-0003 | businessType must be valid | Validate that the businessType field contains a supported and correctly formatted value. Replace invalid business type entries with approved values before resubmitting the request. | | RFND-0005 | creditorId is not associated with Creditor service provider or it is not in active state | Check that the creditorId is active and properly associated with the relevant creditor service provider. Update the creditor mapping or activate the creditor account if required. | | RFND-0006 | caseReferenceId must be present if refundReason is DISPUTES | Ensure the caseReferenceId field is included whenever the refundReason is set to DISPUTES. Provide a valid dispute reference before retrying the refund request. | | RFND-0007 | currency must be a valid ISO-4217 alpha currency code | Confirm that the currency field uses a valid ISO-4217 three-letter currency code such as USD or EUR. Remove unsupported or incorrectly formatted currency values. | | RFND-0008 | refundAmount value must be greater than zero and have valid number of fraction digits | Verify that the refundAmount is greater than zero and follows the correct currency precision rules. Ensure the amount contains valid fraction digits for the selected currency. | | RFND-0009 | refundReason must be valid | Validate that the refundReason field contains a supported and correctly formatted value. Replace invalid or unsupported refund reason codes before resubmitting the request. | | RFND-0011 | refundStatus must be valid | Ensure the refundStatus value is valid and supported by the system. Review the request payload and update any incorrect status values. | | RFND-0012 | refundStatusReason must be provided if refundStatus is DECL | Include the refundStatusReason field whenever the refundStatus is set to DECL. Ensure the reason code or description provided is valid and properly formatted. | | RFND-0013 | refundPaymentConfirmation must be provided if refundStatus is APPR | Provide the refundPaymentConfirmation details when the refundStatus is set to APPR. Ensure the confirmation information is complete and correctly formatted. | | RFND-0016 | refundRequestLifecycleId must be valid | Verify that the refundRequestLifecycleId is valid, correctly formatted, and linked to an existing refund request. Avoid using expired or incorrect lifecycle identifiers. | | RFND-0017 | Either paymentRequestLifecycleId is not valid or payment request may not be Authorised | Check that the paymentRequestLifecycleId is valid and associated with a payment request in an Authorised state. Use an eligible payment request reference before submitting the refund. | | RFND-0018 | paymentRequestLifecycleId in path param should match with the paymentRequestLifecycleId in request | Confirm that the paymentRequestLifecycleId in the request path matches the value included in the request payload. Use the same lifecycle identifier consistently throughout the request. | | RFND-0019 | refundRequestLifecycleId in path param and refundRequestLifecycleId in request should match | Ensure the refundRequestLifecycleId provided in the path parameter matches the value in the request body. Verify that both identifiers are identical before resubmitting the request. | | RFND-0020 | paymentRequestLifecycleId must be valid | Verify that the paymentRequestLifecycleId is correct, properly formatted, and linked to an existing payment request. Avoid using invalid or incomplete identifiers. | | RFND-0021 | Refund Payment Confirmation already received or is in incorrect state | Check whether a refund payment confirmation has already been submitted or if the refund request is in an invalid state. Review the current refund status before attempting another confirmation submission. | | RFND-0029 | Invalid refundRequestStatusRetrievalLifecycleId | Validate that the refundRequestStatusRetrievalLifecycleId is correct and associated with an existing refund status retrieval request. Correct any invalid or malformed identifier values before retrying. | | RFND-0030 | The second confirmation advice having refundRequestStatusRetrievalLifecycleId MUST have the same key information as the first confirmation advice | Ensure the second confirmation advice uses the same key information as the initial confirmation advice. Verify that all required reference fields and transaction details match exactly between both requests. | ### Alias Resolution Update {#alias-resolution-update} | 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. | X-Participant-ID participant must be active and valid as per onboarding DB. | | ALRE-0003 | initiatingPartyId must be the same as X-Participant-ID. | initiatingPartyId and X-Participant-ID should be same. | | ALRE-0004 | creditorServiceProviderId must be a valid and active participant. | Creditor service provider ID must be valid and active as per onboarding DB. | | ALRE-0005 | aliasLifecycleId must be valid. | aliasLifecycleId provided should be valid (exists in IEXS DB) This is also for the scenario where CSP Id associated with the alias resolution request does not match with the CSP Id provided in the alias resolution update flow. | | ALRE-0006 | Unable to process the update: Current alias resolution status is invalid for the provided aliasLifecycleId. | status is INPR instead of CSPR for the provided aliasLifecycleId and Mastercard has received an update from the CSP for the same aliasLifecycleId. | | ALRE-0007 | Alias resolution update rejected: request with provided aliasLifecycleId is either already resolved or rejected. | status is either RSVD/RJCT instead of CSPR for the provided aliasLifecycleId and Mastercard has received an update from the CSP for same aliasLifecycleId. | | ALRE-0008 | status must be valid. | CSP should provide valid status i.e. either RSVD or RJCT. | | ALRE-0009 | reasonCode must be provided when alias resolution status is RJCT. | reasonCode is applicable only for rejected alias resolution updates (aliasResolutionStatus -\> status = RJCT). | | ALRE-0010 | aliasDetails must be provided when alias resolution status is RSVD. | aliasDetails should be provided only if the alias has been resolved successfully (aliasResolutionStatus -\> status = RSVD). | | ALRE-0011 | reasonCode must be valid. | CSP should provide valid status reasonCode from the list of supported values. | | ALRE-0012 | Alias details type must be valid. | Alias details type provided should be valid value. | | ALRE-0013 | bankAccountDetails must be provided when aliasDetails type is BANK. | bankAccountDetails should be provided when aliasDetails-\>type is BANK. | | ALRE-0014 | walletAccountDetails must be provided when aliasDetails type is WALL. | walletAccountDetails should be provided when aliasDetails-\>type is WALL. | | ALRE-0015 | accountNumberType must be valid. | accountNumberType provided should be either IBAN or BBAN. | | ALRE-0016 | accountType must be valid. | accountType provided should be valid value. | | ALRE-0017 | Creditor details type must be valid. | PERS should be provided as creditor details type. | | ALRE-0018 | personDetails must be provided when creditorDetails type is PERS. | personDetails should be provided when aliasDetails -\> creditorDetails -\>type is PERS. | | ALRE-0019 | nationality must be a valid ISO 3166-1 alpha-3 country code. | nationality should be valid ISO country code. | | ALRE-0020 | country must be a valid ISO 3166-1 alpha-3 country code. | address -\> country should be valid ISO country code. | | ALRE-0021 | Government id type must be valid. | Government id type provided should be valid value. | | ALRE-0022 | issuingCountry must be a valid ISO 3166-1 alpha-3 country code. | issuingCountry should be valid ISO country code. | | ALRE-0023 | Alias resolution request expired: update provided post expiryTimeInterval. | CSP should provide alias resolution update within expiryTimeInterval. | #### Sample Business Rule Error Message (Inbound APIs) {#sample-business-rule-error-message-inbound-apis} { "Errors": { "Error": [ { "Source": "ZAPP", "ReasonCode": "RFPX-0023", "Description": "Incorrect Payment Reference Number", "Recoverable": false, "Details": "NA" } ] } }