> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt). # checkout.payment.failed Emitted when a payment fails for a checkout. --- Use `checkout.payment.failed` to run actions when a payment fails for a checkout. It follows [`checkout.payment.initiated`](https://developer.paddle.com/paddle-js/events/checkout-payment-initiated.md) when the payment attempt doesn't succeed. ## Schema ```yaml title: Checkout event type: object properties: name: type: string description: Name of this event, in the format `entity.event_type`. data: type: object description: Event payload. properties: id: type: string description: Unique Paddle ID for this checkout, prefixed with `che_`. transaction_id: type: string description: Unique Paddle ID for the transaction related to this checkout, prefixed with `txn_`. status: type: string description: Status of this checkout. enum: - draft - ready - billed - paid - completed - canceled - past_due x-enum-descriptions: draft: description: >- Checkout missing required fields to process a payment. Typically the first stage of a checkout before customer details are captured. ready: description: Checkout transaction has all of the required fields to process a payment. billed: description: >- Related transaction for this checkout is `billed`. Billed transactions get an invoice number and are considered a legal record. They cannot be changed. Typically used as part of an invoice workflow. May be present at checkout when a customer is paying an invoice using Paddle Checkout link. paid: description: >- Related transaction for this checkout is fully paid, but has not yet been processed internally. Not typically encountered at checkout. completed: description: Checkout is completed. Typically means payment collected successfully. canceled: description: Related transaction for this checkout is `canceled`. Not typically encountered at checkout. past_due: description: >- Typically means the related transaction is `past_due`. May be present at checkout when updating payment details to collect for an overdue payment. custom_data: type: - object - "null" description: Key-value pairs of custom data. Must be valid JSON and contain at least one key. currency_code: type: string description: Supported three-letter ISO 4217 currency code for this checkout. customer: type: object description: Information about the customer on this checkout. properties: id: type: - string - "null" description: Unique Paddle ID for the customer related to this checkout, prefixed with `ctm_`. email: type: - string - "null" description: Email address for the customer. address: type: - object - "null" description: Information about the customer billing address on this checkout. properties: id: type: string description: Unique Paddle ID for the address related to this checkout, prefixed with `add_`. country_code: type: string description: Two-letter ISO 3166 country code. postal_code: type: string description: ZIP or postal code of the customer billing address. Required for countries with postal codes. first_line: type: string description: First line of the customer billing address. city: type: string description: City of the customer billing address. region: type: string description: State, county, or region of the customer billing address. business: type: - object - "null" description: Information about the customer business on this checkout. properties: id: type: string description: Unique Paddle ID for the business related to this checkout, prefixed with `biz_`. name: type: string description: Name of this business. tax_identifier: type: string description: Tax or VAT Number for this business. items: type: array description: Items to bill for. items: type: object properties: price_id: type: string description: Unique Paddle ID for a price to bill for, prefixed with `pri_`. price_name: type: - string - "null" description: >- Name of this price, shown to customers at checkout. Typically describes how often the related product bills. product: type: object description: Related product object for this price. properties: id: type: string description: Unique Paddle ID for the product related to the price on this checkout, prefixed with `pro_`. name: type: string description: Name of this product. description: type: - string - "null" description: Short description for this product. Included on some customer documents, like receipts. image_url: type: - string - "null" description: Image for this product. Included in the overlay checkout and on some receipts. billing_cycle: type: - object - "null" description: How often this items bills. properties: interval: type: string description: Period of recurrence. enum: - day - week - month - year x-enum-descriptions: day: description: Billed daily. week: description: Billed weekly. month: description: Billed monthly. year: description: Billed annually. frequency: type: integer description: Frequency of recurrence in the period. trial_period: type: - object - "null" description: How long the trial period is for this item. properties: interval: type: string description: Period. enum: - day - week - month - year x-enum-descriptions: day: description: Day week: description: Week month: description: Month year: description: Year frequency: type: number description: Frequency in the period. quantity: type: integer description: Quantity to bill for. totals: type: object description: Financial breakdown of the total for this checkout item, calculated by Paddle. properties: subtotal: type: number description: Amount multiplied by quantity. discount: type: number description: Total discount applied to this checkout. tax: type: number description: Total tax on the subtotal. total: type: number description: Subtotal plus tax. credit: type: number description: Total credit applied. balance: type: number description: Total due after credits. recurring_totals: type: object description: >- Financial breakdown of the recurring total for this checkout item, calculated by Paddle. Only included for recurring items. properties: subtotal: type: number description: Amount multiplied by quantity. discount: type: number description: Total discount applied to this checkout. tax: type: number description: Total tax on the subtotal. total: type: number description: Subtotal plus tax. credit: type: number description: Total credit applied. balance: type: number description: Total due after credits. totals: type: object description: Financial breakdown of the total for this checkout, calculated by Paddle. properties: subtotal: type: number description: Amount multiplied by quantity. discount: type: number description: Total discount applied to this checkout. tax: type: number description: Total tax on the subtotal. total: type: number description: Subtotal plus tax. credit: type: number description: Total credit applied. balance: type: number description: Total due after credits. recurring_totals: type: object description: >- Financial breakdown of the recurring total for this checkout, calculated by Paddle. Only included where there are recurring items. properties: subtotal: type: number description: Amount multiplied by quantity. discount: type: number description: Total discount applied to this checkout. tax: type: number description: Total tax on the subtotal. total: type: number description: Subtotal plus tax. credit: type: number description: Total credit applied. balance: type: number description: Total due after credits. settings: type: object description: Checkout settings. properties: display_mode: type: string description: Display mode for the checkout. enum: - inline - wide-overlay x-enum-descriptions: inline: description: >- Inline checkout mode. Checkout embedded as a frame in the page. Requires `settings.frameTarget` in `Paddle.Initialize()` wide-overlay: description: Overlay checkout mode. Checkout opens in an overlay. theme: type: string description: Theme for the checkout. enum: - dark - light x-enum-descriptions: dark: description: Dark-themed checkout. light: description: Light-themed checkout. variant: type: string description: Checkout experience presented to customers. enum: - one-page - multi-page x-enum-descriptions: one-page: description: One-page checkout experience. Customer information and payment details collected on the same page. multi-page: description: Multi-page checkout experience. Customer information and payment details collected on separate pages. discount: type: - object - "null" description: Information about the discount applied to this checkout. Only included when a discount is applied. properties: id: type: string description: Unique Paddle ID for the discount applied to this checkout, prefixed with `dsc_`. code: type: - string - "null" description: Code for this discount. upsell: type: - object - "null" description: Context about the rendered upsell checkout. `null` if an upsell flow was not rendered. properties: transaction_id: type: string description: Unique Paddle ID for the previously completed transaction that this upsell follows, prefixed with `txn_`. show_skip_button: type: boolean description: Whether the "No thanks" skip button is shown at checkout. same_session: type: boolean description: >- Whether the checkout was created within 5 minutes of the previously completed transaction. Determines the checkout experience presented to the customer. payment: type: object description: Information about the payment details used on this checkout. properties: method_details: type: - object - "null" description: Information about the payment method used for a payment attempt. properties: type: type: string description: Type of payment method used. enum: - alipay - apple-pay - bancontact - blik - card - google-pay - ideal - kakao-pay - mb-way - naver-pay - none - payco - paypal - pix - samsung-pay - south-korea-local-card - unknown - upi x-enum-descriptions: alipay: description: Alipay, popular in China. apple-pay: description: Apple Pay on a supported Apple device. bancontact: description: Bancontact, popular in Belgium. blik: description: BLIK, a popular payment method in Poland. card: description: Credit or debit card. google-pay: description: Google Pay on a supported Android device, Chromebook, or Google Chrome browser. ideal: description: iDEAL, popular in the Netherlands. kakao-pay: description: Kakao Pay, a popular payment method in Korea. mb-way: description: MB WAY, a popular payment method in Portugal. naver-pay: description: Naver Pay, a popular payment method in Korea. none: description: No payment method, or payment method not yet known. payco: description: Payco, a popular payment method in Korea. paypal: description: PayPal. pix: description: Pix, popular in Brazil. Available in early access. samsung-pay: description: Samsung Pay, a popular payment method in Korea. south-korea-local-card: description: Korean local credit or debit card. unknown: description: Payment method not known. upi: description: Unified Payments Interface (UPI), popular in India. Available in early access. card: type: - object - "null" description: Information about the card used for this checkout. properties: type: type: string description: Type of credit or debit card used to pay. enum: - american_express - diners_club - discover - jcb - maestro - mastercard - union_pay - visa - unknown x-enum-descriptions: american_express: description: American Express diners_club: description: Diners Club discover: description: Discover Card jcb: description: JCB Card maestro: description: Maestro (debit card) mastercard: description: Mastercard union_pay: description: UnionPay, popular in China visa: description: Visa unknown: description: Card type unknown last4: type: string description: Last four digits of the card number used. expiry_month: type: integer description: Number of the month of the year that this card expires in the format `MM`. expiry_year: type: integer description: Year that this card expires in the format `YYYY`. ``` ## Example ```json { "name": "checkout.payment.failed", "data": { "id": "che_01k9ppwfg7nkr1s47pntfe7x3s", "transaction_id": "txn_01k9ppwf885xk7azx0xgnp6kp1", "status": "ready", "custom_data": null, "currency_code": "USD", "customer": { "id": "ctm_01k9pq1gzbza1n86n4jef18sbp", "email": "sam@example.com", "address": { "postal_code": "10021", "region": "", "country_code": "US", "id": "add_01k9pq6e149abgqb42rsebvvfw", "city": "", "first_line": "" }, "business": null }, "items": [ { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "price_name": "Monthly (per seat)", "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "AeroEdit Pro", "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png" }, "billing_cycle": { "interval": "month", "frequency": 1 }, "trial_period": null, "quantity": 1, "totals": { "subtotal": 30, "tax": 2.66, "total": 32.66, "discount": 0, "balance": 32.66, "credit": 0 }, "recurring_totals": { "subtotal": 30, "tax": 2.66, "discount": 0, "total": 32.66 } } ], "totals": { "subtotal": 30, "tax": 2.66, "total": 32.66, "discount": 0, "credit": 0, "balance": 32.66 }, "payment": { "method_details": { "type": "card" } }, "settings": { "display_mode": "wide-overlay", "theme": "light", "variant": "one-page" }, "recurring_totals": { "subtotal": 30, "tax": 2.66, "discount": 0, "total": 32.66, "balance": 32.66, "credit": 0 }, "upsell": { "transaction_id": "txn_01gzdn07vccpnwp1gwwnn2hy8r", "show_skip_button": true, "same_session": true } } } ```