When a credit card transaction is blocked by the issuing bank’s risk controls, PayGate may return additional information in the payment response.
This occurs when a Merchant Advice Code (MAC) indicates that the merchant/card combination should be blocked for the current transaction or future attempts.
This page explains how to read and interpret these fields in PayHost responses.
Overview
When a transaction is blocked due to risk rules, the response will include a RiskDetails element containing:
-
MerchantAdviceCode (MAC)
-
BlockStatus information
No changes are required to your payment requests.
Your integration only needs to read these additional response elements.
Response Elements
RiskDetails
Contains the MAC code returned by the bank and details about the block applied.
Fields
| Field | Description | Required | Type |
|---|---|---|---|
| MerchantAdviceCode | Code received from the bank indicating the reason for the block | Yes | String |
| BlockStatus | Information about whether the block is permanent or temporary | Yes | RiskBlockStatusType |
RiskBlockStatus
Provides details about the duration of the block.
Fields
| Field | Description | Required | Type | Example |
|---|---|---|---|---|
| Permanent | Indicates whether the merchant/card combination is permanently blocked | Yes | Boolean | false |
| UntilDate | Date when the block will be lifted (if temporary) | Optional | DateTime | 2025-02-16T09:13:31.000+02:00 |
If the block is permanent, the UntilDate field will not be present.
Merchant Advice Codes (MAC)
The MerchantAdviceCode returned in the RiskDetails element indicates the recommended action the merchant should take when a transaction is declined or blocked.
| Merchant Advice Code | Description | Possible Reason | Recommended Action |
|---|---|---|---|
| 01 | Updated information needed | Expired card, account upgrade, or portfolio conversion | Obtain updated account information before the next billing cycle |
| 02 | Try again later | Over credit limit or insufficient funds | Retry the transaction after 72 hours |
| 03 | Do not try again | Account closed or fraudulent activity | Request another payment method from the customer |
| 04 | Transaction not supported | SLI or cryptographic data issue | Resubmit the transaction with corrected information |
| *21 | Stop recurring payment requests | Cardholder cancelled agreement | Do not retry this payment |
| 24 | Retry after 1 hour | Credit limit issues or insufficient funds | Retry after 1 hour |
| 25 | Retry after 24 hours | Credit limit issues or insufficient funds | Retry after 24 hours |
| 26 | Retry after 2 days | Credit limit issues or insufficient funds | Retry after 2 days |
| 27 | Retry after 4 days | Credit limit issues or insufficient funds | Retry after 4 days |
| 28 | Retry after 6 days | Credit limit issues or insufficient funds | Retry after 6 days |
| 29 | Retry after 8 days | Credit limit issues or insufficient funds | Retry after 8 days |
| 30 | Retry after 10 days | Credit limit issues or insufficient funds | Retry after 10 days |
| 40 | Non reloadable prepaid card | Issuer recognized a consumer non reloadable prepaid card was used | No action required |
| 41 | Single use virtual card number | Issuer recognized a consumer single use virtual card number was used | No action required |
| 42 | Sanctions scoring service | Mastercard refused the transaction due to a sanctions match | No action required |
| 43 | Consumer multi use virtual card number | Transaction carried out using a consumer multi use virtual card number | No action required |
Example CardPaymentResponse (Risk Blocked)
<ns2:RiskDetails>
<ns2:MerchantAdviceCode>2</ns2:MerchantAdviceCode>
<ns2:BlockStatus>
<ns2:Permanent>false</ns2:Permanent>
<ns2:UntilDate>2025-02-16T09:13:31.000+02:00</ns2:UntilDate>
</ns2:BlockStatus>
</ns2:RiskDetails>