> ## Documentation Index
> Fetch the complete documentation index at: https://docs.singapay.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Track, monitor, and reconcile every payment received through your Payment Links — each recorded as an individual Payment Link History.

Every time a customer completes a payment through a Payment Link URL, Singapay creates a **Payment Link History** record. This API lets you list, filter, and inspect those records for reconciliation, reporting, and customer support.

<CardGroup cols={3}>
  <Card title="Per-payment records" icon="receipt">
    Every payment through a link creates its own history entry with status, amount, and method.
  </Card>

  <Card title="Full fee breakdown" icon="chart-bar">
    Each record shows vendor fee, platform margin, and net amount received.
  </Card>

  <Card title="Filterable & searchable" icon="magnifying-glass">
    Query by reference number, method, status, amount, or date range.
  </Card>
</CardGroup>

***

## Relationship with Payment Link

A Payment Link is the **parent** — the reusable URL and its configuration. Each time a customer pays through it, a Payment Link History **child** record is created.

<Info>
  **Example:** Payment Link `https://singapay.com/b2b/INV-2024-001`

  | History | Amount      | Method | Date  |
  | ------- | ----------- | ------ | ----- |
  | #1      | IDR 500,000 | VA BRI | Jan 1 |
  | #2      | IDR 500,000 | QRIS   | Jan 2 |
  | #3      | IDR 500,000 | GoPay  | Jan 3 |

  One Payment Link → multiple independent history records.
</Info>

***

## Transaction lifecycle

<Steps>
  <Step title="Customer opens the link">
    Customer accesses the Payment Link URL and views the payment page with item details.
  </Step>

  <Step title="Selects a payment method">
    Customer chooses from the available methods configured for that link (VA, QRIS, or E-Wallet).
  </Step>

  <Step title="History record created">
    A Payment Link History record is created immediately with status `pending`.
  </Step>

  <Step title="Customer completes payment">
    Customer pays via the selected method. The bank or payment provider sends a notification to Singapay.
  </Step>

  <Step title="Processing and reconciliation">
    Singapay validates the payment and reconciles the transaction. Status updates to `paid`.
  </Step>

  <Step title="Settlement">
    Funds are settled to your account (bank or Singapay Balance) based on your configured settlement method.
  </Step>
</Steps>

***

## Payment status

| Status    | Description                                             |
| --------- | ------------------------------------------------------- |
| `pending` | History record created, awaiting payment from customer. |
| `paid`    | Payment confirmed and reconciled by Singapay.           |
| `settled` | Funds transferred to your account.                      |

***

## Important notes

<AccordionGroup>
  <Accordion title="Multiple payment methods per link" icon="credit-card">
    A single Payment Link can receive payments via different methods (VA, QRIS, E-Wallet). Each payment is recorded as a separate history entry regardless of method used.
  </Accordion>

  <Accordion title="Customer information capture" icon="address-card">
    If customer detail collection is enabled on the Payment Link, name, email, and phone are captured and stored in each history record.
  </Accordion>

  <Accordion title="Fee breakdown per transaction" icon="receipt">
    Every history record includes the payment method used, vendor fee, platform margin, and net amount received — ready for accounting reconciliation.
  </Accordion>

  <Accordion title="QRIS special handling" icon="qrcode">
    For QRIS payments, additional MDR (Merchant Discount Rate) information is recorded in the history entry alongside standard fields.
  </Accordion>

  <Accordion title="Filtering and search" icon="filter">
    Query histories by `reff_no`, `status`, `payment_method_name`, `amount`, date ranges (`created_at_from` / `created_at_to`), and settlement dates. Default sort is newest first.
  </Accordion>

  <Accordion title="Data retention" icon="database">
    History records are retained for **1 year**. Data older than 1 year is archived and may not be accessible via the API.
  </Accordion>
</AccordionGroup>

***

## Available endpoints

<CardGroup cols={2}>
  <Card title="List Payment Link Histories" icon="list" href="./list">
    Paginated list of history records for an account with full filter support.
  </Card>

  <Card title="Show Payment Link History" icon="eye" href="./show">
    Retrieve a single history record by ID.
  </Card>
</CardGroup>

<Note>
  All endpoints require authentication. See [Authentication](/api-reference/authentication).
</Note>