How to Update a Payment Method (Billing Address, Postal Code, etc.)

Why You Might Want to Do This

You can update payment method information using the PATCH API endpoint. You might need to do this for several reasons:

• A customer made a typo during checkout (e.g. wrong ZIP or phone number).

• The billing address changed and needs to be corrected.

• Card expiry information needs to be updated.

---

Endpoint

PATCH /payment_methods/{id}
Replace {id} with the ID of the payment method you're updating.

Content-Type: application/json

---

Payload Structure

Use the following sample payload to update the postal code, billing address, and other fields:

{
  "billing_details": {
    "address": {
      "line1": "123 New Street",
      "line2": "Suite 400",
      "city": "Houston",
      "state": "TX",
      "postal_code": "77002",
      "country": "US"
    },
    "email": "customer@example.com",
    "name": "Jane Doe",
    "phone": "555-123-4567"
  },
  "card": {
    "exp_month": "12",
    "exp_year": "2026"
  }
}

Only include the fields you want to update — partial updates are supported.

---

Response

A successful update returns a 200 with the updated payment method object in JSON format. For example:

{
  "id": "pm_1234567890",
  "entity": "payment_method",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:45:00Z",
  "billing_details": {
    "address": {
      "line1": "123 New Street",
      "line2": "Suite 400",
      "city": "Houston",
      "state": "TX",
      "postal_code": "77002",
      "country": "US"
    },
    "email": "customer@example.com",
    "name": "Jane Doe",
    "phone": "555-123-4567"
  },
  "card": {
    "exp_month": "12",
    "exp_year": "2026"
  }
}

---

Example Use Cases

Here are common scenarios where you might need to update payment method information:

Scenario	Fields to Update
Customer entered wrong ZIP code	billing_details.address.postal_code
Billing address changed	billing_details.address
Card expiration date needs refresh	card.exp_month, card.exp_year

---

Tips

• You do not need to include all fields — only what’s changing.
• Make sure the id in the URL matches the payment method you want to update.