order.payment.record

Record a payment that arrived OUTSIDE the order flow (a reconciled transfer, a boleto matched on the statement). Idempotent by the caller key: the same key twice is one movement. Never exceeds the order total.

• Scope: order.payment.write
• System: no
• Reachable from: POST /v1/commands/order.payment.record (tenant credential) · MCP tool order.payment.record · SDK client.call('order.payment.record', …)
• Events: order.payment.recorded

Input (JSON Schema)

{
  "properties": {
    "amount": {
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "type": "string"
    },
    "method": {
      "maxLength": 50,
      "minLength": 1,
      "type": "string"
    },
    "occurred_at": {
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "type": "string"
    },
    "order_id": {
      "minLength": 1,
      "type": "string"
    },
    "reference": {
      "maxLength": 200,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "order_id",
    "amount",
    "idempotency_key"
  ],
  "type": "object"
}

Result (200)

{
  "additionalProperties": false,
  "properties": {
    "authorized": {
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "captured": {
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "order_id": {
      "type": "string"
    },
    "payment_status": {
      "enum": [
        "not_paid",
        "partially_authorized",
        "partially_paid",
        "paid",
        "partially_refunded",
        "refunded"
      ],
      "type": "string"
    },
    "refunded": {
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "total_amount": {
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "transaction_id": {
      "type": "string"
    }
  },
  "required": [
    "order_id",
    "transaction_id",
    "payment_status",
    "captured",
    "authorized",
    "refunded",
    "total_amount"
  ],
  "type": "object"
}

Errors

validation_failed (400) · unauthorized (401) · forbidden (403) · conflict (409) · internal (500)