New payment method ID field for transaction payments

More easily work with payment methods against transaction payment attempts using a new field that returns a Paddle ID.

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_idstring

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.

200 OK


231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
231              "ends_at": "2024-05-22T08:25:12.565118Z"
232            }
233          }
234        }
235      ]
236    },
237    "payments": [
238      {
239        "payment_attempt_id": "ce7acfcd-5a98-489b-9b21-5377e3359bd4",
240        "stored_payment_method_id": "badbd3d8-df98-4aa4-b7ba-5e9ad85b4488",
241        "payment_method_id": "paymtd_01h3h3a0q85s2tnntt6ypt063k",
242        "amount": "108874",
243        "status": "captured",
244        "error_code": null,
245        "method_details": {
246          "type": "card",
247          "card": {
248            "type": "visa",
249            "last4": "4242",
250            "expiry_month": 1,

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.

Learn more

Transaction entity overview

Paddle IDs