Transactions
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 24 hours after their due date, if no payment has been received.
postWebhooktransaction.payment_failed
Headers
paddle_signaturestring required
Signature for this request. Use to verify that webhooks come from Paddle.
Payload
Example payload
{
"event_id": "evt_01gks14ge726w50ch2tmaw2a1x",
"occurred_at": "2024-10-12T07:20:50.52Z",
"notification_id": "ntf_01ghbkd0frb9k95cnhwd1bxpvk",
"data": {
"id": "txn_01h04vsbhqc62t8hmd4z3b578c",
"customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
"address_id": "add_01gm302t81w94gyjpjpqypkzkf",
"business_id": "biz_01grrebrzaee2qj2fqqhmcyzaj",
"custom_data": {
"customer_reference_id": "abcd1234"
},
"subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
"invoice_id": "inv_01ghbk4xjn4qdsmstcwzgcgg35",
"invoice_number": "123-45678",
"discount_id": "dsc_01gv5kpg05xp104ek2fmgjwttf",
"billing_period": {
"starts_at": "2024-10-12T07:20:50.52Z",
"ends_at": "2024-10-12T07:20:50.52Z"
},
"items": [
{
"price": {
"id": "pri_01gsz8z1q1n00f12qt82y31smh",
"product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
"quantity": {
"minimum": 1,
"maximum": 100
},
"custom_data": {
"customer_reference_id": "abcd1234"
},
"import_meta": {
"external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
"imported_from": "paddle_classic"
},
"created_at": "2024-10-12T07:20:50.52Z",
"updated_at": "2024-10-13T07:20:50.52Z"
},
"proration": {
"billing_period": {
"starts_at": "2024-10-12T07:20:50.52Z",
"ends_at": "2024-10-12T07:20:50.52Z"
}
}
}
],
"details": {
"tax_rates_used": [
{
"tax_rate": "0.2",
"totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500"
}
}
],
"totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500",
"credit": "0",
"credit_to_balance": "0",
"balance": "16500",
"grand_total": "16500",
"grand_total_tax": "83",
"fee": "825",
"earnings": "15675"
},
"adjusted_totals": {
"subtotal": "15000",
"tax": "1500",
"total": "16500",
"grand_total": "16500",
"grand_total_tax": "83",
"fee": "825",
"retained_fee": "300",
"earnings": "15675"
},
"payout_totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500",
"credit": "0",
"credit_to_balance": "0",
"balance": "16500",
"grand_total": "16500",
"grand_total_tax": "83",
"fee": "825",
"earnings": "15675",
"exchange_rate": "1.0513135",
"fee_rate": "0.05"
},
"adjusted_payout_totals": {
"subtotal": "15000",
"tax": "1500",
"total": "16500",
"fee": "825",
"retained_fee": "300",
"chargeback_fee": {
"amount": "1680",
"original": {
"amount": "1500",
"currency_code": "USD"
}
},
"earnings": "15675",
"exchange_rate": "1.0513135"
},
"line_items": [
{
"price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
"proration": {
"billing_period": {
"starts_at": "2024-10-12T07:20:50.52Z",
"ends_at": "2024-10-12T07:20:50.52Z"
}
},
"tax_rate": "0.2",
"unit_totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500"
},
"totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500"
},
"product": {
"id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
"custom_data": {
"customer_reference_id": "abcd1234"
},
"import_meta": {
"external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
"imported_from": "paddle_classic"
},
"created_at": "2024-10-12T07:20:50.52Z",
"updated_at": "2024-10-13T07:20:50.52Z"
},
"id": "txnitm_01gm302t81w94gyjpjpqypkzkf"
}
]
},
"payments": [
{
"payment_attempt_id": "497f776b-851d-4ebf-89ab-8ba0f75d2d6a",
"stored_payment_method_id": "7636e781-3969-49f4-9c77-8226232e28a6",
"payment_method_id": "paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1",
"amount": "1050",
"method_details": {
"south_korea_local_card": {
"last4": "4242"
},
"card": {
"last4": "4242",
"expiry_month": 12,
"expiry_year": 2028
},
"paypal": {
"email": "john.doe@example.com"
}
},
"created_at": "2024-10-12T07:20:50.52Z",
"captured_at": "2024-10-12T07:20:50.52Z"
}
],
"created_at": "2024-10-12T07:20:50.52Z",
"updated_at": "2024-10-13T07:20:50.52Z",
"billed_at": "2024-10-12T07:20:50.52Z",
"revised_at": "2024-10-12T07:20:50.52Z"
}
}Response
Respond with an HTTP 200 status code within 5 seconds to let Paddle know that you successfully received the message.
If your server sends another kind of status code or doesn't respond, Paddle automatically retries using an exponential backoff schedule.
Changes
Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.