> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Record carrier payment

> Record a carrier payment against a trip. Idempotent on `ReferenceNumber` — re-submitting the same reference returns the current state without creating a duplicate payment.

When recorded payments fully cover the carrier payable, the trip transitions to `Completed`. Partial payments leave the trip status unchanged.

This endpoint allows external systems (for example factoring or payment platforms) to record a carrier payment against a trip in Alvys.

### Path Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| version   | string | Yes      | API version (e.g., `1.0`) |

### Request Body

Content-Type: `application/json-patch+json`

| Field           | Type               | Required | Description                                                            |
| --------------- | ------------------ | -------- | ---------------------------------------------------------------------- |
| TripId          | string             | Yes      | Identifier of the trip for which the carrier payment is being recorded |
| Amount          | object             | Yes      | Payment amount object                                                  |
| Amount.Amount   | number             | Yes      | Payment amount value                                                   |
| Amount.Currency | integer            | Yes      | Currency identifier                                                    |
| PaymentDate     | string (date-time) | Yes      | Date when the payment was made                                         |
| ReferenceNumber | string             | Yes      | External reference number for the payment                              |
| PaymentMethod   | string             | No       | Payment method used (e.g., Check, ACH, Wire)                           |
| CheckNumber     | string             | No       | Check number if payment method is check                                |
| Note            | string             | No       | Additional note related to the payment                                 |
| MarkAsPaid      | boolean            | No       | Indicates whether the trip should be marked as fully paid              |

### Example Request

```json theme={null}
{
  "TripId": "string",
  "Amount": {
    "Amount": 0,
    "Currency": 0
  },
  "PaymentDate": "2026-03-16T13:48:19.920Z",
  "ReferenceNumber": "string",
  "PaymentMethod": "string",
  "CheckNumber": "string",
  "Note": "string",
  "MarkAsPaid": true
}
```

### Response Body

| Field           | Type   | Description                                    |
| --------------- | ------ | ---------------------------------------------- |
| TripId          | string | Identifier of the trip                         |
| TripNumber      | string | Trip number associated with the payment        |
| Status          | string | Current trip status                            |
| CarrierPayments | array  | List of carrier payments recorded for the trip |

#### CarrierPayments Object

| Field           | Type    | Description                        |
| --------------- | ------- | ---------------------------------- |
| Id              | string  | Unique identifier of the payment   |
| Amount          | object  | Payment amount object              |
| Amount.Amount   | number  | Payment amount value               |
| Amount.Currency | integer | Currency identifier                |
| PaymentDate     | string  | Date when the payment was recorded |
| ReferenceNumber | string  | Payment reference number           |
| PaymentMethod   | string  | Payment method used                |
| CheckNumber     | string  | Check number if applicable         |

### Example Response

```json theme={null}
{
  "TripId": "string",
  "TripNumber": "string",
  "Status": "string",
  "CarrierPayments": [
    {
      "Id": "string",
      "Amount": {
        "Amount": 0,
        "Currency": 0
      },
      "PaymentDate": "2026-03-16T13:48:19.924Z",
      "ReferenceNumber": "string",
      "PaymentMethod": "string",
      "CheckNumber": "string"
    }
  ]
}
```


## OpenAPI

````yaml POST /api/p/v{version}/invoices/carrier-payments
openapi: 3.0.1
info:
  title: Alvys
  description: >-
    Alvys provides a robust set of REST APIs to allow you to integrate Alvys
    into virtually any platform. These APIs cover most of Alvys' major product
    areas with additional endpoints being added regularly based on customer
    requests.
  contact:
    name: Alvys Support
    url: https://www.alvys.com/resources/contact/
  version: v1
servers:
  - url: https://integrations.alvys.com
    description: Public API Server
  - url: https://api.alvys.com/
    description: Public API Server
security:
  - Public: []
tags:
  - name: Authentication
    description: Obtain an OAuth 2.0 access token for the Alvys Public API.
  - name: Carrier Settlement Statements
    description: >-
      Search carrier settlement statements and retrieve a single statement by
      number.
  - name: Carriers
    description: Read carrier records, search carriers, and manage carrier documents.
  - name: Customers
    description: Create, read, update, delete, and search customer records.
  - name: Deductions
    description: >-
      Create one-time deductions and search or delete existing deduction
      records.
  - name: DispatchPreferences
    description: Dispatch preferences endpoints for reading dispatch rules and preferences.
  - name: Driver Settlement Statements
    description: >-
      Search driver settlement statements and retrieve a single statement by
      number.
  - name: Drivers
    description: >-
      Read driver records, search drivers and driver events, and manage driver
      documents.
  - name: Fuel
    description: Read and search fuel transactions.
  - name: Invoices
    description: >-
      Read invoices, create carrier invoices, and record carrier and customer
      payments.
  - name: Loads
    description: Read, update, search loads, and manage load documents and notes.
  - name: Locations
    description: Read and search company location details.
  - name: Maintenance
    description: Read and search maintenance records.
  - name: Tenders
    description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
  - name: Tolls
    description: Read and search toll transactions.
  - name: Trailers
    description: Read trailers, search trailer events, and manage trailer documents.
  - name: Trips
    description: >-
      Read, search trips, manage trip documents, and record stop appointments,
      arrivals, and departures.
  - name: Trucks
    description: Read trucks, search truck events, and manage truck documents.
  - name: Users
    description: List and search users.
  - name: Visibility
    description: >-
      Read inbound and outbound visibility history and search outbound
      visibility errors.
  - name: Webhooks
    description: >-
      Create, read, update, delete, enable, disable, verify, test, and rotate
      secrets for webhook subscriptions; read event types, delivery logs, and
      health metrics.
paths:
  /api/p/v{version}/invoices/carrier-payments:
    post:
      tags:
        - Invoices
      summary: Record carrier payment
      description: >-
        Record a carrier payment against a trip. Idempotent on `ReferenceNumber`
        — re-submitting the same reference returns the current state without
        creating a duplicate payment.


        When recorded payments fully cover the carrier payable, the trip
        transitions to `Completed`. Partial payments leave the trip status
        unchanged.
      parameters:
        - name: version
          in: path
          description: API version (e.g., 1.0)
          required: true
          schema:
            type: string
            default: '1.0'
            example: '1.0'
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Invoices.Request.CarrierPaymentRequest
          application/json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Invoices.Request.CarrierPaymentRequest
          text/json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Invoices.Request.CarrierPaymentRequest
          application/*+json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Invoices.Request.CarrierPaymentRequest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Alvys.Models.Invoices.Response.CarrierPaymentResponse
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
      security:
        - Public: []
components:
  schemas:
    Alvys.Models.Invoices.Request.CarrierPaymentRequest:
      required:
        - Amount
        - PaymentDate
        - ReferenceNumber
        - TripId
      type: object
      properties:
        TripId:
          type: string
          description: >-
            Identifier of the trip for which the carrier payment is being
            recorded.
        Amount:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        PaymentDate:
          type: string
          format: date-time
        ReferenceNumber:
          type: string
        PaymentMethod:
          type: string
          nullable: true
        CheckNumber:
          type: string
          nullable: true
        Note:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Models.Invoices.Response.CarrierPaymentResponse:
      required:
        - CarrierPayments
        - Status
        - TripId
        - TripNumber
      type: object
      properties:
        TripId:
          type: string
        TripNumber:
          type: string
        Status:
          type: string
          description: >-
            Current trip status after the payment is applied. When payments
            fully cover the carrier payable, this is `Completed`.
        CarrierPayments:
          type: array
          items:
            $ref: >-
              #/components/schemas/Alvys.Models.Invoices.Response.CarrierPaymentResponsePaymentDto
      additionalProperties: false
    Microsoft.AspNetCore.Mvc.ValidationProblemDetails:
      required:
        - Errors
      type: object
      properties:
        Errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Microsoft.AspNetCore.Mvc.ProblemDetails:
      type: object
      properties:
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Alvys.Money:
      required:
        - Amount
      type: object
      properties:
        Amount:
          type: number
          format: double
        Currency:
          type: integer
          format: int32
          nullable: true
      additionalProperties: false
    Alvys.Models.Invoices.Response.CarrierPaymentResponsePaymentDto:
      required:
        - Amount
        - Id
      type: object
      properties:
        Id:
          type: string
        Amount:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        PaymentDate:
          type: string
          format: date-time
          nullable: true
        ReferenceNumber:
          type: string
          nullable: true
        PaymentMethod:
          type: string
          nullable: true
        CheckNumber:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    Public:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 client-credentials access token. Obtain one from
        https://auth.alvys.com/oauth/token (grant_type=client_credentials,
        audience=https://api.alvys.com/public/), then paste it here. The
        playground sends it as `Authorization: Bearer <token>`.

````