Hantera Betalningsmisslyckanden

När en betalning misslyckas tillhandahåller Dodo Payments en standardiserad error_code och en lättförståelig error_message. Den här guiden visar hur du läser dessa fält, avgör om du ska försöka igen och återställer betalningen på ett säkert sätt.

Hur Dodo Payments Rapporterar Ett Fel

Varje misslyckad betalning innehåller dessa fält i betalningsobjektet:

Fält	Typ	Beskrivning
`status`	string	`failed` för en misslyckad betalning. Andra icke-slutförda statusar: `cancelled`, `requires_customer_action`, `requires_payment_method`.
`error_code`	string \| null	Standardiserad felorsak, till exempel `INSUFFICIENT_FUNDS` eller `PROCESSING_ERROR`. Se Transaction Failures för hela listan.
`error_message`	string \| null	Förklaring för handlaren med rekommenderad åtgärd. Ska inte visas för kunder.
`retry_attempt`	integer	`0` för den ursprungliga debiteringen. `1` eller högre för schemalagda försök igen vid prenumerationsförnyelser.

error_code och error_message är null tills en betalning misslyckas. Kontrollera alltid status först.

error_message är avsett för handlare och kan avslöja bedrägerirelaterade orsaker. Visa det aldrig för kunder. Mappa i stället error_code till kundanpassad text (se Visa fel för kunder på ett säkert sätt).

Webhooken `payment.failed`

Webhooken payment.failed är det mest tillförlitliga sättet att upptäcka ett fel. Händelsen innehåller 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 baserat på 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 payment. If Payment Retries is on, Dodo retries failed renewals.
      // On-demand charges are never retried automatically: handle those yourself.
      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 payment. If Payment Retries is on, Dodo retries failed renewals.
            # On-demand charges are never retried automatically: handle those yourself.
            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 nekande	Exempel	Åtgärd
Soft decline	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	Försök igen efter en fördröjning eller när kunden har korrigerat sina uppgifter.
Hard decline	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	Försök inte igen med samma kort. Be kunden använda en annan betalningsmetod.

Se Transaction Failures för hela listan över typer av nekanden och rekommenderade åtgärder.

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 håller aktivt på att genomföra köpet. Visa ett tydligt meddelande och låt kunden försöka igen eller använda ett annat kort.

requires_payment_method — kunden angav aldrig någon betalningsmetod. Detta är vanligtvis ett avbrutet checkout-flöde, inte ett nekande. Kontakta kunden igen så att betalningen kan slutföras (se Återställning av övergivna kundvagnar).
requires_customer_action — ytterligare autentisering (till exempel 3DS) krävs. Be kunden slutföra den. Se 3D Secure.

Kunden är inte närvarande. När en förnyelse misslyckas flyttas prenumerationen till on_hold och subscription.on_hold aktiveras. Om ditt företag har en respitperiod flyttas den först till past_due (subscription.past_due) och åtkomsten behålls tills respitperioden löper ut.

Soft declines försöks automatiskt igen om du aktiverar Subscription Payment Retries (inaktiverat som standard). Försöken gäller endast schemalagda förnyelser, inte on-demand-debiteringar.
Hard declines (och uttömda försök) vid schemalagda förnyelser återställs med Subscription Dunning, som skickar e-post till kunden för att uppdatera betalningsmetoden. För misslyckade on-demand-debiteringar, se On-Demand Subscriptions.

Se Subscription Integration Guide för hela flödet från väntande prenumeration → återaktivering.

Försöka igen med en misslyckad betalning

Prenumerationer: Aktivera Subscription Payment Retries för att automatiskt återställa soft declines. Om du vill försöka igen omedelbart i stället för att vänta på schemat kan du använda Manual Payment Retry från dashboarden eller API:t. Du kan också utlösa återställning genom att låta kunden uppdatera sin betalningsmetod via Update Payment Method API, vilket debiterar eventuella utestående belopp. Engångsbetalningar: Skicka checkout-länken eller payment_link igen så att kunden kan försöka på nytt med en annan metod. Det finns inget automatiskt försök igen för engångsbetalningar.

Försök inte igen med hard declines mot samma kort. Kortnätverk flaggar upprepade nekanden 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 den råa error_code eller den handlarinriktade error_message.

På ytor som hanteras av Dodo Payments (checkout, Customer Portal, dunning-e-post) görs denna mappning redan åt dig, inklusive återgång till ett generiskt meddelande för bedrägerirelaterade nekanden. Du behöver bara mappningen nedan när du visar fel 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 för STOLEN_CARD, LOST_CARD, PICKUP_CARD eller FRAUDULENT. Om du visar dessa kan en bedragare få information som hjälper dem. Visa ett generiskt meddelande om nekad betalning och logga endast den specifika error_code internt.

Relaterat

Transaction Failures

Varje nekandekod, dess typ och rekommenderade åtgärd.

Error Codes

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

Subscription Payment Retries

Automatisk återställning av soft declines vid prenumerationsförnyelser.

Subscription Dunning

E-postsekvenser som återställer hard declines.

Payment Webhooks

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

Testing Failures

Testkort som simulerar nekanden 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