Provider errors

How Yuno surfaces downstream payment provider errors, the ISO 8583 decline codes you will see, and how to decide whether to retry or fail.

When a payment fails at the provider (the issuer, the acquirer, or the gateway between them), Yuno wraps the failure in its standard error envelope and surfaces the provider’s raw response so you can inspect it.

How provider errors are returned

Errors that originate downstream are returned with a PROVIDER_* prefixed code in the standard error envelope, and the provider’s raw text in messages.

{
  "code": "PROVIDER_INVALID_REQUEST",
  "messages": [
    "Insufficient funds (provider response code 51)"
  ]
}

The full set of PROVIDER_* codes is documented in Error codes. Common ones include PROVIDER_INVALID_REQUEST, PROVIDER_REQUEST_TIMEOUT, PROVIDER_PAYMENT_NOT_FOUND, PROVIDER_INVALID_AMOUNT, PROVIDER_COUNTRY_NOT_SUPPORTED, PROVIDER_CURRENCY_NOT_ALLOWED, and PROVIDER_UNAVAILABLE_PAYMENT_METHOD.

For card payments that the issuer declined, retrieve the payment with Get Payment and inspect the transaction history. Each transaction includes the provider’s raw response, including the ISO 8583 decline code.

Soft vs hard declines

Whether you should retry a card decline depends on the type of decline. Soft declines may resolve on their own. Hard declines will not.

Type	Description	Retry?	Examples
Soft decline	Temporary issue that may resolve.	Yes, with backoff and a sensible attempt cap.	Insufficient funds, issuer timeout, network error.
Hard decline	Permanent issue that will not resolve on retry.	No. Surface to the customer.	Invalid card number, stolen card, closed account.

Retrying hard declines wastes processing capacity and can trigger card network fraud rules. Always classify the decline type before deciding to retry.

Common ISO 8583 decline codes

These are standard codes returned by card issuers and surfaced by every major acquirer. Yuno passes them through verbatim in the transaction response.

Card declines

Code	Description	Type	Recommended action
01	Refer to issuer	Soft	Ask the customer to contact their bank.
02	Refer to issuer (special)	Soft	Ask the customer to contact their bank.
04	Pick up card	Hard	Do not retry. Card reported lost or stolen.
05	Do not honor	Soft	Retry once. If it fails, ask for an alternate method.
12	Invalid transaction	Hard	Verify transaction parameters.
13	Invalid amount	Hard	Check amount format and provider limits.
14	Invalid card number	Hard	Ask the customer to re enter card details.
41	Lost card	Hard	Do not retry.
43	Stolen card	Hard	Do not retry.
51	Insufficient funds	Soft	Inform the customer. Suggest a lower amount or retry later.
54	Expired card	Hard	Ask the customer for a valid card.
55	Incorrect PIN	Soft	Ask the customer to re enter the PIN.
57	Transaction not permitted	Hard	Card type is not allowed for this transaction.
61	Exceeds withdrawal limit	Soft	Suggest a lower amount or retry the next day.
65	Activity count limit exceeded	Soft	Retry later.

Network and gateway issues

Code	Description	Type	Recommended action
91	Issuer unavailable	Soft	Retry with exponential backoff.
96	System malfunction	Soft	Retry after a short delay.

For non card methods (PIX, Boleto, OXXO, PSE, SEPA DD, ACH DD, and others), providers do not use ISO 8583 codes. The Yuno code will still be a PROVIDER_* value and the provider’s raw text will be in messages. Inspect the message for the provider specific reason.

MCC restrictions

Some declines relate to the Merchant Category Code (MCC) on your account.

Scenario	Cause	Resolution
”Transaction not permitted” for specific card types	MCC restriction by issuer	Contact Yuno support to verify MCC assignment.
High decline rates for certain countries	MCC flagged for risk in that region	Review with the provider.
Recurring payment declines	MCC not enabled for recurring	Update MCC configuration.

Retry strategy

1. Classify the decline

   Read the ISO 8583 code (cards) or the provider message (non card) and decide if it is soft or hard using the tables above.

2. For a soft decline, retry with backoff

   Use exponential backoff with full jitter. Cap retries at 3 attempts. Do not retry faster than every 1 s.

   const SOFT_DECLINES = new Set(["01", "02", "05", "51", "55", "61", "65", "91", "96"]);
   
   if (SOFT_DECLINES.has(providerResponseCode)) {
     // Retry with exponential backoff and full jitter, max 3 attempts.
   }
   
3. For a hard decline, do not retry

   Surface a clear message to the customer and offer an alternate payment method.

Card networks impose retry limits. Mastercard allows up to 10 retries per card per 24 hours. Visa allows up to 15 retries per card per 30 days. Exceeding these limits can result in fines from the network. Track your per card retry counts.

Escalating provider issues

If you encounter persistent provider errors that are not listed here, open a support ticket with:

• The Yuno payment_id and the response x-trace-id header.
• The provider name and the raw response code or message.
• Timestamp and frequency.