openapi: 3.1.0
info:
  title: PayFast Credit Card Transactions Transaction History API
  description: 'South African payment gateway providing REST APIs for online payment processing, subscription billing, tokenized recurring card payments, onsite checkout, and merchant refunds. Trusted by 80,000+ South African businesses and certified PCI-DSS Level 1.

    '
  version: v1
  contact:
    name: PayFast Developer Support
    url: https://support.payfast.help
  license:
    name: Proprietary
    url: https://payfast.io
servers:
- url: https://api.payfast.co.za/v1
  description: Production API server
- url: https://sandbox.payfast.co.za/v1
  description: Sandbox / test server
security:
- merchantAuth: []
tags:
- name: Transaction History
  description: Query merchant transaction history with date range and aggregations
paths:
  /transactions/history:
    get:
      operationId: getTransactionHistoryRange
      summary: Get transaction history for a date range
      description: 'Retrieve a list of transactions for the authenticated merchant within a specified date range. Results are paginated via offset and limit.

        '
      tags:
      - Transaction History
      parameters:
      - name: from
        in: query
        description: Start date of the range (YYYY-MM-DD). Defaults to today.
        schema:
          type: string
          format: date
        example: '2026-06-01'
      - name: to
        in: query
        description: End date of the range (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-06-30'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Transaction list returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transactions/history/daily:
    get:
      operationId: getDailyTransactionHistory
      summary: Get daily transaction summary
      description: Retrieve a daily aggregated summary of transactions for a given date.
      tags:
      - Transaction History
      parameters:
      - name: date
        in: query
        required: true
        description: The date to retrieve the daily summary for (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-06-12'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Daily summary returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transactions/history/weekly:
    get:
      operationId: getWeeklyTransactionHistory
      summary: Get weekly transaction summary
      description: Retrieve a weekly aggregated summary of transactions for the week containing the specified date.
      tags:
      - Transaction History
      parameters:
      - name: date
        in: query
        required: true
        description: A date within the desired week (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-06-09'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Weekly summary returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transactions/history/monthly:
    get:
      operationId: getMonthlyTransactionHistory
      summary: Get monthly transaction summary
      description: Retrieve a monthly aggregated summary of transactions for the specified month.
      tags:
      - Transaction History
      parameters:
      - name: date
        in: query
        required: true
        description: Year and month (YYYY-MM)
        schema:
          type: string
          pattern: ^\d{4}-\d{2}$
        example: 2026-06
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Monthly summary returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Transaction:
      type: object
      description: A single merchant transaction record
      properties:
        m_payment_id:
          type: string
          description: Merchant payment reference ID
          example: order-1234
        pf_payment_id:
          type: string
          description: PayFast internal payment ID
          example: '1124148'
        payment_status:
          type: string
          description: Payment status
          enum:
          - COMPLETE
          - FAILED
          - PENDING
          example: COMPLETE
        item_name:
          type: string
          description: Item name
          example: Premium subscription
        item_description:
          type: string
          description: Item description
          example: Monthly premium plan
        amount_gross:
          type: number
          format: float
          description: Gross transaction amount (ZAR)
          example: 99.0
        amount_fee:
          type: number
          format: float
          description: PayFast fee (ZAR)
          example: 2.97
        amount_net:
          type: number
          format: float
          description: Net amount received by merchant (ZAR)
          example: 96.03
        buyer_first_name:
          type: string
          description: Buyer first name
          example: Jane
        buyer_last_name:
          type: string
          description: Buyer last name
          example: Smith
        buyer_email_address:
          type: string
          format: email
          description: Buyer email address
          example: jane.smith@example.com
        token:
          type: string
          format: uuid
          description: Subscription or tokenization token (if applicable)
          example: dc0521d3-55fe-269b-fa00-b647310d760f
        billing_date:
          type: string
          format: date
          description: Billing date
          example: '2026-06-01'
        payment_method:
          type: string
          description: Payment method used
          example: cc
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: HTTP error code
          example: 400
        status:
          type: string
          description: Error status
          example: failed
        data:
          type: object
          properties:
            response:
              type: string
              description: Error message
              example: Required "token" parameter missing
    TransactionHistoryResponse:
      type: object
      description: Merchant transaction history results
      properties:
        code:
          type: integer
          example: 200
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            response:
              type: array
              items:
                $ref: '#/components/schemas/Transaction'
  responses:
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — invalid or missing merchant authentication signature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    offset:
      name: offset
      in: query
      description: Pagination offset (number of records to skip)
      schema:
        type: integer
        minimum: 0
        default: 0
      example: 0
    limit:
      name: limit
      in: query
      description: Maximum number of records to return
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 1000
      example: 100
  securitySchemes:
    merchantAuth:
      type: apiKey
      in: header
      name: merchant-id
      description: 'PayFast API authentication uses an MD5 signature derived from the merchant ID, passphrase, timestamp, and request data. Required headers include merchant-id, version, timestamp, and signature.

        '