Hantera Betalningsmisslyckanden

När en betalning misslyckas talar Dodo Payments om varför genom en standardiserad error_code och en läsbar error_message. Denna guide visar hur man läser dessa fält, avgör om en ny försök är värt och återställer betalningen utan att exponera känslig information för kunderna.

Hur Dodo Payments Rapporterar Ett Fel

Varje misslyckad betalning — oavsett om det är en engångskassa eller en abonnemangsförnyelse — bär samma fel fält på betalningsobjektet:

Fält	Typ	Beskrivning
`status`	string	`failed` för en misslyckad betalning. Andra icke-framgångsstatusar inkluderar `cancelled`, `requires_customer_action` och `requires_payment_method`.
`error_code`	string \| null	Den standardiserade anledningen till misslyckandet, till exempel `INSUFFICIENT_FUNDS` eller `PROCESSING_ERROR`. Se referensen för Transaktionsfel för hela listan.
`error_message`	string \| null	En läsbar förklaring av felet.
`retry_attempt`	integer	`0` för den ursprungliga avgiften. `1` eller högre identifierar en schemalagd abonnemangsförnyelseförsök.

error_code och error_message är null tills en betalning faktiskt misslyckas. Kontrollera alltid status först och läs sedan fält för fel.

Webhook för `payment.failed`

Det mest pålitliga sättet att upptäcka ett fel är webhooken payment.failed. Händelsen omsluter det fullständiga betalningsobjektet i data:

payment.failed payload

{
  "business_id": "bus_P3SXLcppjXgagmHS",
  "type": "payment.failed",
  "timestamp": "2025-08-04T05:36:41.609359Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
    "status": "failed",
    "error_code": "PROCESSING_ERROR",
    "error_message": "An error occurred while processing your card. Try again in a little bit.",
    "retry_attempt": 0,
    "subscription_id": null,
    "currency": "USD",
    "total_amount": 400,
    "payment_method": "card",
    "card_last_four": "0119",
    "card_network": "VISA",
    "payment_link": "https://test.checkout.dodopayments.com/cbq",
    "customer": {
      "customer_id": "cus_8VbC6JDZzPEqfB",
      "email": "test@acme.com",
      "name": "Test user"
    }
  }
}

En minimal hanterare läser error_code och dirigerar utifrån det:

import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
// Mount the raw body parser so the exact payload is available for verification
app.use(express.raw({ type: "application/json" }));

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);

app.post("/webhooks/dodo", async (req, res) => {
  // Verify the signature against the raw body before trusting the payload
  const payload = req.body.toString();
  await webhook.verify(payload, req.headers);

  const event = JSON.parse(payload);

  if (event.type === "payment.failed") {
    const payment = event.data;

    console.log(
      `Payment ${payment.payment_id} failed: ${payment.error_code} (${payment.error_message})`
    );

    if (payment.subscription_id) {
      // Subscription renewal — Dodo retries soft declines for you
      await flagSubscriptionPaymentIssue(payment.subscription_id, payment.error_code);
    } else {
      // One-time payment — prompt the customer to try again
      await notifyCustomerOfFailedPayment(payment.customer.customer_id, payment.error_code);
    }
  }

  res.json({ received: true });
});

import os
from fastapi import FastAPI, Request
from standardwebhooks import Webhook

app = FastAPI()
webhook = Webhook(os.environ["DODO_PAYMENTS_WEBHOOK_KEY"])

@app.post("/webhooks/dodo")
async def handle_webhook(request: Request):
    # Verify the signature before trusting the payload
    payload = await request.body()
    webhook.verify(payload, dict(request.headers))

    event = await request.json()

    if event["type"] == "payment.failed":
        payment = event["data"]

        print(
            f"Payment {payment['payment_id']} failed: "
            f"{payment['error_code']} ({payment['error_message']})"
        )

        if payment["subscription_id"]:
            # Subscription renewal — Dodo retries soft declines for you
            flag_subscription_payment_issue(payment["subscription_id"], payment["error_code"])
        else:
            # One-time payment — prompt the customer to try again
            notify_customer_of_failed_payment(payment["customer"]["customer_id"], payment["error_code"])

    return {"received": True}

Verifiera alltid webhookens signatur innan du behandlar den. Se Webhooks guide för fullständig installation, inklusive signaturverifiering och idempotens.

Avgör Om Du Ska Försöka Igen: Mjuka vs. Hårda Avslag

error_code berättar för dig om det är värt att försöka med samma betalningsmetod igen.

Avslagstyp	Vad det betyder	Vad du ska göra
Mjukt avslag	Tillfälligt eller korrigerbart (till exempel `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Att försöka igen — efter en fördröjning, eller när kunden rättar till sin inmatning — kan lyckas.
Hårt avslag	Terminal (till exempel `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	Försök inte med samma kort igen. Be kunden att välja en annan betalningsmetod.

Referensen Transaktionsfel listar avslagstypen och rekommenderad åtgärd för varje error_code.

Hantera Fel Vid Checkout vs. Vid Förnyelse

Hur du återställer beror på om kunden är närvarande.

At checkout (customer present)
On subscription renewal (customer not present)

Kunden handlar aktivt. Visa ett tydligt meddelande och låt dem försöka igen direkt eller använda ett annat kort.

requires_payment_method — kunden har aldrig angett en betalningsmetod: de angav inte kortuppgifter, eller blev ombedda att göra det och gjorde inget. Detta är vanligtvis en checkout avbrott, inte ett avslag — återengagera kunden för att slutföra betalningen (se Återhämtning av Övergivna Varukorgar).
requires_customer_action — ytterligare autentisering (såsom 3DS) behövs; be kunden slutföra den. Se 3D Secure hantering.

Kunden är inte närvarande, så du kan inte uppmana dem i realtid. När en förnyelse misslyckas går abonnemanget till on_hold och subscription.on_hold utlöses.

Mjuka avslag försöks automatiskt igen av Abonnemangsbetalningsförsök.
Hårda avslag (och uttömda försök) återhämtas bäst med Abonnemang Dunning, som skickar e-post till kunden för att uppdatera sin betalningsmetod.

Se Abonnemangsintegrationsguiden för hela flödet från på paus → reaktivera.

Försöka med en Misslyckad Betalning Igen

Abonnemang: Aktivera Abonnemangsbetalningsförsök för att återhämta sig från mjuka avslag utan integrationsarbete. Du kan också utlösa återhämtning genom att kunden uppdaterar sin betalningsmetod via API för Uppdatering av Betalningsmetod, som debiterar alla utestående avgifter.
Engångsbetalningar: Skicka om checkout eller payment_link så att kunden kan försöka igen med en annan metod. Det finns ingen automatisk återförsök för engångsbetalningar.

Försök inte med hårda avslag mot samma kort igen. Kortnätverk kan flagga upprepade avslag som missbruk, vilket försämrar din auktorisationsfrekvens.

Visa Fel För Kunder På Ett Säkert Sätt

Visa kunderna ett vänligt meddelande — aldrig den råa error_code.

Customer-facing messaging

const CUSTOMER_MESSAGES = {
  INSUFFICIENT_FUNDS: "Your card has insufficient funds. Please use another card.",
  EXPIRED_CARD: "Your card has expired. Please use a card with a valid expiry date.",
  INCORRECT_CVC: "The security code (CVC) is incorrect. Please re-enter it.",
};

function customerMessage(errorCode) {
  // Sensitive declines must never reveal the real reason
  const SENSITIVE = ["STOLEN_CARD", "LOST_CARD", "PICKUP_CARD", "FRAUDULENT"];
  if (SENSITIVE.includes(errorCode)) {
    return "Your card was declined. Please contact your bank or use another card.";
  }
  return CUSTOMER_MESSAGES[errorCode] ?? "Your payment could not be processed. Please try another card.";
}

Avslöja aldrig den verkliga anledningen till STOLEN_CARD, LOST_CARD, PICKUP_CARD eller FRAUDULENT. Att visa dessa kan tipsa en bedräglig aktör. Visa ett generiskt meddelande om avslag och logga bara det specifika error_code internt.

Relaterade

Transaction Failures

Varje avvisningskod, dess typ och den rekommenderade åtgärden.

Error Codes

API- och affärslogiska fel som inte är kortavslag.

Subscription Payment Retries

Automatisk återhämtning av mjuka avslag vid abonnemangsförnyelser.

Subscription Dunning

E-postsekvenser som återhämtar hårda avslag.

Payment Webhooks

Fullständigt payload-schema för betalningshändelser.

Testing Failures

Testkort som simulerar avslag och förnyelsemisslyckanden.

Integration Guides

Billing Deconstructions

Cookbooks

Hur Dodo Payments Rapporterar Ett Fel

Webhook för `payment.failed`

Avgör Om Du Ska Försöka Igen: Mjuka vs. Hårda Avslag

Hantera Fel Vid Checkout vs. Vid Förnyelse

Försöka med en Misslyckad Betalning Igen

Visa Fel För Kunder På Ett Säkert Sätt

Relaterade

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Hur Dodo Payments Rapporterar Ett Fel

​Webhook för payment.failed

​Avgör Om Du Ska Försöka Igen: Mjuka vs. Hårda Avslag

​Hantera Fel Vid Checkout vs. Vid Förnyelse

​Försöka med en Misslyckad Betalning Igen

​Visa Fel För Kunder På Ett Säkert Sätt

​Relaterade

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Hur Dodo Payments Rapporterar Ett Fel

Webhook för `payment.failed`

Avgör Om Du Ska Försöka Igen: Mjuka vs. Hårda Avslag

Hantera Fel Vid Checkout vs. Vid Förnyelse

Försöka med en Misslyckad Betalning Igen

Visa Fel För Kunder På Ett Säkert Sätt

Relaterade