Update a payment

​

Updates mutable reconciliation 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.

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 string[]
Headers
  • Idempotency-Key
    Type: string
    max length:  
    255    Pattern: ^[a-zA-Z0-9:_\-.]+$

    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 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.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v2/payments/{id}
curl 'https://api.paypercut.io/v2/payments/{id}' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "client_reference_id": "order_1042",
  "metadata": {
    "cart_id": "cart_987",
    "source": "checkout"
  }
}'

{
  "id": "string",
  "created": "2026-07-08T08:02:27.741Z",
  "amount": 2000,
  "currency": {
    "iso": "usd",
    "scale": 2
  },
  "status": "failed",
  "metadata": {
    "additionalProperty": "string"
  },
  "balance_transaction": {
    "id": "string",
    "created": "2026-07-08T08:02:27.741Z",
    "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-07-08T08:02:27.741Z",
  "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
}

Detailed Payment Information