Record carrier payment

POST

api

{version}

invoices

carrier-payments

Record carrier payment

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "TripId": "<string>",
  "Amount": {
    "Amount": 123,
    "Currency": 123
  },
  "PaymentDate": "2023-11-07T05:31:56Z",
  "ReferenceNumber": "<string>",
  "PaymentMethod": "<string>",
  "CheckNumber": "<string>",
  "Note": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    TripId: '<string>',
    Amount: {Amount: 123, Currency: 123},
    PaymentDate: '2023-11-07T05:31:56Z',
    ReferenceNumber: '<string>',
    PaymentMethod: '<string>',
    CheckNumber: '<string>',
    Note: '<string>'
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments"

payload = {
    "TripId": "<string>",
    "Amount": {
        "Amount": 123,
        "Currency": 123
    },
    "PaymentDate": "2023-11-07T05:31:56Z",
    "ReferenceNumber": "<string>",
    "PaymentMethod": "<string>",
    "CheckNumber": "<string>",
    "Note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'TripId' => '<string>',
    'Amount' => [
        'Amount' => 123,
        'Currency' => 123
    ],
    'PaymentDate' => '2023-11-07T05:31:56Z',
    'ReferenceNumber' => '<string>',
    'PaymentMethod' => '<string>',
    'CheckNumber' => '<string>',
    'Note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments"

	payload := strings.NewReader("{\n  \"TripId\": \"<string>\",\n  \"Amount\": {\n    \"Amount\": 123,\n    \"Currency\": 123\n  },\n  \"PaymentDate\": \"2023-11-07T05:31:56Z\",\n  \"ReferenceNumber\": \"<string>\",\n  \"PaymentMethod\": \"<string>\",\n  \"CheckNumber\": \"<string>\",\n  \"Note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"TripId\": \"<string>\",\n  \"Amount\": {\n    \"Amount\": 123,\n    \"Currency\": 123\n  },\n  \"PaymentDate\": \"2023-11-07T05:31:56Z\",\n  \"ReferenceNumber\": \"<string>\",\n  \"PaymentMethod\": \"<string>\",\n  \"CheckNumber\": \"<string>\",\n  \"Note\": \"<string>\"\n}")
  .asString();

{
  "TripId": "<string>",
  "TripNumber": "<string>",
  "Status": "<string>",
  "CarrierPayments": [
    {
      "Id": "<string>",
      "Amount": {
        "Amount": 123,
        "Currency": 123
      },
      "PaymentDate": "2023-11-07T05:31:56Z",
      "ReferenceNumber": "<string>",
      "PaymentMethod": "<string>",
      "CheckNumber": "<string>"
    }
  ]
}

{
  "Errors": {},
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

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

{
  "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

{
  "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"
    }
  ]
}

Authorizations

Authorization

string

header

required

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

Path Parameters

version

string

default:1.0

required

API version (e.g., 1.0)

Example:

"1.0"

Body

TripId

string

required

Identifier of the trip for which the carrier payment is being recorded.

Amount

object

required

Show child attributes

PaymentDate

string<date-time>

required

ReferenceNumber

string

required

PaymentMethod

string | null

CheckNumber

string | null

Note

string | null

Response

TripId

string

required

TripNumber

string

required

Status

string

required

Current trip status after the payment is applied. When payments fully cover the carrier payable, this is Completed.

CarrierPayments

object[]

required

Show child attributes

⌘I

Record carrier payment

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "TripId": "<string>",
  "Amount": {
    "Amount": 123,
    "Currency": 123
  },
  "PaymentDate": "2023-11-07T05:31:56Z",
  "ReferenceNumber": "<string>",
  "PaymentMethod": "<string>",
  "CheckNumber": "<string>",
  "Note": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    TripId: '<string>',
    Amount: {Amount: 123, Currency: 123},
    PaymentDate: '2023-11-07T05:31:56Z',
    ReferenceNumber: '<string>',
    PaymentMethod: '<string>',
    CheckNumber: '<string>',
    Note: '<string>'
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments"

payload = {
    "TripId": "<string>",
    "Amount": {
        "Amount": 123,
        "Currency": 123
    },
    "PaymentDate": "2023-11-07T05:31:56Z",
    "ReferenceNumber": "<string>",
    "PaymentMethod": "<string>",
    "CheckNumber": "<string>",
    "Note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'TripId' => '<string>',
    'Amount' => [
        'Amount' => 123,
        'Currency' => 123
    ],
    'PaymentDate' => '2023-11-07T05:31:56Z',
    'ReferenceNumber' => '<string>',
    'PaymentMethod' => '<string>',
    'CheckNumber' => '<string>',
    'Note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments"

	payload := strings.NewReader("{\n  \"TripId\": \"<string>\",\n  \"Amount\": {\n    \"Amount\": 123,\n    \"Currency\": 123\n  },\n  \"PaymentDate\": \"2023-11-07T05:31:56Z\",\n  \"ReferenceNumber\": \"<string>\",\n  \"PaymentMethod\": \"<string>\",\n  \"CheckNumber\": \"<string>\",\n  \"Note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/invoices/carrier-payments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"TripId\": \"<string>\",\n  \"Amount\": {\n    \"Amount\": 123,\n    \"Currency\": 123\n  },\n  \"PaymentDate\": \"2023-11-07T05:31:56Z\",\n  \"ReferenceNumber\": \"<string>\",\n  \"PaymentMethod\": \"<string>\",\n  \"CheckNumber\": \"<string>\",\n  \"Note\": \"<string>\"\n}")
  .asString();

{
  "TripId": "<string>",
  "TripNumber": "<string>",
  "Status": "<string>",
  "CarrierPayments": [
    {
      "Id": "<string>",
      "Amount": {
        "Amount": 123,
        "Currency": 123
      },
      "PaymentDate": "2023-11-07T05:31:56Z",
      "ReferenceNumber": "<string>",
      "PaymentMethod": "<string>",
      "CheckNumber": "<string>"
    }
  ]
}

{
  "Errors": {},
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

​Path Parameters

​Request Body

​Example Request

​Response Body

​CarrierPayments Object

​Example Response

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Example Request

Response Body

CarrierPayments Object

Example Response