Introduction

Pockyt provides a set of transaction management endpoints that allow merchants to look up individual transactions, retrieve transaction lists in bulk, and attach supplementary notes to transaction records. These endpoints work across all payment types — online checkout, in-store, and refund transactions.

The queries and reporting workflow supports three key functions:

1. Single Transaction Query: Retrieve the full details and current status of a specific transaction using its transactionNo or reference.
2. Bulk Transaction List: Pull a filtered list of transactions for reconciliation, reporting, or audit purposes.
3. Transaction Notes: Add notes and supplementary data to existing transaction records for internal tracking and documentation.

---

API Overview

sequenceDiagram
    participant MB as Merchant Backend
    participant PA as Pockyt API

    Note over MB: Query Single Transaction
    MB->>PA: POST /app-data-search/v3/tran-query
    PA-->>MB: Transaction details (status, amount, etc.)

    Note over MB: Query Transactions in Bulk
    MB->>PA: POST /app-data-search/v3/transaction-list
    PA-->>MB: Filtered transaction list

    Note over MB: Add Notes to Transaction
    MB->>PA: POST /app-data-search/v3/notes/add
    PA-->>MB: Confirmation

---

Endpoints

Query Specific Transaction

Endpoint: POST /app-data-search/v3/tran-query

Action: Retrieve the full details of a single transaction by providing either the transactionNo (Pockyt's transaction identifier) or the reference (the merchant's own invoice or order number).

This is the most commonly used query endpoint. Typical use cases include:

• Webhook fallback: If the webhook notification is delayed or not received, poll this endpoint to confirm payment status before updating the order.
• Pre-refund verification: Confirm a transaction has a "success" status before initiating a refund.
• Customer support: Look up transaction details when handling customer inquiries.

📘

API Reference: Query Specific Transactions

---

Query Transactions in Bulk

Endpoint: POST /app-data-search/v3/transaction-list

Action: Retrieve a filtered list of transactions based on criteria such as date range, status, or store. This endpoint is designed for reconciliation workflows and reporting.

Typical use cases include:

• Daily reconciliation: Pull all transactions for a given date to match against internal records.
• Settlement verification: Cross-reference transaction totals with settlement amounts.
• Custom reporting: Generate filtered exports for accounting, compliance, or business intelligence.

📘

API Reference: Query Transaction List

---

Add Notes to Transaction

Endpoint: POST /app-data-search/v3/notes/add

Action: Attach supplementary notes or metadata to an existing transaction record. Notes are stored alongside the transaction and are visible in the Pockyt dashboard.

Typical use cases include:

• Internal documentation: Record the reason for a refund, a customer service interaction, or an exception case.
• Audit trail: Attach compliance-related notes or approval references to specific transactions.
• Operational context: Add context that helps your team understand why a transaction was handled a certain way.

📘

API Reference: Add Notes to Transaction

---

Key Considerations

1. Cross-Flow Compatibility: These endpoints work across all Pockyt payment types. Whether the original transaction was an online checkout, an in-store QRC payment, or a refund, you can query and annotate it using the same endpoints.

2. Lookup by Reference or TransactionNo: The tran-query endpoint accepts either the Pockyt-generated transactionNo or the merchant's own reference value. Use whichever identifier your system tracks — both resolve to the same transaction.

3. Error Handling: A ret_code of 000100 indicates success on all Pockyt API responses. If a transactionNo or reference does not match any existing record, the API returns an error response. See Status & Error Codes for the complete reference.