Simplifi/Simplifipay Transaction API

openapi: 3.2.0
info:
  title: SimpliFi Cards Transaction API
  version: 1.0.0
  description: 'SimpliFi Cards-as-a-Service API for issuing and managing virtual and physical cards across the GCC. Covers authentication (JWT), card programs, funding sources, cards, users, transactions, fees, rule groups, and webhook management. SimpliFi uses an asynchronous architecture: API calls return 2xx on receipt and final outcomes are delivered via webhooks.'
  contact:
    name: SimpliFi Support
    email: info@simplifipay.com
    url: https://apidoc.simplifipay.com/
servers:
- url: https://{env}-lb.simplifipay.com
  description: Load-balanced API host; {env} is the environment token issued during onboarding
  variables:
    env:
      default: uat
      description: Environment token issued by SimpliFi
security:
- bearerAuth: []
tags:
- name: Transaction
paths:
  /v1/transaction:
    post:
      summary: List All Transactions
      deprecated: false
      description: 'The List All Transactions endpoint retrieves a paginated array of all the transactions carried

        out in the last 90 days. The results are displayed with a default page size of 10 and the response

        returns the transaction list with total no. of elements. Following are the properties of this endpoint.'
      tags:
      - Transaction
      parameters:
      - name: Authorization
        in: header
        description: This field contains the JWT token that is used to authenticate the user.
        required: true
        example: ''
        schema:
          type: string
          allowEmptyValue: false
      - name: requestUuid
        in: header
        description: 'A unique id is required to be passed as part of the header whenever a SimpliFi API is called from your

          system. This would help us in debugging in case of a discrepancy in the expected behavior of the API.'
        required: true
        example: ''
        schema:
          type: string
          allowEmptyValue: false
          minLength: 20
          maxLength: 40
          examples:
          - 00d366f2-a6e9-4714-b172-02c4e58c29d8
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequestModel'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
          headers: {}
        '400':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                type: object
                properties: {}
          headers: {}
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                type: object
                properties: {}
          headers: {}
      security:
      - bearerAuth: []
      operationId: listAllTransactions
components:
  schemas:
    TransactionUuidParameter:
      type: string
      description: This is a unique identifier of the transaction.
      examples:
      - f0888e10-43e3-4686-9c79-256633d79559
    TransactionRequestModel:
      type: object
      properties:
        cardProgramUuids:
          type: array
          description: These are unique identifiers of the card programs.
          items:
            type: string
        page:
          description: This field contains the page number currently being displayed for transactions.
          type: integer
        size:
          description: This field contains the number of the transaction records to be displayed on this page.
          type: integer
        startDate:
          description: This is the start date of transactions.
          type: string
          format: date-time
          examples:
          - '2025-02-28 13:31:00'
        endDate:
          description: This is the end date of transactions.
          type: string
          format: date-time
          examples:
          - '2025-02-28 13:31:00'
        cardUuid:
          description: This is a unique identifier of the card.
          type: string
        userUuid:
          description: This is a unique identifier of the user.
          type: string
        billAmount:
          description: This field contains the billed amount.
          type: number
        billCurrency:
          description: This field contains the currency in which the amount has been billed.
          type: string
        classificationType:
          description: This field contains the classification type of the transaction.
          type: string
        sortBy:
          type: string
          enum:
          - transactionDate
          - transactionAmount
        sortDirection:
          type: string
          enum:
          - ASC
          - DESC
        transactionType:
          $ref: '#/components/schemas/TransactionTypeParameter'
    TransactionResponseDetails:
      type: object
      properties:
        transactionUuid:
          $ref: '#/components/schemas/TransactionUuidParameter'
        transactionId:
          $ref: '#/components/schemas/TransactionIdParameter'
        cardUuid:
          type: string
          description: This is a unique identifier of the card.
          examples:
          - 95e8008f-c14b-4d4c-bc3b-6378be83618c
        maskedPan:
          $ref: '#/components/schemas/MaskedPanParameter'
        userName:
          type: string
          description: username of user.
          examples:
          - john.smith
        userEmail:
          type: string
          description: email of user.
          examples:
          - user@simplifipay.com
        userFullName:
          type: string
          description: full name of user.
          examples:
          - John Smith
        transactionType:
          type: string
          description: This is a transaction type
          enum:
          - Auth
          - Reversal
          - Settlement
          - Refund
          - Load
          - Unload
          - Fees
          examples:
          - Auth
        statusCode:
          type: string
          description: This field contains the status code of the transaction code received from processor.
          examples:
          - '00'
        statusCodeDescription:
          type: string
          description: This field contains the status description of the transaction code received from processor.
          examples:
          - Approved
        authResponse:
          type: string
          description: This field contains the auth response value of the transaction received from processor.
          examples:
          - '51'
        mccCode:
          type: string
          description: 'This field contains the Merchant Category Code. These, MCCs are four-digit numbers that

            describe a merchant''s primary business activity.'
          examples:
          - '6011'
        merchantId:
          type: string
          description: This field contains the registered merchant ID.
          examples:
          - F09089372443345
        merchantName:
          type: string
          description: This field contains the registered merchant name.
          examples:
          - GOOGLE *TEMPORARY HOLD
        transactionAmount:
          type: number
          format: decimal
          description: This field contains the total amount that was transacted.
          examples:
          - '100.54'
        transactionCurrency:
          type: string
          description: This field contains the currency in which the amount was transacted.
          examples:
          - AED
        transactionDate:
          type: string
          format: date-time
          description: This field contains the date on which the transaction was carried out.
          examples:
          - '2025-02-28 13:31:00'
        billAmount:
          type: number
          format: decimal
          description: This field contains the billed amount.
          examples:
          - '6.95'
        billCurrency:
          type: string
          description: This field contains the name of currency in which the amount is stored in the card
          examples:
          - AED
        fxFee:
          type: number
          format: decimal
          description: This field contains the FX fee amount.
          examples:
          - '0.31'
        feeOperationType:
          type: string
          description: This field specifies the Fee Operation Type
          examples:
          - PRIMARY_VIRTUAL_CARD_ISSUANCE
        feeOperationTypeDescription:
          type: string
          description: This field specifies the Fee Operation Type description
          examples:
          - Virtual Card Issuance Fee
        comments:
          type: string
          description: Any notes for this transaction
        classificationType:
          type: string
          description: Classification of the transaction (Business/Personal)
      required:
      - transactionUuid
      - transactionId
      - cardUuid
      - maskedPan
      - userName
      - userEmail
      - userFullName
      - transactionType
      - statusCode
      - authResponse
      - transactionAmount
      - transactionCurrency
      - transactionDate
    TransactionResponse:
      type: object
      properties:
        transactions:
          type: array
          description: 'This array of objects is a collection of transaction fields,

            possessing sub-fields explained in the rows below.'
          items:
            $ref: '#/components/schemas/TransactionResponseDetails'
        totalElement:
          type: integer
          format: int64
          description: This field contains the total number of elements against the criteria.
      required:
      - transactions
      - totalElement
    TransactionIdParameter:
      type: string
      description: This is an identifier of the transaction.
      examples:
      - '6712309'
    MaskedPanParameter:
      type: string
      description: 'This field contains the partially hidden Primary Account Number

        i.e. all digits are masked, except for the last four ones.'
      examples:
      - '**********1234'
    TransactionTypeParameter:
      type: array
      description: 'This field defines the Transaction types. Allowed values are

        `Auth` - for Authorized transactions

        `Reversal` - for Reversed transactions

        `Settlement` - for Settled transactions

        `Refund` - for Refund transactions

        `Load` - for Card Load transactions

        `Unload` - for Card Unload transactions

        `Fees` - for Fee transactions'
      items:
        type: string
        enum:
        - Auth
        - Reversal
        - Settlement
        - Refund
        - Load
        - Unload
        - Fees
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT access token from POST /v1/auth/login/{companyName}, sent as Authorization: Bearer <token>.'