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.

Example responses

Declined Mastercard payment with MAC

{
  "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

{
  "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.

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.

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

Mastercard

For Mastercard, retry behavior is determined by the MAC code when present — follow the interval and limits specified in the Merchant Advice Codes table above. When no MAC is returned, do not retry more than 15 times over a 30-day period.