> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# 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](https://developer.paddle.com/api-reference/transactions/overview.md). It returns a [Paddle ID](https://developer.paddle.com/api-reference/about/paddle-ids.md).

- **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](https://developer.paddle.com/api-reference/about/paddle-ids.md) 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](https://developer.paddle.com/api-reference/transactions/get-transaction.md). The `stored_payment_method_id` and `payment_method_id` fields are highlighted.

```json {% title="200 OK" highlightLines="240-241" collapse=true %}
{
  "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](https://developer.paddle.com/api-reference/transactions/list-transactions.md) to see the new field.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `payment_method_id` | Field | added | Transaction | Paddle ID of the saved payment method used, on transaction payments. |
| `stored_payment_method_id` | Field | deprecated | Transaction |  |