Clover PAYMENTS API

openapi: 3.1.0
info:
  title: Clover Ecommerce CHARGES PAYMENTS API
  description: 'Clover Ecommerce API v1 — online (card-not-present) payments: charges, captures, refunds, tokenization, and hosted checkout. Authentication uses OAuth 2.0 / PAKMS Ecommerce API keys. Schemas and operations are derived from the Clover developer reference at docs.clover.com.'
  version: v1
  contact:
    name: Clover Developer Platform
    url: https://docs.clover.com/dev/reference
  x-generated-from: documentation
  x-last-validated: '2026-06-02'
servers:
- url: https://scl.clover.com
  description: Production Ecommerce
- url: https://scl-sandbox.dev.clover.com
  description: Sandbox Ecommerce
security:
- OAuth2: []
tags:
- name: PAYMENTS
paths:
  /v3/merchants/{mId}/payments/{payId}:
    get:
      summary: Clover Get a Single Payment
      description: Retrieve a single payment information, including the total amount, tip amount, tax amount, and result status.
      operationId: payGetPayment
      tags:
      - PAYMENTS
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: payId
        in: path
        required: true
        description: Payment Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: expand
        in: query
        required: false
        description: 'Expandable fields: [tender, germanInfo, lineItemPayments, cardTransaction, dccInfo, employee, refunds, transactionInfo, externalReferenceId, oceanGatewayInfo, taxRates, additionalCharges, appTracking, paymentAttributes, order]'
        schema:
          type: string
        example: example-expand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
              examples:
                PayGetPayment200Example:
                  summary: Default payGetPayment 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    order: {}
                    device: {}
                    tender: {}
                    amount: 1
                    tipAmount: 1
                    taxAmount: 1
                    cashbackAmount: 1
                    cashTendered: 1
                    externalPaymentId: example-value
                    employee: {}
                    createdTime: 1
                    clientCreatedTime: 1
                    gatewayProcessingTime: 1
                    modifiedTime: 1
                    offline: true
                    result: SUCCESS
                    cardTransaction: {}
                    serviceCharge: {}
                    attributes: {}
                    additionalCharges:
                    - {}
                    taxRates:
                    - {}
                    refunds:
                    - {}
                    note: example-value
                    lineItemPayments:
                    - {}
                    authorization: {}
                    voidPaymentRef: {}
                    voidReason: USER_CANCEL
                    voidReasonDetails: {}
                    dccInfo: {}
                    transactionSettings: {}
                    germanInfo: {}
                    appTracking: {}
                    cashAdvanceExtra: {}
                    transactionInfo: {}
                    signatureDisclaimer: {}
                    externalReferenceId: example-value
                    merchant: {}
                    increments:
                    - {}
                    purchaseCardL2: {}
                    purchaseCardL3: {}
                    oceanGatewayInfo: {}
                    terminalManagementComponents:
                    - {}
                    emiInfo: {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/merchants/{mId}/payments:
    get:
      summary: Clover Get All Payments
      description: Retrieves payment information, including the total amount, tip amount, tax amount, and result status.
      operationId: payGetPayments
      tags:
      - PAYMENTS
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant identifier.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: filter
        in: query
        required: false
        description: 'Filter fields to display search results: [modifiedTime, device.id, externalReferenceId, result, offline, createdTime, externalPaymentId, voided, id, tender.id, employee.id, order.modifiedTime, amount, cardType, clientCreatedTime]'
        schema:
          type: string
        example: example-filter
      - name: expand
        in: query
        required: false
        description: 'Expandable fields to display additional nested information: [tender, germanInfo, lineItemPayments, cardTransaction, dccInfo, refunds, transactionInfo, externalReferenceId, oceanGatewayInfo, taxRates, additionalCharges, appTracking, paymentAttributes, order]'
        schema:
          type: string
        example: example-expand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
              examples:
                PayGetPayments200Example:
                  summary: Default payGetPayments 200 response
                  x-microcks-default: true
                  value:
                    elements:
                    - {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Payment:
      type: object
      properties:
        id:
          type: string
          description: 13-digits unique identifier of the Merchant.
          example: 9ABCDEF1234567
        order:
          type: object
          example: {}
        device:
          type: object
          example: {}
        tender:
          type: object
          example: {}
        amount:
          type: integer
          format: int64
          description: Total amount paid.
          example: 1099
        tipAmount:
          type: integer
          description: Tip amount paid.
          example: 1099
        taxAmount:
          type: integer
          description: Tax amount paid.
          example: 1099
        cashbackAmount:
          type: integer
          description: Cash amount given by the customer to the merchant.
          example: 1099
        cashTendered:
          type: integer
          description: Payment amount given by the customer.
          example: 1
        externalPaymentId:
          type: string
          description: External payment identifier.
          example: 9ABCDEF1234567
        employee:
          type: object
          example: {}
        createdTime:
          type: integer
          format: int64
          description: Time when payment was recorded on the server.
          example: 1718153645000
        clientCreatedTime:
          type: integer
          format: int64
          description: Time when payment was recorded on the client server.
          example: 1718153645000
        gatewayProcessingTime:
          type: integer
          format: int64
          description: Time when the transaction was processed by the payment gateway.
          example: 1718153645000
        modifiedTime:
          type: integer
          format: int64
          description: Last modified time of the payment.
          example: 1718153645000
        offline:
          type: boolean
          description: Indicates if the tender option is offline.
          example: true
        result:
          type: string
          description: "Indicates the result of the tender.\n Values: Success, fail, initiated, voided, voiding, void_failed, auth, auth_completed, discount, offline_retrying, and pending."
          enum:
          - SUCCESS
          - FAIL
          - INITIATED
          - VOIDED
          - VOIDING
          - VOID_FAILED
          - AUTH
          - AUTH_COMPLETED
          - DISCOUNT
          - OFFLINE_RETRYING
          - PENDING
          example: SUCCESS
        cardTransaction:
          type: object
          example: {}
        serviceCharge:
          type: object
          example: {}
        attributes:
          type: object
          example: {}
        additionalCharges:
          type: array
          items:
            type: object
          example: []
        taxRates:
          type: array
          items:
            type: object
          example: []
        refunds:
          type: array
          items:
            type: object
          example: []
        note:
          type: string
          description: Note for the refund.
          example: Example note value.
        lineItemPayments:
          type: array
          items:
            type: object
          example: []
        authorization:
          type: object
          example: {}
        voidPaymentRef:
          type: object
          example: {}
        voidReason:
          type: string
          description: If voided, the reason for the payment void, if available.
          enum:
          - USER_CANCEL
          - TRANSPORT_ERROR
          - REJECT_SIGNATURE
          - REJECT_PARTIAL_AUTH
          - NOT_APPROVED
          - FAILED
          - AUTH_CLOSED_NEW_CARD
          - DEVELOPER_PAY_PARTIAL_AUTH
          - REJECT_DUPLICATE
          - REJECT_OFFLINE
          - GIFTCARD_LOAD_FAILED
          - USER_GIFTCARD_LOAD_CANCEL
          - DEVELOPER_PAY_TIP_ADJUST_FAILED
          - USER_CUSTOMER_CANCEL
          - FRAUD
          - REJECT_GREATER_APPROVED_AMOUNT
          - TIMEOUT
          example: USER_CANCEL
        voidReasonDetails:
          type: object
          example: {}
        dccInfo:
          type: object
          example: {}
        transactionSettings:
          type: object
          example: {}
        germanInfo:
          type: object
          example: {}
        appTracking:
          type: object
          example: {}
        cashAdvanceExtra:
          type: object
          example: {}
        transactionInfo:
          type: object
          example: {}
        signatureDisclaimer:
          type: object
          example: {}
        externalReferenceId:
          type: string
          description: External reference identifier (ID) if associated with the payment.
          example: 9ABCDEF1234567
        merchant:
          type: object
          example: {}
        increments:
          type: array
          items:
            type: object
          example: []
        purchaseCardL2:
          type: object
          example: {}
        purchaseCardL3:
          type: object
          example: {}
        oceanGatewayInfo:
          type: object
          example: {}
        terminalManagementComponents:
          type: array
          items:
            type: object
          example: []
        emiInfo:
          type: object
          example: {}
      description: Clover Payment resource. Schema derived from the Clover Platform REST API v3 reference.
      x-schema-source: documentation
      x-source-url: https://docs.clover.com/dev/reference/paygetpayment
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.clover.com/oauth/authorize
          tokenUrl: https://api.clover.com/oauth/token
          scopes: {}
      description: OAuth 2.0 token or Ecommerce (PAKMS) API key.