Payments

The Payment object represents a payment record in your Custom Trades CRM account.

View as Markdown

Endpoints

GET/api/v1/payments

GET/api/v1/payments/{uuid}

POST/api/v1/payments

PUT/api/v1/payments/{uuid}

DELETE/api/v1/payments/{uuid}

The Payment object

Attributes

uuidstring

Unique identifier for the payment

payment_numberstring |null

Payment number

invoice_uuidUUID

Invoice UUID (required)

customer_uuidUUID

Customer UUID

payment_typestring

Type: 'credit_card', 'ach', 'check', 'cash', 'other'

payment_methodstring |null

Payment method (e.g., 'visa', 'mastercard', 'bank_transfer')

amountnumber

Payment amount (required)

processing_feenumber

Processing fee

net_amountnumber

Net amount (amount - processing_fee)

payment_datestring

Payment date (YYYY-MM-DD format)

transaction_idstring |null

Transaction ID

reference_numberstring |null

Reference number (e.g., check number)

authorization_codestring |null

Authorization code (for credit cards)

payment_detailsJSONB |null

Additional payment details

notesstring |null

Notes

statusstring

Status: 'Pending', 'Completed', 'Failed', 'Refunded'

processed_atstring |null

Processing timestamp

created_by_user_idUUID

User ID who created the payment

created_atstring

ISO timestamp of creation

updated_atstring

ISO timestamp of last update

deleted_atstring |null

ISO timestamp of soft deletion (null if not deleted)

View as Markdown

THE PAYMENT OBJECT

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "payment_number": "PAY-001",
  "amount": 500,
  "payment_type": "credit_card",
  "status": "Completed",
  "payment_date": "2025-01-15",
  "invoice": {
    "uuid": "...",
    "invoice_number": "INV-001"
  }
}

List payments

Returns a paginated list of payments for your company.

Parameters

include_deleted(boolean, default: false)required

Include soft-deleted payments

invoice_uuid(UUID)

Filter by invoice

customer_uuid(UUID)

Filter by customer

payment_type(string)

Filter by payment type

status(string)

Filter by status

page(number, default: 1)required

Page number

limit(number, default: 50, max: 100)required

Items per page

GET/api/v1/payments

curl -G \
  https://customtradescrm.com/api/v1/payments?invoice_uuid=123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."

Response

{
  "success": true,
  "data": {
    "payments": [
      {
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "payment_number": "PAY-001",
        "amount": 500,
        "payment_type": "credit_card",
        "status": "Completed",
        "payment_date": "2025-01-15",
        "invoice": {
          "uuid": "...",
          "invoice_number": "INV-001"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    }
  }
}

Get a payment

Returns a specific payment by UUID with related invoice and customer information.

GET/api/v1/payments/{uuid}

curl -G \
  https://customtradescrm.com/api/v1/payments/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."

Create a payment

Creates a new payment record. **Request Body:**

Parameters

invoice_uuid(string)required

Invoice UUID (must belong to your company)

payment_type(string)required

Payment type ('credit_card', 'ach', 'check', 'cash', 'other')

amount(string)required

Payment amount (must be > 0)

payment_date(string)required

Payment date (YYYY-MM-DD format)

payment_method(string)

Payment method (e.g., 'visa', 'mastercard', 'bank_transfer')

processing_fee(string)

Processing fee (default: 0)

transaction_id(string)

Transaction ID

reference_number(string)

Reference number (e.g., check number)

authorization_code(string)

Authorization code (for credit cards)

payment_details(string)

JSONB object with additional details

notes(string)

Notes

POST/api/v1/payments

curl -G \

Response

{
  "invoice_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "payment_type": "credit_card",
  "payment_method": "visa",
  "amount": 500,
  "processing_fee": 15,
  "payment_date": "2025-01-15",
  "transaction_id": "txn_1234567890",
  "authorization_code": "AUTH123"
}

Update a payment

Updates a payment. All fields are optional (partial update). **Request Body:**

PUT/api/v1/payments/{uuid}

curl -G \

Response

{
  "status": "Completed",
  "processed_at": "2025-01-15T10:00:00Z"
}

Delete a payment

Soft deletes a payment (sets `deleted_at` timestamp).

Error codes

HTTP status code	Description
200	Success
400	Validation error
401	Unauthorized (invalid API key)
403	Forbidden (add-on required, IP restriction, or usage limit exceeded)
404	Payment not found
500	Server error

DELETE/api/v1/payments/{uuid}

curl -X DELETE \
  https://customtradescrm.com/api/v1/payments/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."