--- updatedAt: 2026-08-24T17:14:27.000Z agentTools: projectIndex: https://docs.dlocal.com/llms.txt --- # Network Response When a card payment is declined, dLocal returns raw data from the card scheme and issuer in the `acquirer` object of the payment response. This gives you direct access to the network-level decline reason which is useful for building precise retry logic, debugging decline patterns at scale, and mapping issuer responses to your own internal systems. dLocal's `status_code` and `status_detail` fields remain the primary way to handle payment outcomes. The `acquirer` object is an additional layer for integrations that require scheme-level granularity. > **Note:** These fields are available upon request. Contact your Technical Account Manager to enable the `acquirer` response fields for your account. *** ## The `acquirer` object The `acquirer` object is returned in the payment response when a card payment is declined and the fields are enabled for your account. These fields are returned in the real-time payment response (POST `/payments`), when retrieving a payment via GET `/payments/{id}`, and in the IPN notification for asynchronous payment flows. | Field | Type | Description | | ------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------ | | `network_response_code` | String | The raw ISO 8583 response code returned by the card scheme or issuer (e.g. `05`, `51`, `N7`) | | `network_response_description` | String | Human-readable description of the network response code | | `merchant_advice_code` | String | Mastercard only. A code provided by the issuer with specific guidance on whether and when to retry the transaction | | `merchant_advice_description` | String | Human-readable description of the merchant advice code | ### Example responses **Declined Mastercard payment with MAC** ```json { "id": "T-4-cf8eef6b-52d5-4320-b5ea-f5e0bbe4343f", "amount": 10.00, "currency": "BRL", "payment_method_id": "CARD", "payment_method_type": "CARD", "payment_method_flow": "DIRECT", "country": "BR", "card": { "holder_name": "John Doe", "expiration_month": 6, "expiration_year": 2026, "brand": "MC", "last4": "4444" }, "created_date": "2024-01-15T14:22:31.000+0000", "status": "REJECTED", "status_code": "306", "status_detail": "Call bank for authorize", "order_id": "order-001", "acquirer": { "network_response_code": "05", "network_response_description": "Do not honor", "merchant_advice_code": "03", "merchant_advice_description": "Do not try again" } } ``` **Declined Visa payment** ```json { "id": "T-4-ab3de12f-11c4-4781-a3ea-c2e1cc5b231a", "amount": 10.00, "currency": "BRL", "payment_method_id": "CARD", "payment_method_type": "CARD", "payment_method_flow": "DIRECT", "country": "BR", "card": { "holder_name": "John Doe", "expiration_month": 6, "expiration_year": 2026, "brand": "VI", "last4": "1111" }, "created_date": "2024-01-15T14:22:31.000+0000", "status": "REJECTED", "status_code": "302", "status_detail": "Insufficient amount", "order_id": "order-002", "acquirer": { "network_response_code": "51", "network_response_description": "Insufficient funds/over credit limit" } } ``` > `merchant_advice_code` and `merchant_advice_description` are only returned for Mastercard transactions where the issuer includes them in the authorization response. For Visa transactions, only the network response fields are returned. *** ## Merchant Advice Codes (Mastercard) Merchant Advice Codes (MACs) are returned by Mastercard issuers to provide explicit retry guidance. When present, the MAC takes precedence over `networkResponseCode` for determining retry behavior. | MAC Code | Description | Type | Recommended action | | -------- | ---------------------------- | ----- | ---------------------------------------------------------------------------------------------- | | 01 | Updated information required | Soft | Request updated card details from the cardholder before retrying | | 02 | Try again later | Soft | Retry after a short delay | | 03 | Do not try again | Hard | Do not retry. Advise the cardholder to contact their bank | | 21 | Payment cancellation | Hard | Do not retry. The cardholder has revoked the recurring payment authorization with their issuer | | 24 | Retry after 1 hour | Timed | Retry after at least 1 hour | | 25 | Retry after 24 hours | Timed | Retry after at least 24 hours | | 26 | Retry after 2 days | Timed | Retry after at least 2 days | | 27 | Retry after 4 days | Timed | Retry after at least 4 days | | 28 | Retry after 6 days | Timed | Retry after at least 6 days | | 29 | Retry after 8 days | Timed | Retry after at least 8 days | | 30 | Retry after 10 days | Timed | Retry after at least 10 days | *** ## Retry guidance Use the following decision logic when handling declined card payments: **Mastercard:** Check `merchant_advice_code` first. If present, follow its instruction — it represents explicit guidance from the issuer. If not present, fall back to `network_response_code`. **Visa:** Use `network_response_code` directly. Visa does not use MACs. As a general rule: * **Hard** declines should not be retried. * **Soft** declines can be retried with spacing and within the limits set by each card scheme. * **Timed** declines (Mastercard only) should be retried only after the specified interval. For the full mapping between network response codes and dLocal status codes, see [Payment status codes](https://docs.dlocal.com/reference/payment-status-codes). ## Scheme retry limits Card schemes enforce limits on how many times you can retry a declined transaction. Exceeding these limits can result in fees and negatively impact your authorization rates. **Visa** | Category | Description | Retry limit | | ---------- | ------------------------------------ | --------------------------------------------------------------------- | | Category 1 | Hard declines | Do not retry | | Category 2 | Issuer or cardholder action required | Up to 15 attempts over 30 days | | Category 3 | Data quality issues | Up to 15 attempts over 30 days — revalidate card data before retrying | | Category 4 | Generic declines | Up to 15 consecutive attempts over 30 days | **Mastercard** For Mastercard, retry behavior is determined by the MAC code when present — follow the interval and limits specified in the [Merchant Advice Codes](#merchant-advice-codes-mastercard) table above. When no MAC is returned, do not retry more than 15 times over a 30-day period.