MVMNT Carrier Payment Methods API
Carrier payment method management operations
OpenAPI Specification
openapi: 3.1.0
info:
title: MVMNT Bill Payments Carrier Payment Methods API
version: 1.0.0
description: "The MVMNT API enables you to automate freight brokerage workflows by integrating\ndirectly with our Transportation Management System.\n\n## Authentication\n\nOAuth 2.0 client credentials flow. See [Authentication Guide](/getting-started/authentication)\nfor details.\n\n### Token Endpoint\n\n```\nPOST https://api.mvmnt.io/oauth2/token\n```\n\n#### Request\n\n**Headers:**\n```http\nContent-Type: application/x-www-form-urlencoded\n```\n\n**Body Parameters:**\n```\ngrant_type=client_credentials\nclient_id=YOUR_CLIENT_ID\nclient_secret=YOUR_CLIENT_SECRET\n```\n\n#### Example Request\n\n```bash\ncurl -X POST https://api.mvmnt.io/oauth2/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id=YOUR_CLIENT_ID\" \\\n -d \"client_secret=YOUR_CLIENT_SECRET\"\n```\n\n#### Success Response\n\n**Status:** `200 OK`\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600\n}\n```\n\n**Response Fields:**\n- `access_token`: JWT Bearer token to use for API requests\n- `token_type`: Always `Bearer`\n- `expires_in`: Token lifetime in seconds (3600 = 1 hour)\n"
contact:
name: MVMNT Support
email: support@mvmnt.io
url: https://docs.mvmnt.io
license:
name: Proprietary
url: https://mvmnt.io/legal/terms
x-parsed-md-description:
result:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes:
content: The MVMNT API enables you to automate freight brokerage workflows by integrating
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes: {}
children: []
type: softbreak
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes:
content: directly with our Transportation Management System.
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes:
level: 2
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: true
attributes:
content: Authentication
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: heading
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: 'OAuth 2.0 client credentials flow. See '
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
href: /getting-started/authentication
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: Authentication Guide
children: []
type: text
annotations: []
slots: {}
type: link
annotations: []
slots: {}
redocly:::linkOriginal:href: /getting-started/authentication
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: ' for details.'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
servers:
- url: https://api.mvmnt.io/v1
description: Production
security:
- BearerAuth: []
tags:
- name: Carrier Payment Methods
description: Carrier payment method management operations
paths:
/carrier-payment-methods/filter:
post:
tags:
- Carrier Payment Methods
summary: Filter carrier payment methods
description: 'Query carrier payment methods using flexible filter criteria with AND/OR logic.
By default, only non-deleted payment methods are returned (deletedAt: { isNull: true }).
Override this by explicitly setting deletedAt filter criteria.
Carrier payment methods define how and where payments are sent for a specific carrier.
'
operationId: filterCarrierPaymentMethods
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierPaymentMethodFilterRequest'
responses:
'200':
description: Filtered carrier payment methods with pagination
content:
application/json:
schema:
type: object
required:
- data
- pageInfo
properties:
data:
type: array
items:
$ref: '#/components/schemas/CarrierPaymentMethod'
pageInfo:
$ref: '#/components/schemas/PaginationInfo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'500':
$ref: '#/components/responses/InternalServerError'
/carrier-payment-methods:
post:
tags:
- Carrier Payment Methods
summary: Create carrier payment method
description: 'Create a new carrier payment method.
**Payment Recipient Type Constraints:**
- **DIRECT**: Payment goes to carrier directly. `carrierFactorId` must be null or omitted.
- **FACTOR**: Payment goes to factoring company. `carrierFactorId` is required.
**Important**: The `carrierId` cannot be changed after creation.
'
operationId: createCarrierPaymentMethod
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierPaymentMethodInput'
examples:
directPayment:
summary: Direct ACH payment to carrier
value:
carrierId: 770e8400-e29b-41d4-a716-446655440000
paymentRecipientType: DIRECT
paymentMethodType: ACH
isPreferred: true
bankName: Chase Bank
accountName: Carrier Transport Inc
accountNumber: '1234567890'
abaAch: '021000021'
currency: USD
factorPayment:
summary: Payment through factoring company
value:
carrierId: 770e8400-e29b-41d4-a716-446655440000
paymentRecipientType: FACTOR
paymentMethodType: ACH_WIRE
carrierFactorId: 550e8400-e29b-41d4-a716-446655440000
isPreferred: false
zelle:
summary: Zelle payment
value:
carrierId: 770e8400-e29b-41d4-a716-446655440000
paymentRecipientType: DIRECT
paymentMethodType: ZELLE
email: payments@carrier.com
phone: +1-555-123-4567
username: carrier_payments
responses:
'201':
description: Carrier payment method created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierPaymentMethod'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'409':
$ref: '#/components/responses/ConflictError'
'422':
$ref: '#/components/responses/ValidationError'
'500':
$ref: '#/components/responses/InternalServerError'
/carrier-payment-methods/{id}:
get:
tags:
- Carrier Payment Methods
summary: Get carrier payment method
description: 'Retrieve a single carrier payment method by its unique identifier.
Returns full details including banking information and associated carrier/factor references.
'
operationId: getCarrierPaymentMethodById
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
responses:
'200':
description: Carrier payment method found
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierPaymentMethod'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
patch:
tags:
- Carrier Payment Methods
summary: Update carrier payment method
description: 'Partially update a carrier payment method. Only provided fields will be updated.
**IMPORTANT**: The `carrierId` field cannot be changed after creation.
**Payment Recipient Type Constraints:**
- When changing to **DIRECT**: `carrierFactorId` must be set to null
- When changing to **FACTOR**: `carrierFactorId` is required
- **Omitted fields**: Not modified (current value preserved)
- **Provided fields**: Updated to the new value
- **Null values**: Clear the field (set to null) where applicable
'
operationId: updateCarrierPaymentMethod
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierPaymentMethodPatch'
examples:
updateBanking:
summary: Update banking details
value:
bankName: Bank of America
accountNumber: '9876543210'
abaAch: 026009593
changeToFactor:
summary: Change from direct to factor payment
value:
paymentRecipientType: FACTOR
carrierFactorId: 550e8400-e29b-41d4-a716-446655440000
makePreferred:
summary: Set as preferred payment method
value:
isPreferred: true
responses:
'200':
description: Carrier payment method updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierPaymentMethod'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'422':
$ref: '#/components/responses/ValidationError'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
tags:
- Carrier Payment Methods
summary: Delete carrier payment method
description: 'Soft delete a carrier payment method (sets deletedAt timestamp).
The payment method will no longer appear in default queries but can be retrieved
by explicitly filtering for deleted records.
'
operationId: deleteCarrierPaymentMethod
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
responses:
'204':
description: Carrier payment method deleted successfully
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
ValidationError:
type: object
required:
- error
- message
- details
properties:
error:
type: string
description: Error code
example: validation_error
message:
type: string
description: Human-readable error message
details:
type: array
description: Validation error details
items:
type: object
required:
- field
- message
properties:
field:
type: string
description: Field name that failed validation
message:
type: string
description: Validation error message
BooleanFilter:
type: object
description: Filter options for boolean fields
properties:
equalTo:
type: boolean
description: Exact match
notEqualTo:
type: boolean
description: Not equal to
isNull:
type: boolean
description: Field is null (true) or not null (false)
Error:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code
message:
type: string
description: Human-readable error message
CarrierFactorReference:
type: object
description: 'Enhanced reference to a carrier factor (factoring company).
Includes full carrier factor details in addition to id/key.
'
required:
- id
- companyName
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Carrier factor UUID
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference ID if set
example: ERP-FACTOR-001
companyName:
type: string
description: Factoring company legal name
example: Capital Factoring Services Inc
email:
type:
- string
- 'null'
format: email
description: Primary email address
example: accounting@capitalfactoring.com
phoneNumber:
type:
- string
- 'null'
description: Primary phone number
example: +1-555-234-5678
currency:
type:
- string
- 'null'
description: Preferred currency code (ISO 4217)
example: USD
createdAt:
type: string
format: date-time
description: When the carrier factor was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
description: When the carrier factor was last updated
example: '2025-01-15T14:30:00Z'
CarrierReference:
type: object
description: 'Enhanced reference to a carrier resource (returned in responses).
Includes full carrier details in addition to id/key.
Note: Does NOT include nested references (contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.
'
required:
- id
- name
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Carrier UUID
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference ID if set
example: ERP-CARRIER-SWIFT
name:
type: string
description: Carrier company name
example: Swift Transportation
phoneNumber:
type:
- string
- 'null'
description: Primary phone number
example: +1-555-987-6543
email:
type:
- string
- 'null'
format: email
description: Primary email address
example: dispatch@swifttrans.com
createdAt:
type: string
format: date-time
description: When the carrier was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
description: When the carrier was last updated
example: '2025-01-15T14:30:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
description: When the carrier was soft deleted (null if active)
example: null
PaginationInfo:
type: object
required:
- pageSize
- hasNextPage
properties:
pageSize:
type: integer
description: Number of items per page
example: 50
hasNextPage:
type: boolean
description: Whether there are more pages
example: true
hasPreviousPage:
type: boolean
description: Whether there are previous pages
example: false
endCursor:
type:
- string
- 'null'
description: Cursor for the next page (null if no next page)
example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9
PaymentMethodType:
type: string
description: Payment method type
enum:
- ACH_WIRE
- ZELLE
- VENMO
- ACH
- CHECK
- WIRE
- CAD_EFT
- TRIUMPH_PAY
- COMCHECK
- EFS
- ECHECK
example: ACH
CarrierPaymentMethodPatch:
type: object
description: 'Partial carrier payment method update. All fields are optional.
**IMPORTANT**: The `carrierId` field cannot be changed after creation.
- **Omitted fields**: Not modified (current value preserved)
- **Provided fields**: Updated to the new value
- **Null values**: Clear the field (set to null) where applicable
'
properties:
paymentRecipientType:
$ref: '#/components/schemas/PaymentRecipientType'
description: 'Who receives the payment.
- **DIRECT**: carrierFactorId must be null
- **FACTOR**: carrierFactorId is required
'
paymentMethodType:
$ref: '#/components/schemas/PaymentMethodType'
description: How payment is made
status:
type:
- string
- 'null'
description: Payment method status
example: ACTIVE
isPreferred:
type:
- boolean
- 'null'
description: Whether this is the preferred payment method
example: true
email:
type:
- string
- 'null'
format: email
description: Email address for payment notifications
example: payments@carrier.com
phone:
type:
- string
- 'null'
description: Phone number for payment contact
example: +1-555-123-4567
companyName:
type:
- string
- 'null'
description: Company name for this payment method
example: Carrier Payments LLC
username:
type:
- string
- 'null'
description: Username for payment platforms
example: carrier_payments
bankName:
type:
- string
- 'null'
description: Bank name
example: Chase Bank
bankAddress:
type:
- string
- 'null'
description: Bank address
example: 123 Bank Street, Dallas, TX 75201
accountName:
type:
- string
- 'null'
description: Bank account holder name
example: Carrier Transport Inc
accountNumber:
type:
- string
- 'null'
description: Bank account number
example: '1234567890'
abaAch:
type:
- string
- 'null'
description: ABA/ACH routing number
example: '021000021'
wire:
type:
- string
- 'null'
description: Wire transfer routing number
example: 026009593
swiftCode:
type:
- string
- 'null'
description: SWIFT/BIC code
example: CHASUS33
eftInstitution:
type:
- string
- 'null'
description: EFT institution number
example: '001'
eftTransit:
type:
- string
- 'null'
description: EFT transit number
example: '00010'
clabe:
type:
- string
- 'null'
description: CLABE number
example: 012180001234567897
currency:
type:
- string
- 'null'
description: Preferred currency code
example: USD
carrierFactorId:
type:
- string
- 'null'
format: uuid
description: 'Carrier factor ID.
**Constraint**: Required when paymentRecipientType is FACTOR, must be null when DIRECT.
'
example: 550e8400-e29b-41d4-a716-446655440000
paymentTermId:
type:
- string
- 'null'
format: uuid
description: Payment term ID
example: 550e8400-e29b-41d4-a716-446655440002
PaymentTermReference:
type: object
description: 'Enhanced reference to a payment term resource (returned in responses).
Includes full payment term details in addition to id/key.
'
required:
- id
- name
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Payment term UUID
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference ID if set
example: ERP-PAYTERM-NET30
name:
type: string
description: Payment term name
example: Net 30
description:
type:
- string
- 'null'
description: Payment term description or notes
example: Payment due 30 days from invoice date
days:
type:
- integer
- 'null'
description: Number of days until payment is due
example: 30
quickPayFee:
type:
- number
- 'null'
format: float
description: Quick pay fee percentage (e.g., 0.05 for 5%)
example: 0.05
x-parsed-md-description:
result:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: true
attributes:
content: Quick pay fee percentage (e.g., 0.05 for 5%)
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
apOnly:
type:
- boolean
- 'null'
description: Whether this payment term is for accounts payable only
example: false
doNotUse:
type:
- boolean
- 'null'
description: Flag to prevent using this payment term for new transactions
example: false
createdAt:
type: string
format: date-time
description: When the payment term was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
description: When the payment term was last updated
example: '2025-01-15T14:30:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
description: When the payment term was soft deleted (null if active)
example: null
UUIDFilter:
type: object
description: Filter options for UUID fields (all operations)
properties:
equalTo:
type: string
format: uuid
description: Exact match
notEqualTo:
type: string
format: uuid
description: Not equal to
in:
type: array
items:
type: string
format: uuid
description: Matches any UUID in the array
notIn:
type: array
items:
type: string
format: uuid
description: Does not match any UUID in the array
isNull:
type: boolean
description: Field is null (true) or not null (false)
CarrierPaymentMethodFilter:
type: object
description: Filter criteria for carrier payment methods with AND/OR logic support
properties:
and:
type: array
description: All conditions must match (recursive)
items:
$ref: '#/components/schemas/CarrierPaymentMethodFilter'
or:
type: array
description: At least one condition must match (recursive)
items:
$ref: '#/components/schemas/CarrierPaymentMethodFilter'
not:
$ref: '#/components/schemas/CarrierPaymentMethodFilter'
description: Negates the filter
id:
$ref: '#/components/schemas/IDFilter'
carrierId:
$ref: '#/components/schemas/UUIDFilter'
paymentRecipientType:
$ref: '#/components/schemas/PaymentRecipientTypeFilter'
paymentMethodType:
$ref: '#/components/schemas/PaymentMethodTypeFilter'
status:
$ref: '#/components/schemas/StringFilter'
isPreferred:
$ref: '#/components/schemas/BooleanFilter'
email:
$ref: '#/components/schemas/StringFilter'
companyName:
$ref: '#/components/schemas/StringFilter'
bankName:
$ref: '#/components/schemas/StringFilter'
currency:
$ref: '#/components/schemas/StringFilter'
carrierFactorId:
$ref: '#/components/schemas/UUIDFilter'
paymentTermId:
$ref: '#/components/schemas/UUIDFilter'
createdAt:
$ref: '#/components/schemas/DatetimeFilter'
updatedAt:
$ref: '#/components/schemas/DatetimeFilter'
deletedAt:
$ref: '#/components/schemas/DatetimeFilter'
PaymentRecipientTypeFilter:
type: object
description: Filter for payment recipient type
properties:
equalTo:
$ref: '#/components/schemas/PaymentRecipientType'
notEqualTo:
$ref: '#/components/schemas/PaymentRecipientType'
in:
type: array
items:
$ref: '#/components/schemas/PaymentRecipientType'
notIn:
type: array
items:
$ref: '#/components/schemas/PaymentRecipientType'
PaymentMethodTypeFilter:
type: object
description: Filter for payment method type
properties:
equalTo:
$ref: '#/components/schemas/PaymentMethodType'
notEqualTo:
$ref: '#/components/schemas/PaymentMethodType'
in:
type: array
items:
$ref: '#/components/schemas/PaymentMethodType'
notIn:
type: array
items:
$ref: '#/components/schemas/PaymentMethodType'
UserReference:
type: object
description: 'Enhanced reference to a user resource (returned in responses).
Includes full user details in addition to id/key.
Note: Does NOT include nested references (teams, etc.) to prevent recursion.
Maximum nesting depth: 1 level.
'
required:
- id
- email
- status
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: User UUID
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference ID if set
example: ERP-USER-12345
email:
type: string
format: email
description: User's email address
example: john.doe@example.com
name:
type:
- string
- 'null'
description: User's full name
example: John Doe
phone:
type:
- string
- 'null'
description: User's phone number
example: +1-555-123-4567
phoneExt:
type:
- string
- 'null'
description: Phone extension
example: '123'
status:
type: string
description: User account status
enum:
- PENDING
- ACTIVE
- INACTIVE
example: ACTIVE
avatarId:
type:
- string
- 'null'
format: uuid
description: Profile avatar document ID
example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
createdAt:
type: string
format: date-time
description: When the user was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
description: When the user was last updated
example: '2025-01-15T14:30:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
description: When the user was soft deleted (null if active)
example: null
DatetimeFilter:
type: object
description: Filter options for datetime fields
properties:
equalTo:
type: string
format: date-time
description: Exact match
notEqualTo:
type: string
format: date-time
description: Not equal to
lessThan:
type: string
format: date-time
description: Before this datetime
lessThanOrEqualTo:
type: string
format: date-time
description: On or before this datetime
greaterThan:
type: string
format: date-time
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mvmnt/refs/heads/main/openapi/mvmnt-carrier-payment-methods-api-openapi.yml