# PAYMENT_FAILED

# PAYMENT_FAILED

The payment was declined and the processor did not tell us why. This is the unattributed decline — the generic answer we return whenever a payment fails without a reason we can map to something more specific.

## Summary

| Field | Value |
|---|---|
| Appears as | `errors[].code` |
| Response | HTTP `200` — `Order` with `isValid: false` and a populated `errors[]` |
| Retry the same card | No |

:::note[This is a reason code, not a top-level error code]
`PAYMENT_FAILED` is an `errors[].code` value on the order. It is **not** a top-level
`ProblemDetail.errorCode`, so it carries no HTTP status, `errorCategory`, or `retryable` field of its
own. See [Unified OrderError shape](/distribution-partners/marketfront-api/guides/order-lifecycle#unified-ordererror-shape).
:::

## When This Fires

- **`POST /v1/marketfront/orders/place`** — payment authorization failed and the decline carried no attributable reason, or carried one we deliberately do not refine (an address-verification failure, for example).

`PAYMENT_FAILED` is not superseded by the more specific decline reasons — it remains the correct answer for a generic decline. If you need to branch on *why* a payment failed, handle the specific codes and let `PAYMENT_FAILED` be your default case.

## Recommended Action

Ask the user for a different payment method:

1. Show a clear "your card was declined — please try another payment method" message.
2. Open the payment-method picker.
3. Resubmit `place` with the new method.

Do not retry the declined card automatically — this is a decision by the issuer, not a transient fault, so a retry will return the same answer and repeated attempts can trigger fraud lockouts.

:::note[Looking for the retryable case?]
If the payment failed because of a timeout or a fault at the processor rather than a decision about
the card, that is [`PROCESSING_ERROR`](/errors/PROCESSING_ERROR) — the one payment reason where
retrying the same card is sensible advice, and the one that needs idempotency care to avoid a
double charge.
:::

## Related codes

More specific decline reasons refine this one. All are `errors[].code` values:

| Code | When you get it instead |
|---|---|
| [`INSUFFICIENT_FUNDS`](/errors/INSUFFICIENT_FUNDS) | The account does not cover the amount |
| [`INCORRECT_CVC`](/errors/INCORRECT_CVC) | The security code did not match |
| [`CARD_EXPIRED`](/errors/CARD_EXPIRED) | The card has expired |
| [`CARD_LOST_OR_STOLEN`](/errors/CARD_LOST_OR_STOLEN) | The credential is flagged — never retry, never explain |
| [`PROCESSING_ERROR`](/errors/PROCESSING_ERROR) | A transient fault, not a decline |

## Example

```json
{
  "isValid": false,
  "errors": [
    {
      "code": "PAYMENT_FAILED",
      "message": "We couldn't process your payment. Please try a different payment method.",
      "pointer": null
    }
  ]
}
```