> ## Documentation Index > Fetch the complete documentation index at: https://docs.envoi.no/llms.txt > Use this file to discover all available pages before exploring further. # Record a payment > Records one payment on a sent invoice. Part payments are allowed; the invoice becomes `paid` when nothing is outstanding. The payment's id is derived from the API client's grant and the `Idempotency-Key`, so one key names one payment for as long as the invoice exists. The same key on the same invoice answers `201` with the existing payment and records nothing twice, also after the key's 7 days have passed. The same key on another invoice is `422 idempotency-key-reused`, at any age. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/invoices/{id}/payments openapi: 3.0.4 info: title: Envoi API description: >- The Envoi API lets your own systems work with an Envoi account: create and send invoices, record payments, keep the customer register in step, and read the books. An online store such as Nordvik Handel AS can, for example, create an invoice in Envoi for every B2B order from its web shop and mark it paid when the money arrives. **Base URL.** `https://api.envoi.no`. Every path starts with `/v1`. **Authentication.** An Owner or Admin creates an API client in Envoi under *Settings → API clients* (in the app: *Innstillinger → API-klienter*) and gets a Client ID and a client secret (shown once). Exchange them for an access token at `POST /v1/oauth/token` (OAuth 2.0 client credentials) and send it as `Authorization: Bearer {access_token}`. A token lives 15 minutes; ask for a new one when it expires. Every request is checked against Envoi's database, not only the token: deleting the client, rotating its secret or removing a scope takes effect on the next request. **Accounts and environments.** A token acts on one account, named by its Account ID in the token request's `audience`: `P11112001` is the production account, `T11112001` its test environment. Nothing done in the test environment reaches a real customer: emails are captured, not delivered. An id from another account, or from the other environment, is `404 not-found`, never `403`. **Scopes.** Each endpoint needs one scope, such as `invoices:read`. Levels nest: `admin` includes `write`, `write` includes `read`. A request without the scope is `403 insufficient_scope`. **Errors.** Every error is JSON: `{ "code": "...", "message": "..." }`, sometimes with `details`, and with `errors` (one entry per field) on `400 validation-failed`. Branch on `code`; the message is for developers and may change. The token endpoint uses the OAuth shape `{ "error": "..." }` instead. **Idempotency.** Every POST needs an `Idempotency-Key` header. A retry with the same key and the same request gets the first answer again instead of creating a second invoice or payment. **Paging.** Lists take `page` (from 1) and `pageSize` (1 to 100) and answer `{ "items": [...], "page": 1, "pageSize": 20, "totalCount": 57, "hasMore": true }`. **Values.** JSON in camelCase. Dates are `yyyy-MM-dd`; timestamps ISO 8601 in UTC. Money is in kroner as a decimal number; `currency` is always `NOK` in v1. VAT codes are the SAF-T standard codes (for sales: `3` = 25 %, `31` = 15 %, `33` = 12 %, `5` = exempt, `6` = outside the VAT Act, `7` = no VAT treatment, `52` = export). **Rate limits.** Each API client may send 600 requests a minute; the token endpoint allows 60 requests a minute per IP address and 30 per Client ID. Above that the answer is `429` with a `Retry-After` header. version: v1 servers: - url: https://api.envoi.no description: >- Production and test environment (the token's audience picks the environment) security: [] tags: - name: Authentication description: >- Get an access token with the OAuth 2.0 client credentials grant, and see which API client and account a token belongs to. - name: Invoices description: >- Create draft invoices, send them, record payments, and read invoices. The same rules as in the Envoi app. - name: Clients description: The account's customer register. - name: Accounting description: >- Read-only views of the built-in books: the chart of accounts and journal entries. Only when Envoi's built-in accounting is turned on for the account. paths: /v1/invoices/{id}/payments: post: tags: - Invoices summary: Record a payment description: >- Records one payment on a sent invoice. Part payments are allowed; the invoice becomes `paid` when nothing is outstanding. The payment's id is derived from the API client's grant and the `Idempotency-Key`, so one key names one payment for as long as the invoice exists. The same key on the same invoice answers `201` with the existing payment and records nothing twice, also after the key's 7 days have passed. The same key on another invoice is `422 idempotency-key-reused`, at any age. operationId: recordInvoicePayment parameters: - name: Idempotency-Key in: header description: >- Required on every POST, at most 255 characters. Use a new UUID for each logical operation. The first request with a key runs, and its answer (any status below 500) is stored for 7 days. A retry with the same key, method, path and body gets the stored answer again with `Idempotency-Replayed: true`, and nothing runs twice. The same key with a different body or path is `422 idempotency-key-reused`; the same key while the first request is still running is `409 idempotency-key-in-progress`. A 5xx answer is not stored, so the same key may be retried. A key belongs to the API client's grant (one environment). required: true schema: maxLength: 255 type: string example: 5d3f1c52-7a4e-4f7e-9f5c-1b2d3e4f5a6b - name: id in: path description: The invoice's id. required: true schema: type: string format: uuid example: 8b6f2a4e-1c3d-4e5f-9a7b-2c4d6e8f0a12 requestBody: description: The payment. content: application/json: schema: $ref: '#/components/schemas/RecordPaymentRequest' example: amount: 1250 paidOn: '2026-09-29' responses: '201': description: The payment and the invoice's new balance. headers: Idempotency-Replayed: description: >- `true` when this is the stored answer to an earlier request with the same `Idempotency-Key`. Absent otherwise. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PaymentResult' example: paymentId: e7f1a2b3-c4d5-4e6f-8a9b-0c1d2e3f4a5b invoiceStatus: paid paidAmount: 1250 outstandingAmount: 0 '400': description: >- - `validation-failed`: `paidOn` is missing (`required`) or a field is not valid. - `payment-not-positive`: `amount` is zero or less. - `payment-date-in-future`: `paidOn` is after today. - `idempotency-key-required`: the `Idempotency-Key` header is missing. - `idempotency-key-too-long`: the `Idempotency-Key` is longer than 255 characters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: payment-date-in-future: summary: payment-date-in-future value: code: payment-date-in-future message: The payment date cannot be in the future. idempotency-key-required: summary: idempotency-key-required value: code: idempotency-key-required message: Every POST needs an Idempotency-Key header. '401': description: >- - `unauthorized`: no token, an invalid or expired one, or a token the per-request check refuses (the client or its grant was deleted, the secret was rotated, or the account is being closed). Header `WWW-Authenticate: Bearer error="invalid_token"`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: summary: unauthorized value: code: unauthorized message: A valid API client access token is required. '403': description: >- - `insufficient_scope`: the grant does not hold `invoices:write` (or a higher level of it). content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_scope: summary: insufficient_scope value: code: insufficient_scope message: This API client needs invoices:write. '404': description: '- `not-found`: no invoice with this id in this account.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: not-found: summary: not-found value: code: not-found message: Not found. '409': description: >- - `payment-exceeds-outstanding`: the amount is more than is owed. `details.outstanding` is the amount owed. - `invoice-not-payable`: the invoice cannot take a payment in its state (for example a draft). - `idempotency-key-in-progress`: a request with this `Idempotency-Key` is still running. Retry after `Retry-After` seconds. headers: Retry-After: description: >- Sent with `idempotency-key-in-progress`: seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' examples: payment-exceeds-outstanding: summary: payment-exceeds-outstanding value: code: payment-exceeds-outstanding message: The amount is more than is owed on the invoice. details: outstanding: 250 idempotency-key-in-progress: summary: idempotency-key-in-progress value: code: idempotency-key-in-progress message: >- A request with this Idempotency-Key is still being processed. '413': description: >- - `payload-too-large`: the body is larger than 1 MB. The key is not used up. content: application/json: schema: $ref: '#/components/schemas/Error' examples: payload-too-large: summary: payload-too-large value: code: payload-too-large message: The request body is larger than 1 MB. '422': description: >- - `idempotency-key-reused`: this `Idempotency-Key` was already used for a payment on another invoice. - `idempotency-key-reused`: this `Idempotency-Key` was already used for a different request (another body or path). content: application/json: schema: $ref: '#/components/schemas/Error' examples: idempotency-key-reused: summary: idempotency-key-reused value: code: idempotency-key-reused message: >- This Idempotency-Key was already used for a different request. '429': description: >- - `rate_limited`: this API client sent too many requests. Wait the number of seconds in `Retry-After`. headers: Retry-After: description: Seconds to wait before the next request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: summary: rate_limited value: code: rate_limited message: Too many requests; try again later. '500': description: >- - `server-error`: something unexpected went wrong. The message never contains details. On a POST the `Idempotency-Key` is released, so retrying with the same key is safe. content: application/json: schema: $ref: '#/components/schemas/Error' examples: server-error: summary: server-error value: code: server-error message: >- The request could not be completed. It is safe to retry with the same Idempotency-Key. security: - oauth2: - invoices:write - bearerAuth: [] components: schemas: RecordPaymentRequest: required: - amount - paidOn type: object properties: amount: type: number description: Amount paid, in kroner. Above zero and at most what is owed. paidOn: type: string description: The date the money was paid; not in the future. Required. format: date description: A payment to record. PaymentResult: required: - invoiceStatus - outstandingAmount - paidAmount - paymentId type: object properties: paymentId: type: string description: >- The payment's id. The same `Idempotency-Key` on the same invoice always gives the same id. format: uuid invoiceStatus: type: string description: The invoice's status after the payment, for example `paid`. paidAmount: type: number description: How much has been paid on the invoice in all. outstandingAmount: type: number description: How much is still owed. description: A recorded payment and the invoice's new balance. Error: required: - code - message type: object properties: code: type: string description: >- A stable, machine-readable code, for example `not-found` or `insufficient_scope`. Branch on this, never on the message. message: type: string description: >- A short English sentence for a developer. Never contains customer data and may change. details: type: object additionalProperties: {} description: >- Extra facts for some codes, for example `existingId` on `client-exists`, `outstanding` on `payment-exceeds-outstanding`, `maxMonths` on `period-too-long`. Absent otherwise. nullable: true errors: type: array items: $ref: '#/components/schemas/FieldError' description: >- Present only on `validation-failed`: one entry per field that failed. nullable: true description: The error body of every `/v1` endpoint except the token endpoint. FieldError: required: - code - field type: object properties: field: type: string description: >- The field's path in the request, for example `dueDate` or `lines[0].quantity`. code: type: string description: A stable kebab-case code, for example `required` or `greater-than`. description: A field that failed validation. securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client credentials. The token request also needs the `audience` form field (the Account ID), which OAuth tooling does not always send; see `POST /v1/oauth/token`. flows: clientCredentials: tokenUrl: https://api.envoi.no/v1/oauth/token scopes: bilag:read: >- Read access to the books (the chart of accounts and journal entries). bilag:write: >- Write access to the books (the chart of accounts and journal entries). Includes bilag:read. clients:admin: Admin access to clients. Includes clients:write and clients:read. clients:read: Read access to clients. clients:write: Write access to clients. Includes clients:read. invoices:admin: >- Admin access to invoices. Includes invoices:write and invoices:read. invoices:read: Read access to invoices. invoices:write: Write access to invoices. Includes invoices:read. bearerAuth: type: http description: >- The `access_token` from `POST /v1/oauth/token`, as `Authorization: Bearer {access_token}`. It lives 15 minutes. scheme: bearer bearerFormat: JWT ````