transaction.payment_failed

Occurs when a payment fails for a transaction. The payments array is updated with details of the payment attempt.

Typically happens for automatically-collected transactions, but may occur for manually-collected transactions (invoices) where a customer pays using Paddle Checkout and their payment is declined.

If related to a subscription renewal:

The transaction status changes to past_due and transaction.past_due occurs.
The related subscription status changes to past_due and subscription.past_due occurs.

Manually-collected transactions are marked as past_due when the payment terms have elapsed.

event_idstring

Unique Paddle ID for this event, prefixed with evt_.

event_typestring

Type of event sent by Paddle, in the format entity.event_type.

occurred_atstring<date-time>

RFC 3339 datetime string of when this event occurred.

dataobject

New or changed entity.

idstring

Unique Paddle ID for this transaction entity, prefixed with txn_.

statusstring

Status of this transaction. You may set a transaction to billed or canceled, other statuses are set automatically by Paddle. Automatically-collected transactions may return completed if payment is captured successfully, or past_due if payment failed.

customer_idstring or null

Paddle ID of the customer that this transaction is for, prefixed with ctm_.

address_idstring or null

Paddle ID of the address that this transaction is for, prefixed with add_.

business_idstring or null

Paddle ID of the business that this transaction is for, prefixed with biz_.

custom_dataobject or null

Your own structured key-value data.

currency_codestring

Supported three-letter ISO 4217 currency code. Must be USD, EUR, or GBP if collection_mode is manual.

originstring

Describes how this transaction was created.

subscription_idstring or null

Paddle ID of the subscription that this transaction is for, prefixed with sub_.

invoice_idstring or null

Paddle ID of the invoice that this transaction is related to, prefixed with inv_. Used for compatibility with the Paddle Invoice API, which is now deprecated. This field is scheduled to be removed in the next version of the Paddle API.

invoice_numberstring or null

Invoice number for this transaction. Automatically generated by Paddle when you mark a transaction as billed where collection_mode is manual.

collection_modestring

How payment is collected for this transaction. automatic for checkout, manual for invoices.

discount_idstring or null

Paddle ID of the discount applied to this transaction, prefixed with dsc_.

billing_detailsobject or null

Details for invoicing. Required if collection_mode is manual.

billing_periodobject or null

Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for.

itemsarray[object]

List of items on this transaction. For calculated totals, use details.line_items.

detailsobject

Calculated totals for a transaction, including proration, discounts, tax, and currency conversion. Considered the source of truth for totals on a transaction.

paymentsarray[object]

List of payment attempts for this transaction, including successful payments. Sorted by created_at in descending order, so most recent attempts are returned first.

checkoutobject or null

Paddle Checkout details for this transaction. Returned for automatically-collected transactions and where billing_details.enable_checkout is true for manually-collected transactions; null otherwise.

created_atstring<date-time>

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring<date-time>

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

billed_atstring<date-time> or null

RFC 3339 datetime string of when this transaction was marked as billed. null for transactions that are not billed or completed. Set automatically by Paddle.

revised_atstring<date-time> or null

RFC 3339 datetime string of when a transaction was revised. Revisions describe an update to customer information for a billed or completed transaction. null if not revised. Set automatically by Paddle.

notification_idstring

Unique Paddle ID for this notification, prefixed with ntf_.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "event_id": "evt_01hv8wx4vr9w6zsv6xss0b8az9",
3  "event_type": "transaction.payment_failed",
4  "occurred_at": "2024-04-12T10:16:00.120972Z",
5  "notification_id": "ntf_01hv8wx4ywcj8pptnpeq1rrvzm",
6  "data": {
7    "id": "txn_01hv8wptq8987qeep44cyrewp9",
8    "items": [
9      {
10        "price": {
11          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
12          "name": "Monthly (per seat)",
13          "type": "standard",
14          "status": "active",
15          "quantity": {
16            "maximum": 999,
17            "minimum": 1
18          },
19          "tax_mode": "account_setting",
20          "created_at": "2023-02-23T13:55:22.538367Z",