Customer Payments

Reference for the customer_payments resource. Requests follow the conventions in Requests and Responses; fields you receive and may write are filtered by your user's permissions, so responses can contain a subset of the fields below.

Operations

Required on create: link customer under data.relationships — a create that omits it is rejected with 422 naming the relationship.

How it works

customer_payments are the payments recorded against a customer — cash, check, or a card/bank charge run through the payment gateway. Gated by Customer Payments at the customer's location.

Recording a payment is not the same as charging one

Creating a customer_payments row records a payment — it never contacts the payment gateway. POST to record, PATCH to edit, DELETE to remove. Actually charging a card/bank (and later voiding or refunding it) runs through the separate process/void/refund action, which is the only path that touches the gateway.

curl -X POST "https://portal.securitytrax.com/acme/user/v4/customer_payments" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"amount":"49.99","payment_date":"2026-07-15","customer_payment_type_id":3,"notes":"July check"},"relationships":{"customer":{"data":{"type":"customers","id":100}}}}}'

Processing, voiding, and refunding

Charging the gateway is a set of action endpoints — the only path that writes the gateway result fields. Each requires the Process Payment permission and returns the updated payment.

curl -X POST "https://portal.securitytrax.com/acme/user/v4/customer_payments/42/process" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"type":"sale","cvv":"123"}}}'

On success the response is the updated payment plus meta.auth_code and any gateway meta.messages. A gateway decline returns 422 with the reason (the payment stays unprocessed and can be retried). An action that isn't possible for the payment's current state — already processed, nothing refundable, no gateway enabled — returns 409; a permission failure returns 403. A recorded payment is charged at most once: re-processing an already-processed payment is a 409, so a retried request can never double-charge.

Read-only fields

The gateway result — transaction_id, authcode, processing_status, processed_at, is_refunded, is_voided, and the rest of the gateway_processing block — is read-only and visible only with the Process Payment permission. These are written by the gateway when a payment is processed, never by a client: a payment is "paid" only because it was actually charged, so you cannot set these on create/update to fake a paid payment. The system columns (tax, sale_type, check_number, posting dates, audit stamps) are read-only too.

Reading a customer's payments

The simplest read is on the parent: GET /customers/{id}?include=payments. You can also list directly: GET /customer_payments?customer_id={customerId} (filters: customer_id, customer_payment_type_id, customer_billing_id, cleared, payment_date/created_at ranges; sort: id, customer_id, payment_date, amount, created_at; ?count_only=true for the total).

Fields

Fields are grouped by the permission that gates them. A group you may not view is absent from responses; a group you may not write is rejected with 422 when sent in a write.

Payment

View: Customer Payments at the record's location. Create: Customer Payments at the record's location. Update: Customer Payments at the record's location.

Payment Meta

View: Customer Payments at the record's location.

Gateway Processing

View: Process Payment at the record's location.

Pagination

The list endpoint uses client-controlled offset pagination: ?page= (1-based) and ?per_page= (default 25, max 100). The response mirrors meta.pagination (page, per_page, total, last_page) and sends an RFC5988 Link header; follow rel="next" to walk pages. See Pagination.

Filters

The list endpoint accepts these query-param filters: customer_id, customer_payment_type_id, customer_billing_id, cleared, payment_date_from, payment_date_to, created_at_from, created_at_to. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../customer_payments?sort= orders the list by: id, customer_id, payment_date, amount, created_at. Prefix a field with - for descending; comma-separate for tie-breakers. An unsupported field returns 422. See Sorting collections.

Related

• Requests and Responses — envelope, errors, pagination, and rate limits.
• Authentication — tokens and the Authorization header.