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:

Field	Type	Description
`status`	string	`failed` för en misslyckad betalning. Andra tillstånd som inte innebär framgång är `cancelled`, `requires_customer_action` och `requires_payment_method`.
`error_code`	string \| null	Den standardiserade orsaken till misslyckandet, till exempel `INSUFFICIENT_FUNDS` eller `PROCESSING_ERROR`. Se referensen Transaction Failures för hela listan.
`error_message`	string \| null	En lättförståelig förklaring av misslyckandet, skriven för dig och inte för kunden. För ett standardiserat `error_code` består detta av en rubrik plus den rekommenderade åtgärden, inte den råa texten från betalningsprocessorn.
`retry_attempt`	integer	`0` för den ursprungliga debiteringen. `1` eller högre identifierar ett schemalagt nytt försök vid förnyelse av en prenumeration.

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.

error_message från merchant API är text för handlaren. Den kan ange den verkliga orsaken till ett avslag, inklusive bedrägerirelaterade orsaker, så återge den aldrig direkt för en kund. Mappa i stället error_code till din egen kundsäkra formulering, enligt exemplet i Visa fel för kunder på ett säkert sätt.

Webhooken `payment.failed`

Det mest tillförlitliga sättet att upptäcka ett misslyckande är webhooken payment.failed. Händelsen kapslar in hela 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 handler 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 hela konfigurationen, inklusive signaturverifiering och idempotens.

Avgör om du ska försöka igen: mjuka kontra hårda avslag

error_code visar om det är meningsfullt att försöka igen med samma betalningsmetod.

Typ av avslag	Vad det betyder	Vad du ska göra
Mjukt avslag	Tillfälligt eller möjligt att korrigera (till exempel `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Ett nytt försök — efter en fördröjning eller när kunden har korrigerat sina uppgifter — kan lyckas.
Hårt avslag	Slutgiltigt (till exempel `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	Försök inte igen med samma kort. Be kunden använda en annan betalningsmetod.

Referensen Transaction Failures listar typen av avslag och den rekommenderade åtgärden för varje error_code.

Hantera misslyckanden i checkout jämfört med vid förnyelse

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

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

Kunden genomför aktivt checkout. Visa ett tydligt meddelande och låt kunden försöka igen direkt eller använda ett annat kort.

requires_payment_method — kunden angav aldrig någon betalningsmetod: hen angav inte kortuppgifter eller blev ombedd att ange dem men vidtog ingen åtgärd. Detta är vanligtvis ett avbrutet köp, inte ett avslag — återengagera kunden så att hen slutför betalningen (se Återställning av övergivna kundvagnar).
requires_customer_action — ytterligare autentisering (till exempel 3DS) krävs; be kunden slutföra den. Se Hantering av 3D Secure.

Kunden är inte närvarande, så du kan inte be hen agera i realtid. När en förnyelse misslyckas flyttas prenumerationen till on_hold och subscription.on_hold utlöses.

Mjuka avslag försöks automatiskt igen av Subscription Payment Retries.
Hårda avslag (och uttömda försök) återställs bäst med Subscription Dunning, som skickar ett e-postmeddelande till kunden med en uppmaning att uppdatera betalningsmetoden.

Se Subscription Integration Guide för hela flödet från pausad → återaktiverad prenumeration.

Försöka igen med en misslyckad betalning

Prenumerationer: Aktivera Subscription Payment Retries för att återställa mjuka avslag utan integrationsarbete. Du kan också utlösa återställning genom att låta kunden uppdatera sin betalningsmetod via Update Payment Method API, som debiterar eventuella utestående belopp.
Engångsbetalningar: Skicka checkout eller payment_link igen så att kunden kan försöka med en annan metod. Det finns inget automatiskt nytt försök för engångsbetalningar.

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

Visa fel för kunder på ett säkert sätt

Visa kunderna ett vänligt meddelande — aldrig det råa error_code och aldrig det error_message som är avsett för handlaren.

På ytor som styrs av Dodo Payments — checkout, Customer Portal och kravmejl — är denna mappning redan gjord åt dig, inklusive återgången till ett generiskt meddelande för bedrägerirelaterade avslag. Du behöver bara mappningen nedan när du återger misslyckanden i din egen produkt.

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 orsaken till STOLEN_CARD, LOST_CARD, PICKUP_CARD eller FRAUDULENT. Om du visar dessa kan du ge en bedragare information. Visa ett generiskt avslagsmeddelande och logga endast det specifika error_code internt.

Relaterat

Transaction Failures

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

Error Codes

API- och affärslogikfel som inte är kortavslag.

Subscription Payment Retries

Automatisk återställning av mjuka avslag vid förnyelse av prenumerationer.

Subscription Dunning

E-postsekvenser som återställer hårda avslag.

Payment Webhooks

Fullständigt schema för nyttolasten för betalningshändelser.

Testing Failures

Testkort som simulerar avslag och misslyckade förnyelser.

Integration Guides

Billing Deconstructions

Cookbooks

Hur Dodo Payments Rapporterar Ett Fel

Webhooken `payment.failed`

Avgör om du ska försöka igen: mjuka kontra hårda avslag

Hantera misslyckanden i checkout jämfört med vid förnyelse

Försöka igen med en misslyckad betalning

Visa fel för kunder på ett säkert sätt

Relaterat

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Hur Dodo Payments Rapporterar Ett Fel

​Webhooken payment.failed

​Avgör om du ska försöka igen: mjuka kontra hårda avslag

​Hantera misslyckanden i checkout jämfört med vid förnyelse

​Försöka igen med en misslyckad betalning

​Visa fel för kunder på ett säkert sätt

​Relaterat

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Hur Dodo Payments Rapporterar Ett Fel

Webhooken `payment.failed`

Avgör om du ska försöka igen: mjuka kontra hårda avslag

Hantera misslyckanden i checkout jämfört med vid förnyelse

Försöka igen med en misslyckad betalning

Visa fel för kunder på ett säkert sätt

Relaterat