What's new?
We added a new payment_method_id field that's returned for payment attempts against a transaction. It returns a Paddle ID.
payment_method_id string
Unique Paddle ID for this payment method entity, prefixed with paymtd_
The stored_payment_method_id field is now deprecated. We may remove it in future versions of the API.
How it works
Transactions return an array of payments, which contains an object for each attempt to collect for the amount due for a transaction.
Each payment attempt includes a stored_payment_method_id field. This is a UUID that Paddle generates for the payment method used. When working with automatically-collected subscriptions, Paddle saves the payment method used to collect. Future transactions created for a subscription that are paid using the same payment method have the same stored_payment_method_id value.
We introduced a new payment_method_id field that supersedes the stored_payment_method_id field. The payment_method_id field works in the same way as the stored_payment_method_id field, but returns a Paddle ID that starts with paymtd_ rather than a UUID.
We made this change to make it easier to work with payment methods in Paddle Billing. Paddle IDs are easily identifiable, lexicographically sortable, and used throughout the Paddle Billing platform.
Example
This is a transaction entity, returned using the get a transaction operation. The stored_payment_method_id and payment_method_id fields are highlighted.
{ "data": { "id": "txn_01hmrd3w1n9dqvsgccdca02gvg", "status": "completed", "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a", "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5", "business_id": null, "custom_data": null, "origin": "subscription_recurring", "collection_mode": "automatic", "subscription_id": "sub_01h3h3a9sfpr5syq38tq0sd4sp", "invoice_id": "inv_01hmrd6rb6gm16d2aek7mrnsbj", "invoice_number": "325-10397", "billing_details": null, "billing_period": { "starts_at": "2024-04-22T08:25:12.565118Z", "ends_at": "2024-05-22T08:25:12.565118Z" }, "currency_code": "USD", "discount_id": null, "created_at": "2024-01-22T10:58:01.869326Z", "updated_at": "2024-01-22T10:59:45.631048Z", "billed_at": "2024-01-22T10:58:01.397078Z", "items": [ { "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "description": "Monthly (per seat)", "type": "standard", "name": null, "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "billing_cycle": { "interval": "month", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "3000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "quantity": { "minimum": 10, "maximum": 999 }, "status": "active" }, "quantity": 30, "proration": { "rate": "1", "billing_period": { "starts_at": "2024-04-22T08:25:12.565118Z", "ends_at": "2024-05-22T08:25:12.565118Z" } } }, { "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "description": "Monthly (recurring addon)", "type": "standard", "name": null, "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "billing_cycle": { "interval": "month", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "10000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "quantity": { "minimum": 1, "maximum": 100 }, "status": "active" }, "quantity": 1, "proration": { "rate": "1", "billing_period": { "starts_at": "2024-04-22T08:25:12.565118Z", "ends_at": "2024-05-22T08:25:12.565118Z" } } } ], "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "100000", "discount": "0", "tax": "8874", "total": "108874" } } ], "totals": { "subtotal": "100000", "tax": "8874", "discount": "0", "total": "108874", "grand_total": "108874", "fee": "5494", "credit": "0", "credit_to_balance": "0", "balance": "0", "earnings": "94506", "currency_code": "USD" }, "adjusted_totals": { "subtotal": "100000", "tax": "8874", "total": "108874", "grand_total": "108874", "fee": "5494", "earnings": "94506", "currency_code": "USD" }, "payout_totals": { "subtotal": "100000", "tax": "8874", "discount": "0", "total": "108874", "credit": "0", "credit_to_balance": "0", "balance": "0", "grand_total": "108874", "fee": "5494", "earnings": "94506", "currency_code": "USD" }, "adjusted_payout_totals": { "subtotal": "100000", "tax": "8874", "total": "108874", "fee": "5494", "chargeback_fee": { "amount": "0", "original": null }, "earnings": "94506", "currency_code": "USD" }, "line_items": [ { "id": "txnitm_01hmrd3wfyk8f33bh4ec35v36n", "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 30, "totals": { "subtotal": "90000", "tax": "7987", "discount": "0", "total": "97987" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "type": "standard", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "custom_data": { "features": { "crm": true, "data_retention": false, "reports": true }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": "Move from Basic to Pro to take advantage of advanced reporting and a CRM that's right where you're chatting." }, "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "tax": "266", "discount": "0", "total": "3266" }, "proration": { "rate": "1", "billing_period": { "starts_at": "2024-04-22T08:25:12.565118Z", "ends_at": "2024-05-22T08:25:12.565118Z" } } }, { "id": "txnitm_01hmrd3wfyk8f33bh4ek8ywy7p", "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "type": "standard", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "custom_data": null, "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "proration": { "rate": "1", "billing_period": { "starts_at": "2024-04-22T08:25:12.565118Z", "ends_at": "2024-05-22T08:25:12.565118Z" } } } ] }, "payments": [ { "payment_attempt_id": "ce7acfcd-5a98-489b-9b21-5377e3359bd4", "stored_payment_method_id": "badbd3d8-df98-4aa4-b7ba-5e9ad85b4488", "payment_method_id": "paymtd_01h3h3a0q85s2tnntt6ypt063k", "amount": "108874", "status": "captured", "error_code": null, "method_details": { "type": "card", "card": { "type": "visa", "last4": "4242", "expiry_month": 1, "expiry_year": 2026, "cardholder_name": "Michael McGovern" } }, "created_at": "2024-01-22T10:58:01.972691Z", "captured_at": "2024-01-22T10:58:04.191515Z" } ], "checkout": { "url": "https://aeroedit.com/pay?_ptxn=txn_01hmrd3w1n9dqvsgccdca02gvg" } }, "meta": { "request_id": "469ca986-df8d-4022-95ca-e035dc8aab58" }}Next steps
This change is available in version 1 of the Paddle API.
It's a non-breaking change, meaning it doesn't impact existing integrations.
The stored_payment_method_id field is now deprecated. We may remove it in future versions of the API. We recommend using the payment_method_id field instead.
You can list transactions to see the new field.
Summary of changes
| Entity | Field | Change | Type |
|---|---|---|---|
| Transaction | payment_method_id | + Added | Field |
| Paddle ID of the saved payment method used, on transaction payments. | |||
| Transaction | stored_payment_method_id | - Deprecated | Field |