Webhook: payment.failed

The payment.failed event is sent when a payment fails.

Example

{
  "id": "422e0801-2354-4b46-ae59-49cfd2341a29",
  "type": "payment.failed",
  "version": 1,
  "isSandbox": true,
  "data": {
    "payment": {
      "id": "28ccdea9-2a3d-4f81-9577-ac8f21d6f9e8",
      "date": "2025-08-29T16:00:40.454Z",
      "method": "credit_card",
      "status": "INVALID_PAYMENT_METHOD",
      "code": "declined",
      "message": "Declined.",
      "amount": 499,
      "currency": "USD"
    },
    "checkout": {
      "id": "80d480ca-5bc3-45eb-b70c-f37ad241024c",
      "accountId": "@neon-tester",
      "externalReferenceId": "external_reference_id",
      "externalMetadata": {
        "foo": "bar"
      }
    }
  }
}

checkout or invoice

data contains either a checkout object (for a one-time purchase, as above) or an invoice object (for a subscription invoice payment). An invoice contains id and accountId:

"invoice": {
  "id": "5b9e0c1d-7f3a-4e2b-8c6d-1a2b3c4d5e6f",
  "accountId": "@neon-tester"
}

method

The payment method used, if available. Example: credit_card.

status

Either INVALID_PAYMENT_METHOD (the payment was declined) or FAILED (the payment failed for another reason).

code

The type of failure. Possible codes are declined, insufficient_funds, expired_card, incorrect_cvc, invalid_cvc, incorrect_number, invalid_number, incorrect_zip, invalid_exp_month, invalid_exp_year, invalid_name, unexpected_country, session_expired, and failed.

message

A human-readable description of code.

amount and currency

The amount of the failed payment, expressed as 100x the currency's base unit (see Currencies), and its ISO 4217 currency code.