Payments Query

Note: The Teachify Admin API is currently under development and not yet available for public use. This documentation is provided for preview purposes only.

Overview

The Payments API allows you to retrieve information about payments in your school. Payments represent financial transactions made by users when purchasing courses, memberships, events, digital downloads, and other products. This API provides access to payment details, refund information, and filtering capabilities.

Available Queries

payments

Returns a paginated list of payments for the authenticated school.

Parameters:

Parameter	Type	Description
filter	AdminPaymentFilter	Filter criteria (see Filtering)
page	Int	Page number for pagination
perPage	Int	Number of items per page (default: 20, max: 50)
limit	Int	Alternative to perPage

Returns:

• AdminPaymentPage object with:
  • nodes: Array of AdminPayment objects
  • currentPage: Current page number
  • hasNextPage: Whether there are more pages
  • hasPreviousPage: Whether there are previous pages
  • nodesCount: Total number of items across all pages
  • totalPages: Total number of pages

Example:

query {
  payments(
    filter: {
      paymentState: { eq: "paid" },
      paidAt: { gte: 1704067200 }
    },
    page: 1,
    perPage: 10
  ) {
    nodes {
      id
      tradeNo
      amount
      currency
      paymentType
      paidAt
      user {
        id
        email
        name
      }
      lineitems {
        name
        amount
        itemType
      }
    }
    currentPage
    hasNextPage
    hasPreviousPage
    nodesCount
    totalPages
  }
}

AdminPayment Object

The AdminPayment object contains the following fields:

Field	Type	Description
id	String!	Unique identifier
user	AdminUser!	The user who made the payment
tradeNo	String	Unique trade/transaction number from the payment gateway
currency	String!	Currency code (e.g., TWD, USD) in ISO 4217 format
currencySymbol	String!	Currency symbol (e.g., $, NT$)
amount	Float!	Payment amount
refundedAmount	Float	Amount that has been refunded
refundAmount	Float!	Returns the refund amount if the payment is refunding, otherwise returns the refunded amount
discountAmount	Float	Discount amount applied to this payment
paymentType	String	Payment method (e.g., credit, atm, cvs, web_atm, barcode, line_pay)
paidAt	Int	Unix timestamp when the payment was completed
refundedAt	Int	Unix timestamp when the payment was refunded
expiredAt	Int	Unix timestamp when the payment expired
affiliateCode	String	Affiliate tracking code, if applicable
remark	String	Additional remarks or notes
lineitems	[Lineitem]	List of purchased items in this payment
invoice	Invoice	Associated invoice, if issued
installment	Int	Installment period for credit card payments, if applicable
createdAt	Int!	Unix timestamp when the payment record was created
updatedAt	Int!	Unix timestamp when the payment record was last updated

Filtering

The payments query supports filtering through the filter parameter. The following filter fields are available:

Filter Field	Type	Description
id	StringOperator	Filter by payment ID
amount	FloatOperator	Filter by payment amount
paymentState	StringOperator	Filter by payment state (not_paid, paid, expired, failed, manual_enrolled, refunding, refunded)
paidAt	IntOperator	Filter by payment timestamp (Unix timestamp)
refundedAt	IntOperator	Filter by refund timestamp (Unix timestamp)
createdAt	IntOperator	Filter by creation timestamp (Unix timestamp)
tradeNo	StringOperator	Filter by trade/transaction number

StringOperator Filters

Operator	Description	Example
eq	Equal to	{ tradeNo: { eq: "T20250101001" } }
neq	Not equal to	{ paymentState: { neq: "expired" } }
in	In a list of values	{ paymentState: { in: ["paid", "refunding"] } }
nin	Not in a list of values	{ paymentState: { nin: ["expired", "failed"] } }
like	Contains substring (case-sensitive)	{ tradeNo: { like: "T2025" } }
contains	Contains substring (case-insensitive)	{ tradeNo: { contains: "T2025" } }

IntOperator Filters

Operator	Description	Example
eq	Equal to	{ paidAt: { eq: 1704067200 } }
gt	Greater than	{ paidAt: { gt: 1704067200 } }
gte	Greater than or equal	{ paidAt: { gte: 1704067200 } }
lt	Less than	{ paidAt: { lt: 1735689600 } }
lte	Less than or equal	{ paidAt: { lte: 1735689600 } }

FloatOperator Filters

Operator	Description	Example
eq	Equal to	{ amount: { eq: 999.0 } }
gt	Greater than	{ amount: { gt: 500.0 } }
gte	Greater than or equal	{ amount: { gte: 500.0 } }
lt	Less than	{ amount: { lt: 2000.0 } }
lte	Less than or equal	{ amount: { lte: 2000.0 } }

Filter Examples

Find all paid payments in a date range:

query {
  payments(
    filter: {
      paymentState: { eq: "paid" },
      paidAt: { gte: 1704067200, lte: 1735689600 }
    }
  ) {
    nodes {
      id
      tradeNo
      amount
      currency
      paidAt
      user {
        id
        email
      }
    }
  }
}

Find refunded payments in a specific period:

query {
  payments(
    filter: {
      paymentState: { eq: "refunded" },
      refundedAt: { gte: 1704067200, lte: 1735689600 }
    }
  ) {
    nodes {
      id
      tradeNo
      amount
      refundedAmount
      refundedAt
      user {
        id
        email
      }
    }
  }
}

Look up a specific payment by trade number:

query {
  payments(
    filter: {
      tradeNo: { eq: "T20250101001" }
    }
  ) {
    nodes {
      id
      tradeNo
      amount
      currency
      paymentType
      paidAt
    }
  }
}

Find high-value payments:

query {
  payments(
    filter: {
      paymentState: { in: ["paid", "refunding"] },
      amount: { gte: 10000.0 }
    }
  ) {
    nodes {
      id
      amount
      currency
      paymentType
      user {
        id
        name
        email
      }
    }
  }
}

Relationships

The Payment API relates to:

• Users: Each payment belongs to a user
• Lineitems: A payment contains one or more line items representing purchased products
• Invoices: A payment may have an associated invoice

Detailed Query Structure

Below is a comprehensive view of fields available in the payments query:

query {
  payments(
    filter: {
      id: { eq: "payment_123" }              # Filter by ID (StringOperator)
      amount: { gte: 100.0 }                 # Filter by amount (FloatOperator)
      paymentState: { eq: "paid" }           # Filter by state (StringOperator)
      paidAt: { gte: 1704067200 }            # Filter by paid timestamp (IntOperator)
      refundedAt: { gte: 1704067200 }        # Filter by refund timestamp (IntOperator)
      createdAt: { gte: 1704067200 }         # Filter by creation timestamp (IntOperator)
      tradeNo: { eq: "T20250101001" }        # Filter by trade number (StringOperator)
    },
    page: 1,                                  # Page number (Int)
    perPage: 20                               # Items per page (Int)
  ) {
    nodes {
      id                                      # Unique identifier (String!)
      tradeNo                                 # Trade/transaction number (String)

      # Financial information
      amount                                  # Payment amount (Float!)
      currency                                # Currency code (String!)
      currencySymbol                          # Currency symbol (String!)
      discountAmount                          # Discount applied (Float)
      refundedAmount                          # Amount refunded (Float)
      refundAmount                            # Current refund amount (Float!)

      # Payment details
      paymentType                             # Payment method (String)
      installment                             # Credit card installment period (Int)
      affiliateCode                           # Affiliate tracking code (String)
      remark                                  # Additional notes (String)

      # Timestamps (Unix)
      paidAt                                  # When payment was completed (Int)
      refundedAt                              # When payment was refunded (Int)
      expiredAt                               # When payment expired (Int)
      createdAt                               # When record was created (Int!)
      updatedAt                               # When record was last updated (Int!)

      # Related objects
      user {                                  # Payment user (AdminUser!)
        id
        email
        name
      }
      lineitems {                             # Purchased items ([Lineitem])
        name
        amount
        itemType
      }
      invoice {                               # Associated invoice (Invoice)
        id
        number
        state
      }
    }

    # Pagination information
    currentPage                               # Current page number (Int!)
    hasNextPage                               # Whether there are more pages (Boolean!)
    hasPreviousPage                           # Whether there are previous pages (Boolean!)
    nodesCount                                # Total number of items across all pages (Int!)
    totalPages                                # Total number of pages (Int!)
  }
}