Record one confirmed full external invoice payment

Generated from the checked-in source. Do not edit this reference by hand.

POST /api/v1/organizations/{organization}/projects/{project}/billing/invoices/{invoice}/payment

Installation only. Records a full external payment only for a positive invoice with no balance-bound charges. Mixed invoices, balance-backed invoices and zero-value invoices conflict. Does not top up an account or accept partial payments. Existing exact retries remain idempotent. Does not charge any payment method. References cannot be reused on another invoice. Cache-Control is no-store.

Operation: recordCustomerExternalPayment.

Authentication

Use the credential and permission scope described above. Each object below is an alternative; schemes within one object are required together.

JSON

[
  {
    "adminBearerAuth": []
  }
]

HTTP request

Set NIU_ORIGIN to your installation origin (without /v1). Replace path, query and header placeholders with the required values. Query examples use curl 7.87 or newer to encode values with --url-query. Use the credential scope described above; a bearer token must have the authority required by this operation.

Shell

curl --fail-with-body -X POST "$NIU_ORIGIN/api/v1/organizations/{organization}/projects/{project}/billing/invoices/{invoice}/payment" \
  -H "Authorization: Bearer $NIU_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data @request.json

Parameters

organization

Location: path. Required.

JSON

{
  "type": "string",
  "format": "uuid"
}

project

Location: path. Required.

JSON

{
  "type": "string",
  "format": "uuid"
}

invoice

Location: path. Required.

JSON

{
  "type": "string",
  "format": "uuid"
}

Request body

application/json

Required.

JSON

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "payment_reference"
  ],
  "properties": {
    "payment_reference": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Trimmed nonempty external payment reference; maximum 200 UTF-8 bytes and no control characters."
    }
  }
}

Responses

HTTP 200

Invoice identity, including an exact idempotent replay

Content type: application/json.

JSON

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        }
      }
    }
  }
}

HTTP 400

Invalid reference

HTTP 403

Installation authority required

HTTP 409

Invoice missing, balance-bound or zero-value invoice, already recorded with another reference, or reference already used

Behavior and supported scope

Installation only. Records a full external payment only for a positive invoice with no balance-bound charges. Mixed invoices, balance-backed invoices and zero-value invoices conflict. Does not top up an account or accept partial payments. Existing exact retries remain idempotent. Does not charge any payment method. References cannot be reused on another invoice. Cache-Control is no-store.