> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# Update a payment

Change a payment's metadata.

`PATCH https://dash.402pay.co/api/v1/payments/{id}`

Changes a payment's metadata. Checkout sets everything else, so it can't change.

### Path

- `id` (string, required): The payment's ID, such as `pmt_QI02vLdJGd48hBbg`.

### Body

- `metadata` (object): Merged by key. An empty string or `null` removes a key, and `null` clears them all.

### Errors

- 400 `invalid_request` A field other than `metadata` was sent, a key or value breaks the rules, or the result would hold more than 20 keys.
- 404 `not_found` No payment with that ID belongs to your business.

Any request can also fail on its key or its body. See [errors](https://developer.402pay.co/api/errors.md).

Request, cURL:

```bash
curl -X PATCH "https://dash.402pay.co/api/v1/payments/pmt_QI02vLdJGd48hBbg" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "shipped": "true"
    }
  }'
```

Request, Node.js:

```js
const response = await fetch("https://dash.402pay.co/api/v1/payments/pmt_QI02vLdJGd48hBbg", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    metadata: {
      shipped: "true"
    }
  }),
});
const { data } = await response.json();
```

Request, Python:

```python
import os

import requests

response = requests.patch(
    "https://dash.402pay.co/api/v1/payments/pmt_QI02vLdJGd48hBbg",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
    json={
        "metadata": {
            "shipped": "true"
        }
    },
)
data = response.json()["data"]
```

Response, 200 OK:

```json
{
  "data": {
    "id": "pmt_QI02vLdJGd48hBbg",
    "kind": "payment",
    "status": "succeeded",
    "amount": 4900,
    "currency": "USD",
    "fee_payer": "business",
    "customer_fee": 0,
    "amount_received": 4900,
    "reporting": {
      "currency": "USD",
      "amount": 4900,
      "fee": 0,
      "transaction_fee": 25,
      "customer_fee": 0,
      "net": 4875
    },
    "fee_rate_bps": 0,
    "method": {
      "rail": "crypto",
      "asset": "USDC",
      "network": "polygon",
      "amount": "49.00",
      "expected_amount": "49.00",
      "overpaid_amount": null,
      "from_address": "0x136e44a2738dea5217e8d6745463d2a9a84d1421",
      "tx_hash": "0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20",
      "explorer_url": "https://polygonscan.com/tx/0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20"
    },
    "settlement": {
      "destination": "wallet",
      "asset": "USDC",
      "network": "polygon",
      "amount": "49.00",
      "wallet_id": "wal_1fIGZOrILmsCO0jw",
      "address": "0x9a3c416D4A81669C01f4515bBDEB93C45d3813fe",
      "tx_hash": "0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20",
      "explorer_url": "https://polygonscan.com/tx/0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20"
    },
    "customer_id": "cst_gWFWcc7Ga0Pv7LSC",
    "link_id": null,
    "url": "https://checkout.402pay.co/checkout/2jrsrcxv7k",
    "reference": "order_1042",
    "metadata": {
      "order_id": "1042",
      "shipped": "true"
    },
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cart",
    "expires_at": "2026-09-27T21:22:47.038Z",
    "canceled_at": null,
    "checkout_id": "chk_C5yhPQvPqpYgdDgj",
    "description": "Pro plan, monthly",
    "country": "US",
    "failure_code": null,
    "failure_message": null,
    "confirmed_at": "2026-09-26T21:23:13.447Z",
    "created_at": "2026-09-26T21:22:47.038Z",
    "updated_at": "2026-09-26T21:23:13.447Z",
    "events": [
      {
        "type": "created",
        "created_at": "2026-09-26T21:22:47.038Z",
        "data": null
      },
      {
        "type": "method_selected",
        "created_at": "2026-09-26T21:22:47.047Z",
        "data": {
          "rail": "crypto",
          "asset": "USDC",
          "network": "polygon"
        }
      },
      {
        "type": "detected",
        "created_at": "2026-09-26T21:23:07.047Z",
        "data": {
          "amount": "49.00",
          "network": "polygon",
          "tx_hash": "0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20"
        }
      },
      {
        "type": "confirmation",
        "created_at": "2026-09-26T21:23:08.647Z",
        "data": {
          "current": 1,
          "required": 4
        }
      },
      {
        "type": "confirmation",
        "created_at": "2026-09-26T21:23:10.247Z",
        "data": {
          "current": 2,
          "required": 4
        }
      },
      {
        "type": "confirmation",
        "created_at": "2026-09-26T21:23:11.847Z",
        "data": {
          "current": 3,
          "required": 4
        }
      },
      {
        "type": "confirmation",
        "created_at": "2026-09-26T21:23:13.447Z",
        "data": {
          "current": 4,
          "required": 4
        }
      },
      {
        "type": "succeeded",
        "created_at": "2026-09-26T21:23:13.447Z",
        "data": null
      }
    ]
  }
}
```