Update a payment

Updates mutable fields on an existing payment. Omitted fields are left unchanged.

Use this endpoint to attach your own reconciliation fields after the payment is created, such as an order ID, cart ID, or internal customer reference. The client_reference_id field is write-once: you can set it when it is empty, and repeating the same value is accepted, but changing it to a different value is rejected.

You can also update the payment's free-form description. Metadata updates merge with existing metadata: provided keys overwrite existing values for the same keys, and omitted keys remain unchanged.

You can also search and review payments in the Merchant Dashboard.

Related guide: Payment records

Path Parameters

id
Type: string
max length:
200
required

Query Parameters

expand
Type: array of string

Headers

Idempotency-Key
Type: string
max length:
255

Provide a unique, stable key per operation so retries don't create duplicates. Allowed: letters, digits, colon, dash, underscore, dot. Max 255 characters.

Body·

required

application/json

Request parameters for updating mutable payment fields. Provide at least one of client_reference_id, description, or metadata.

client_reference_id
Type: string | null
max length:
100

A free-form reference from your system, such as an order ID, cart ID, or customer reference.

This field is write-once. You can set it when the payment does not already have a client_reference_id, and you can safely retry the same value. Changing an existing value to a different value is rejected.
metadata
Type: object

Key-value metadata to merge into the payment. Provided keys overwrite existing values for the same keys. Omitted keys remain unchanged.

Properties: 1
description
Type: string | null

A free-form description for the payment. It can be changed at any time.

Responses

application/json
application/json
application/json
application/json
application/json

post/v2/payments/{id}

curl 'https://api.paypercut.io/v2/payments/{id}' \
  --request POST \
  --header 'Idempotency-Key: order:12345:pi:create' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "client_reference_id": "order_1042",
  "metadata": {
    "cart_id": "cart_987",
    "source": "checkout"
  }
}'

Show Schema

{
  "id": "string",
  "created": "2026-10-02T06:37:26.638Z",
  "amount": 2000,
  "currency": {
    "iso": "usd",
    "scale": 2
  },
  "status": "failed",
  "metadata": {
    "additionalProperty": "string"
  },
  "balance_transaction": {
    "id": "string",
    "created": "2026-10-02T06:37:26.638Z",
    "amount": 1,
    "currency": {
      "iso": "usd",
      "scale": 2
    },
    "exchange_rate": null,
    "fee": 1,
    "net": 1
  },
  "formatted_amount": "20.00",
  "amount_captured": 1,
  "amount_refunded": 1,
  "latest_status": "succeeded",
  "captured": true,
  "updated": "2026-10-02T06:37:26.638Z",
  "outcome": {
    "network_decline_code": null,
    "network_status": null,
    "risk_score": 1,
    "seller_message": null,
    "type": "string"
  },
  "failure_code": null,
  "failure_message": null,
  "paid": true,
  "payment_method": "card",
  "payment_method_details": {
    "card": {
      "amount_authorized": null,
      "authorization_code": null,
      "authorization_type": null,
      "capture_before": null,
      "transaction_type": null,
      "brand": null,
      "country": null,
      "cardholder_name": null,
      "issuer": null,
      "funding": "string",
      "segment": "string",
      "exp_month": 1,
      "exp_year": 1,
      "last4": null,
      "network_transaction_id": null,
      "iin": "string",
      "three_d_secure": {
        "authentication_flow": null,
        "electronic_commerce_indicator": null,
        "result": null,
        "result_reason": null,
        "transaction_id": null,
        "exemption_indicator": null,
        "version": null
      },
      "wallet": {
        "type": "string"
      }
    }
  },
  "customer": "01K755J9SV2364REVHB915Z2FW",
  "payment_intent": "01K755J9SY55CS04SQ3JX1NX36",
  "checkout_id": null,
  "latest_operation": "capture",
  "refunded": true,
  "disputed": true,
  "fraud_details": {
    "response_state": "string",
    "fraud_score": 1
  },
  "client_reference_id": null,
  "statement_descriptor": null,
  "fee": 1,
  "fee_details": [
    {
      "amount": 1,
      "currency": {
        "iso": "usd",
        "scale": 2
      },
      "applied_amount": 1,
      "applied_amount_currency": {
        "iso": "usd",
        "scale": 2
      },
      "balance_account_id": null,
      "fixed_amount": 0.25,
      "rate": 1,
      "payer": "string",
      "payee": "string",
      "rule": "string",
      "exchange_rate": {
        "from_currency": {
          "iso": "usd",
          "scale": 2
        },
        "to_currency": {
          "iso": "usd",
          "scale": 2
        },
        "rate": 1,
        "reversed_rate": 1
      },
      "description": null,
      "type": "string"
    }
  ],
  "livemode": true
}