openapi: 3.1.0
info:
  title: FavePay Omni (FPO) Payments Transactions API
  version: v1
  description: FavePay Omni is Fave's partner payment API for accepting payments online or in-store. Partners create single-use QR codes or payment URLs, process customer-presented (merchant-scan) QR/barcodes, look up and list transactions, acknowledge them, and issue full or partial refunds. Transaction status changes are delivered via signed webhook callbacks. Every request is signed with HMAC-SHA256 using a secret key Fave issues during partner onboarding. Operates across Malaysia (MY), Singapore (SG) and Indonesia (ID).
  contact:
    name: Fave Partner Support
    url: https://developers.myfave.com/
  x-apievangelist:
    generated: '2026-07-19'
    method: generated
    source: https://developers.myfave.com/fpo-guide.html
    note: Faithfully generated from Fave's published partner documentation (FavePay Omni guide). No provider-published OpenAPI was found; this captures the documented endpoints, fields, auth and webhooks verbatim.
servers:
- url: https://omni.myfave.com
  description: Production
- url: https://omni.dino.fave.ninja
  description: Sandbox (test)
security:
- hmacSignature: []
tags:
- name: Transactions
  description: Look up, list, acknowledge and refund transactions.
paths:
  /api/fpo/v1/{country_code}/transactions:
    get:
      operationId: getTransaction
      tags:
      - Transactions
      summary: Retrieve a transaction by reference or receipt ID
      description: Look up a single transaction by either omni_reference or receipt_id.
      parameters:
      - $ref: '#/components/parameters/CountryCode'
      - name: app_id
        in: query
        required: true
        schema:
          type: string
      - name: omni_reference
        in: query
        required: false
        description: Required if receipt_id is not supplied.
        schema:
          type: string
      - name: receipt_id
        in: query
        required: false
        description: Required if omni_reference is not supplied.
        schema:
          type: string
      - name: outlet_id
        in: query
        required: false
        description: If supplied, must match the payment's outlet.
        schema:
          type: integer
      - name: sign
        in: query
        required: true
        description: HMAC-SHA256 signature over the request fields.
        schema:
          type: string
      responses:
        '200':
          description: Transaction found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: refundTransaction
      tags:
      - Transactions
      summary: Refund a successful payment
      description: Issues a full or partial refund against a successful payment. Refunds are typically allowed only on the same calendar day as the payment; later attempts return stale_transaction. Partial refunds cannot exceed charged_amount_cents and are unavailable for DuitNow/PayNow.
      parameters:
      - $ref: '#/components/parameters/CountryCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        '200':
          description: Refund processed (or already refunded).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/fpo/v1/{country_code}/transactions/{id}:
    post:
      operationId: acknowledgeTransaction
      tags:
      - Transactions
      summary: Acknowledge a transaction
      description: Marks a transaction as acknowledged so it is excluded from the unacknowledged list feed.
      parameters:
      - $ref: '#/components/parameters/CountryCode'
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcknowledgeRequest'
      responses:
        '200':
          description: Transaction acknowledged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/fpo/v1/{country_code}/outlets/{outlet_id}/transactions:
    get:
      operationId: listOutletTransactions
      tags:
      - Transactions
      summary: List recent transactions for an outlet
      description: Returns recent transactions for an outlet, most recent first. Supports a lookback window of up to ~31 days.
      parameters:
      - $ref: '#/components/parameters/CountryCode'
      - name: outlet_id
        in: path
        required: true
        schema:
          type: integer
      - name: app_id
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum records to return. Max 1000, default 10.
        schema:
          type: integer
          default: 10
          maximum: 1000
      - name: timestamp
        in: query
        required: false
        description: Unix timestamp (seconds) lower bound. Not earlier than ~31 days ago. When only limit is set, defaults to 30 days ago.
        schema:
          type: integer
      - name: ack
        in: query
        required: false
        description: true (default) returns all transactions; false returns only unacknowledged transactions.
        schema:
          type: boolean
          default: true
      - name: sign
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of transactions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    InternalError:
      description: Server failure (internal_error / unexpected_error).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid signature or outlet not linked to the integration.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Unknown app_id, missing transaction, or empty transaction history.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Invalid parameters (validation) or refund outside window (stale_transaction).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    CountryCode:
      name: country_code
      in: path
      required: true
      description: Market the request targets.
      schema:
        type: string
        enum:
        - MY
        - SG
        - ID
  schemas:
    RefundRequest:
      type: object
      required:
      - omni_reference
      - app_id
      - status
      - sign
      properties:
        omni_reference:
          type: string
        app_id:
          type: string
        status:
          type: string
          enum:
          - refunded
        partial_refund_cents:
          type: integer
          description: Optional partial amount; cannot exceed charged_amount_cents.
        sign:
          type: string
    Transaction:
      type: object
      properties:
        id:
          type: string
        receipt_id:
          type: string
        outlet_name:
          type: string
        total_amount_cents:
          type: integer
        payment_type:
          type: string
        payment_type_variant:
          type: string
        currency:
          type: string
        outlet_id:
          type: integer
        mid:
          type: string
        omni_reference:
          type: string
        status:
          type: string
          enum:
          - pending_payment
          - payment_processing
          - successful
          - disputed
          - rejected
          - refunded
        status_code:
          type: integer
          description: 0 pending_payment, 1 payment_processing, 2 successful, 3 disputed, 4 rejected, 5 refunded.
        created_at:
          type: string
        charged_amount_cents:
          type: integer
        campaign_credit_amount_cents:
          type: integer
        campaign_funded_by:
          type: string
        aabig_points_used_amount_cents:
          type: integer
        merchant_cashback_amount_cents:
          type: integer
        fave_credits_amount_cents:
          type: integer
        promo_code_value_cents:
          type: integer
        e_card_credits_used_cents:
          type: integer
        cashback_rate:
          type: number
        merchant_cashback_issued_cents:
          type: integer
        promo_code:
          type: string
        promo_code_cashback_value:
          type: number
        promo_code_cashback_type:
          type: string
        promo_code_cashback_issued_cents:
          type: integer
        promo_code_cashback_funded_by:
          type: string
        fave_fees_percentage:
          type: number
        fave_fees_cents:
          type: integer
        sst_on_total_fees_cents:
          type: integer
        merchant_takeback_cents:
          type: integer
        refund_amount_cents:
          type: integer
        user_id:
          type: string
        fpl_transaction:
          type: boolean
        fpl_fees_percentage:
          type: number
        fpl_fees_cents:
          type: integer
        fpl_merchant_cashback_reduction_percentage:
          type: number
        sign:
          type: string
          description: Present on webhook callback payloads for verification.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error code (e.g. validation, stale_transaction, resource_not_found, provider, internal_error, unexpected_error, failed_request, already_refunded).
        message:
          type: string
    AcknowledgeRequest:
      type: object
      required:
      - omni_reference
      - app_id
      - outlet_id
      - sign
      properties:
        omni_reference:
          type: string
        app_id:
          type: string
        outlet_id:
          type: integer
        sign:
          type: string
  securitySchemes:
    hmacSignature:
      type: apiKey
      in: query
      name: sign
      description: HMAC-SHA256 signature computed over the URL-encoded request fields in submission order (excluding sign and country_code, and excluding outlet_id on list, id on acknowledge, and details on merchant scan), keyed by the secret Fave issued for the integration. On POST requests the signature is passed as the sign field in the request body.