Payments API Documentation

Overview

This collection contains the payments recorded against your organization's invoices. A payment represents a single attempt to pay (or refund) an invoice using a particular method, such as a card transaction, a cash payment recorded at the point of sale, an account-credit deduction, or a voucher redemption.

Note that there is no separate "invoice" collection in the API; the fields most commonly needed from the parent invoice (description, line items, customer, location, staff member, discounts, and revenue accounts) are denormalized onto each payment.

This collection is read-only: only the list and read operations are supported. Results are ordered by creation time, newest first.

Only payments with a status of COM, PRO, FAI, PRF, or REF are returned. Pending (PEN) and cancelled (CAN) payments are never listed. See Statuses.

Fields

All fields are read-only.

Name Type Description
id integer The unique identifier of the payment. This is placed in the URL when making API calls for the payment.
url string (URL) The unique API URL of the payment.
status string The status of the payment. One of the statuses.
failure_message string A human-readable reason for failure. Blank unless the payment failed.
amount string (decimal) The amount paid toward the invoice, to two decimal places. Voucher redemptions are recorded as 0.
amount_pre_tax string (decimal) The portion of amount excluding tax (amount minus tax_amount).
tax_amount string (decimal) The tax portion of this payment. For a partial payment, the tax is prorated against the invoice total.
amount_refunded string (decimal) The amount that has been refunded from this payment. Defaults to 0.
payment_type string The payment method or processor used. One of the payment types.
payment_method_type string The broad category of payment instrument used. One of the payment method types.
credit_card_last4 string The last four digits of the card, if a card was used.
credit_card_brand string The brand of the card (e.g. "Visa"), if a card was used.
bank_account_last4 string The last four digits of the bank account, if a bank account was used.
bank_account_bank_name string The name of the bank, if a bank account was used.
created_date string (ISO-8601 date) The calendar date the payment was created, in the local time of the location's organization.
invoice_id integer The identifier of the invoice this payment was made against.
invoice_description string The description of the invoice this payment was made against.
line_items list of JSON objects The line items of the invoice this payment was made against. See the line item object for the object specification.
customer_id integer or null The identifier of the customer this payment is attributed to. Null for anonymous payments not linked to a customer.
customer_first_name string or null The first name of the linked customer.
customer_last_name string or null The last name of the linked customer.
customer_email string or null The email address of the linked customer.
customer_birthday string (ISO-8601 date) or null The birthday of the linked customer.
discount_amount string (decimal) or null The total discount applied to the parent invoice.
discount_code string A comma-separated list of the discount codes applied to the invoice. Empty if none.
discount_name string A comma-separated list of the discount names applied to the invoice. Empty if none.
discount_display_name string A comma-separated list of display names for the discounts applied to the invoice, falling back to the code where a discount has no name.
revenue_account_codes JSON object A mapping of revenue account code to the fraction of the invoice attributed to that account.
location_id integer or null The identifier of the location the parent invoice belongs to.
location_name string or null The name of the location the parent invoice belongs to.
staff_user_id integer or null The identifier of the staff member who created the invoice. Null for self-service purchases made through the Climber App.
staff_user_first_name string or null The first name of the staff member who created the invoice.
staff_user_last_name string or null The last name of the staff member who created the invoice.
staff_user_email string or null The email address of the staff member who created the invoice.
stripe_payment_intent_id string The Stripe PaymentIntent identifier, for payments processed through Stripe.
gravity_external_transaction_id string The external transaction identifier, for payments processed through Gravity Payments.
gravity_unique_transaction_id string The unique transaction identifier, for completed payments processed through Gravity Payments.
mx_merchant_payment_link_name string The MX Merchant payment-link name, for payments processed through MX Merchant.
mx_merchant_payment_link_id string The MX Merchant payment-link identifier, for payments processed through MX Merchant.
mx_merchant_payment_id string The MX Merchant payment identifier, populated when an MX Merchant payment completes.
gift_card_number string The gift card number used, for gift-card payments.
created_at string (ISO-8601 datetime) When the payment was created, as a UTC timestamp. This is the field that created_at_min / created_at_max filter on, and the field results are ordered by.
updated_at string (ISO-8601 datetime) When the payment's record in the Capitan database was last updated, as a UTC timestamp.

Line Item Object

Each entry in a payment's line_items list is a JSON object with the following fields:

Name Type Description
id integer The unique identifier of the invoice line item.
purchase_type string The kind of product the line item represents. One of the purchase types.
description string The customer-facing description of the product.
amount number The amount of the line item attributable to this payment, including tax. For a partial payment, this is prorated by the payment amount as a fraction of the invoice total, so it may be a non-rounded value and may not equal the full line item price.

Payment Types

Name Syntax
StripeSTR
Gravity PaymentsGRA
MX MerchantMXM
SquareSQU
Lightspeed (point of sale)VEN
Account CreditCRE
VoucherVOU
Offline / RecordedOFF
POS Gift CardPGI
Migrated (imported from legacy software)MIG
Mock (test)MOK
N/ANA

Payment Method Types

Name Syntax
N/ANA
CardCRD
Bank AccountBNK

Statuses

Only the bolded statuses are ever returned by this collection.

Name Syntax Returned?
Payment PendingPENNo
Payment ProcessingPROYes
Payment CompleteCOMYes
Payment FailedFAIYes
Partially RefundedPRFYes
RefundedREFYes
CancelledCANNo

Line Item Purchase Types

Name Syntax
Event BookingBOO
Membership (Initial)MIN
Membership (Fix Failed Payment)MFA
Membership (Recurring)MRE
Membership (Prepaid Freeze Fee)MFR
Membership (Add-on Change Fee)MAC
Entry PassEPA
Voucher PackVPO
Event VoucherEVV
GiftGIF
GenericGEN
LegacyLEG

Filters

See the filtering documentation for more information on how to use filters in the Capitan API.

Name Syntax Description
Minimum Created Date created_at_min Filters for payments created on or after the given date (in the local time of your organization). Accepts an ISO-8601 date (YYYY-MM-DD); the boundary is the start of that day in your organization's time zone.
Maximum Created Date created_at_max Filters for payments created on or before the given date (in the local time of your organization). The given date is inclusive of its whole local day.
General Search search Filters for payments matching the given search terms. Each space-separated term must match; terms are matched against the invoice ID, invoice description, and the linked customer's email, first name, last name, and preferred name.
Payment Method payment_method_in Filters for payments whose payment type is one of the given comma-separated codes. For example, STR,VEN.
Minimum Amount amount_min Filters for payments with an amount greater than or equal to the given value.
Maximum Amount amount_max Filters for payments with an amount less than or equal to the given value.
Status status_in Filters for payments whose status is one of the given comma-separated codes. This narrows within the returned statuses only.
Discount Association discount_association_id Filters for payments whose invoice has a discount belonging to the given discount association ID.
Location location_id Filters for payments whose invoice belongs to the given location ID.
Has No Linked Customer does_not_have_linked_customer If true, filters for payments with no linked customer; if false, filters for payments that have a linked customer.
Stripe Payment Intent ID stripe_payment_intent_id Filters for the payment with the exact given Stripe PaymentIntent ID.
Gravity External Transaction ID gravity_external_transaction_id Filters for the payment with the exact given Gravity Payments external transaction ID.

Operations

List

Request
GET /api/payments/

Response
200 OK
{
    "count": 312,
    "next": "https://api.hellocapitan.com/api/payments/?page=2",
    "previous": null,
    "results": [
        {
            "id": 184320,
            "url": "https://api.hellocapitan.com/api/payments/184320/",
            "status": "COM",
            "amount": "45.00",
            "amount_pre_tax": "40.91",
            "tax_amount": "4.09",
            "amount_refunded": "0.00",
            "payment_type": "STR",
            "payment_method_type": "CRD",
            "credit_card_last4": "4242",
            "credit_card_brand": "Visa",
            "created_date": "2026-06-15",
            "invoice_id": 90211,
            "invoice_description": "Day Pass + Gear Rental",
            "line_items": [
                {"id": 553201, "purchase_type": "EPA", "description": "Adult Day Pass", "amount": 25.00},
                {"id": 553202, "purchase_type": "GEN", "description": "Shoe Rental", "amount": 20.00}
            ],
            "customer_id": 73188,
            "customer_first_name": "Alex",
            "customer_last_name": "Stone",
            "customer_email": "alex.stone@example.com",
            "location_id": 12,
            "location_name": "Downtown",
            "created_at": "2026-06-15T18:42:07.512345Z",
            "updated_at": "2026-06-15T18:42:09.001220Z",
            ...
        },
        ...
    ]
}

Read

Request
GET /api/payments/184320/

Response
200 OK
{
    "id": 184320,
    "url": "https://api.hellocapitan.com/api/payments/184320/",
    "status": "COM",
    "amount": "45.00",
    ...
}

Pulling Recent Payments

The created_at_min and created_at_max filters operate at whole-day granularity, with day boundaries taken in your organization's local time zone. To retrieve a single day's payments, set both to the same date: 

GET /api/payments/?created_at_min=2026-06-15&created_at_max=2026-06-15&page_size=100

Each result also includes a precise UTC created_at timestamp, which can be used to narrow to an exact window on the client side. When polling daily, pulling a slightly overlapping window (for example, the previous two days) and de-duplicating on the payment id avoids missing records near the day boundary. Page through results using the next link until it is null; see the pagination documentation.