Skip to main content
GET
/
v1
/
payments
List payments
curl --request GET \
  --url https://api-eu.flexportal.io/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Tenant-ID: <tenant-id>'
{
  "success": true,
  "payments": [
    {
      "paymentId": "<string>",
      "tenantId": "<string>",
      "customerId": "<string>",
      "subtotal": 1,
      "total": 1,
      "currency": "<string>",
      "paymentType": "individual",
      "billingPeriod": "<string>",
      "status": "pending",
      "idempotencyKey": "<string>",
      "dueDate": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "taxAmount": 0,
      "taxRate": 0,
      "amount": 1,
      "rentalId": "<string>",
      "billingGroupId": "<string>",
      "provider": "stripe",
      "transactionId": "<string>",
      "providerResponse": {},
      "manuallyMarked": false,
      "paymentReference": "<string>",
      "markedBy": "<string>",
      "captureAttempts": 0,
      "lastCaptureError": {
        "code": "<string>",
        "message": "<string>",
        "declineCode": "<string>"
      },
      "lineItems": [
        {
          "rentalId": "<string>",
          "description": "<string>",
          "amount": 1,
          "taxAmount": 0
        }
      ],
      "lateFeeApplied": false,
      "lateFeeAmount": 1,
      "originalAmount": 1,
      "notes": "<string>",
      "paidAt": "<string>",
      "lastCaptureAttempt": "<string>",
      "nextRetryAt": "<string>"
    }
  ],
  "count": 123,
  "hasMore": true,
  "nextCursor": "<string>"
}

​
Overview

Retrieve a paginated list of payments with optional filtering and sorting. Payments represent scheduled or completed billing transactions for subscriptions—they track when payments are due, their status, and when they were collected.

​
Payment Lifecycle

Scheduled → Pending → Processing → Paid/Failed/Cancelled
StatusDescription
pendingPayment scheduled, not yet attempted
processingPayment attempt in progress
paidPayment successfully collected
failedPayment attempt failed
cancelledPayment was cancelled

​
Common Use Cases

Accounts Receivable

Track pending payments and outstanding balances

Collection Dashboard

Monitor failed payments that need attention

Cash Flow Forecasting

Project upcoming revenue from scheduled payments

Customer Billing History

View payment history for specific customers

​
Filtering Payments

# Get pending payments
GET /v1/payments?status=pending

# Get failed payments that need attention
GET /v1/payments?status=failed

# Get payments for a specific customer
GET /v1/payments?customerId=cust_abc123

# Get payments for a subscription
GET /v1/payments?rentalId=sub_xyz789

# Get payments by due date range
GET /v1/payments?dueDateFrom=2025-01-01&dueDateTo=2025-01-31

# Get payments for a billing group
GET /v1/payments?billingGroupId=bg_abc123

​
Response Fields

Key fields in each payment object:
FieldDescription
paymentIdUnique payment identifier
statusCurrent payment status
customerIdCustomer ID
rentalIdAssociated subscription ID
billingGroupIdBilling group (if applicable)
amountPayment amount
currencyCurrency code (EUR, USD, etc.)
dueDateWhen payment is due
paidAtWhen payment was collected (if paid)
createdAtISO 8601 timestamp

​
Example: Get Outstanding Balance

async function getOutstandingBalance(customerId) {
  const { payments } = await listPayments({
    customerId,
    status: 'pending'
  });

  const total = payments.reduce((sum, p) => sum + p.amount, 0);

  return {
    customerId,
    pendingPayments: payments.length,
    totalOutstanding: total,
    currency: payments[0]?.currency || 'EUR'
  };
}

​
Example: Upcoming Revenue Forecast

async function getRevenueForecast(daysAhead) {
  const today = new Date();
  const futureDate = new Date(today.getTime() + daysAhead * 24 * 60 * 60 * 1000);

  const { payments } = await listPayments({
    status: 'pending',
    dueDateFrom: today.toISOString().split('T')[0],
    dueDateTo: futureDate.toISOString().split('T')[0]
  });

  return {
    period: `Next ${daysAhead} days`,
    expectedPayments: payments.length,
    expectedRevenue: payments.reduce((sum, p) => sum + p.amount, 0)
  };
}

Authorizations

​
Authorization
string
header
required

API key obtained from FlexPortal dashboard

Headers

​
Tenant-ID
string
required

Your tenant identifier

Query Parameters

​
limit
string

Items per page (default: 50, max: 100)

​
startAfter
string

Cursor for pagination

​
status
string

Filter by status (pending, processing, paid, failed, cancelled)

​
customerId
string

Filter by customer ID

​
rentalId
string

Filter by rental ID

​
billingGroupId
string

Filter by billing group ID

​
dueDateFrom
string

Filter by due date from (ISO 8601)

​
dueDateTo
string

Filter by due date to (ISO 8601)

Response

200 - application/json

List of payments

​
success
enum<boolean>
required
Available options:
true,
false
​
payments
object[]
required
​
count
number
required
​
hasMore
boolean
required
​
nextCursor
string | null
required