Shepherd Veterinary Software Payment API

openapi: 3.2.0
info:
  version: v1
  title: Shepherd Open API (v2.248.0.39) Payment API
  description: 'Production Base URL: https://open-api.shepherd.vet/pav2/


    Production App URL: https://app.shepherd.vet/


    Production Documentation URL: https://app.shepherd.vet/swagger/


    Sandbox Base URL: https://demo-open-api.shepherd.vet/pav2/


    Sandbox App URL: https://demo.shepherd.vet/


    Sandbox Documentation URL: https://demo.shepherd.vet/swagger


    Authorization: The integration is authorized by providing two headers in the API call


    X-Integration-Private-Key - this contains the private key from your credentials

    X-Integration-Public-Key - this contains the public key from your credentials


    Additionally, for all requests other than Clinic, the X-Clinic-Id header must be provided with the value of the clinic entity id for which you are running the API requests. You can get the entity id by calling the Clinic endpoint. If authorization fails, the request returns HTTP status 401 and the response body is one of the messages below. Missing X-Integration-Public-Key header - the public key header is absent from the request. Missing X-Integration-Private-Key header - the private key header is absent from the request. Missing X-Clinic-Id header - the clinic identifier header is absent, and the endpoint is clinic scoped. Incorrect API keys provided - both key headers were supplied, but the public key matches no integration, or the private key is not valid for that integration. Integration not enabled for the provided clinic - the key pair is valid, but the integration is not enabled and active for the clinic supplied in X-Clinic-Id. NEW: Each API call will count against your RPH and RPM limits. Once you exhaust those limits, requests will start returning HTTP status 429. The RPH is set to 12000 and RPM to 800 (subject to change). Where an endpoint supports searchQuery, a query longer than 500 characters may return HTTP status 400 with ERROR_MESSAGES.SEARCH_PHRASE.TOO_LONG, and a query with more than 10 words may return HTTP status 400 with ERROR_MESSAGES.SEARCH_PHRASE.TOO_MANY_PHRASES. NOTE: Since this API is WIP, we would be happy to hear any feedback and to implement additional filtering/sorting options etc. **Endpoints:

    All endpoints are POST requests that accept JSON bodies. The common request properties for all endpoints are:**


    rpp::int - The number of items to return per page. The max is 1000. Defaults to 10. page::int - The page number. Defaults to 1. sort::string - Which field to sort by. Needs to be in "field|order" format, where order is either "asc" or "desc". All top-level properties should be sortable, only some nested-fields work and you should probably not use them until this API reaches production and we settle on which nested-field sortings we will support. Default depends on endpoint, usually "id|asc". embed::string - Comma-separated values for nested-fields you want to fetch (eg. "clientPhones,clientPhones.phoneType" on Client endpoint). If a specific embed is not requested, the response will contain either null or an empty array for that value. No default. dateCreatedFrom::date

    dateCreatedTo::date

    dateUpdatedFrom::date

    dateUpdatedTo::date

    - Date range filters for either the creation date or last update date. - You can pass in either one end or both of them. *


    * Only the date filters listed on an endpoint''s request model are supported; sending another one, or a ''From'' later than its ''To'', returns HTTP status 400. The request responses will come back as a JSON object. The common response properties for all endpoints are:


    embed::string - Lists the embed used in the request. This may sometimes be different from what you sent in, if in the future we add that some embeds get set automatically on certain endpoints

    links::object[] - Always empty, a leftover from the internal framework we use on our web API. Will be removed in the future if possible so do not rely on this

    page::int - Which page was fetched.'
servers:
- url: https://open-api.shepherd.vet
tags:
- name: Payment
paths:
  /pav2/open-api-payments:
    post:
      tags:
      - Payment
      summary: Retrieves {OpenApiPaymentController.Payment} resources that match the specified…
      description: 'Example Request

        {

        "clinicIds": "82cfa2e3-3d1f-48e9-95ab-4b6d2f8170b9",

        "embed": "clientClinicBalance",

        "paymentStatusIds": "c9f6a1e2-01b3-420e-93d4-b129ef1a4a3f"

        }


        The cash rounding method can be embedded via "embed": "roundingMethodUsed" (returned as the roundingMethodUsed object; otherwise only roundingMethodUsedId is returned).


        Example Response

        {

        "embed": "clientClinicBalance",

        "item": [

        {

        "amount": -130,

        "amountBeforeRounding": -130,

        "authCode": "",

        "cardType": "",

        "cashTotal": -130,

        "changeAmount": null,

        "clientBalanceAfterPayment": -100,

        "clientClinicBalance": {

        "amount": 100,

        "clinicId": "82cfa2e3-3d1f-48e9-95ab-4b6d2f8170b9",

        "dateCreated": "2025-06-30T10:45:01.000Z",

        "dateUpdated": "2025-06-30T10:45:01.000Z",

        "id": "f1a30b3e-67c8-43a2-8744-27f10e8a77dc"

        },

        "clientId": "df7450ba-d66a-4176-805a-f5ef0bd0b3f6",

        "clinicId": "82cfa2e3-3d1f-48e9-95ab-4b6d2f8170b9",

        "customerId": "",

        "dateVoided": null,

        "invoicePayments": [],

        "isBanquest": null,

        "isDeleted": false,

        "lastDigits": "",

        "note": "",

        "payToCreditBalance": 100,

        "paymentDate": "2025-06-30T10:45:00.000Z",

        "paymentMethod": null,

        "paymentMethodId": "aa63be45-bde2-45f5-9b1a-21f463e6f0d0",

        "paymentStatus": null,

        "paymentStatusId": "c9f6a1e2-01b3-420e-93d4-b129ef1a4a3f",

        "processedByUser": null,

        "processedByUserId": "d92c8737-78a5-4c13-9b72-6bafd8b49b4e",

        "referenceNumber": "",

        "refundPayments": null,

        "refundedPayment": null,

        "refundedPaymentId": null,

        "returnedAmount": 0,

        "roundingAdjustment": 0,

        "roundingMethodUsed": null,

        "roundingMethodUsedId": null,

        "transactionId": "",

        "dateCreated": "2025-06-30T10:44:59.000Z",

        "dateUpdated": "2025-06-30T10:45:01.000Z",

        "id": "ee2d4a87-0e38-432f-8e8a-7983019f8e57"

        }

        ],

        "links": [],

        "page": 1,

        "recordsPerPage": 10,

        "searchQuery": null,

        "sort": null,

        "totalRecords": 1

        }'
      operationId: OpenApiPaymentGet
      parameters:
      - name: x-integration-public-key
        in: header
        description: Your public API key
        required: true
        schema:
          type: string
      - name: x-integration-private-key
        in: header
        description: Your private API key
        required: true
        schema:
          type: string
      - name: x-clinic-id
        in: header
        description: The clinic uuid identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A paged collection of payments matching the search criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiPaymentController.Payment'
            text/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiPaymentController.Payment'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiPaymentController.Payment'
        '401':
          description: 'Authorization failed. One of: Missing X-Integration-Public-Key header, Missing X-Integration-Private-Key header, Missing X-Clinic-Id header, Incorrect API keys provided, or Integration not enabled for the provided clinic.'
        '429':
          description: Request rate limit exceeded. Please wait before making further requests. Returned once the integration passes its configured hourly or per-minute request allowance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiPaymentController.PaymentFilterModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiPaymentController.PaymentFilterModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiPaymentController.PaymentFilterModel'
        description: The model.
        required: true
components:
  schemas:
    OpenApiPaymentController.PaymentStatus:
      description: PaymentStatus REST model
      type: object
      properties:
        abrv:
          description: Short unique identifier for the lookup.
          type: string
        description:
          description: The description of the lookup entry.
          type: string
        name:
          description: The name of the lookup entry.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiPaymentController.ClientClinicBalance:
      description: ClientClinicBalance REST model.
      type: object
      properties:
        amount:
          format: double
          description: Amount representing the client's credit balance
          type: number
        clinicId:
          description: Unique identifier representing the related Clinic entity.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiPaymentController.CashRoundingMethodType:
      description: CashRoundingMethodType REST model
      type: object
      properties:
        abrv:
          description: Short unique identifier for the lookup.
          type: string
        description:
          description: The description of the lookup entry.
          type: string
        name:
          description: The name of the lookup entry.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiPaymentController.RefundPayment:
      description: RefundPayment REST model.
      type: object
      properties:
        amount:
          format: double
          description: Amount that was refunded.
          type: number
        amountBeforeRounding:
          format: double
          description: Total amount before any cash rounding was applied. Equal to Amount.
          type: number
        cashTotal:
          format: double
          description: Actual cash total collected for this payment (Amount + RoundingAdjustment).
          type: number
        clientClinicBalance:
          $ref: '#/components/schemas/OpenApiPaymentController.ClientClinicBalance'
          description: Object representing the related Client clinic balance, amount the client has on their balance for this clinic.
        paymentDate:
          format: date-time
          description: Date when the payment was processed.
          type: string
        paymentStatusId:
          format: uuid
          description: Unique identifier representing the related Payment status entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        referenceNumber:
          description: Reference number assigned to this Payment refund.
          type: string
        roundingAdjustment:
          format: double
          description: Signed cash rounding adjustment applied to this payment. 0 when no rounding was applied.
          type: number
        roundingMethodUsed:
          $ref: '#/components/schemas/OpenApiPaymentController.CashRoundingMethodType'
          description: The cash rounding method type applied to this payment. Populated only when embed=roundingMethodUsed is requested; null when no rounding was applied.
        roundingMethodUsedId:
          format: uuid
          description: Unique identifier of the cash rounding method applied to this payment; null when no rounding was applied.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        transactionId:
          description: Transaction ID assigned to this Payment refund.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiPaymentController.PaymentMethod:
      description: PaymentMethod REST model
      type: object
      properties:
        clinicId:
          format: uuid
          description: Unique identifier representing the related Clinic entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        abrv:
          description: Short unique identifier for the lookup.
          type: string
        description:
          description: The description of the lookup entry.
          type: string
        name:
          description: The name of the lookup entry.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiPaymentController.Pav2User:
      description: Pav2User REST model.
      type: object
      properties:
        licenseNumber:
          description: Pav2User's License number.
          type: string
        prefix:
          description: Pav2User's prefix.
          type: string
        suffix:
          description: Pav2User's suffix.
          type: string
        userId:
          description: Unique identifier of this Pav2User.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiPaymentController.Payment:
      description: Payment REST model.
      type: object
      properties:
        amount:
          format: double
          description: Amount used for this payment.
          type: number
        amountBeforeRounding:
          format: double
          description: Total amount before any cash rounding was applied. Sum of the closed invoice payment amounts plus PayToCreditBalance, or Amount when the payment closed no invoice.
          type: number
        authCode:
          description: Authentication code used for this payment.
          type: string
        cardType:
          description: Type of the card used for this payment.
          type: string
        cashTotal:
          format: double
          description: Actual cash total collected for this payment (AmountBeforeRounding + RoundingAdjustment).
          type: number
        changeAmount:
          format: double
          description: Change amount for this payment, only applied for cash payments.
          type: number
        clientBalanceAfterPayment:
          format: double
          description: Client balance after payment is processed.
          type: number
        clientClinicBalance:
          $ref: '#/components/schemas/OpenApiPaymentController.ClientClinicBalance'
          description: Object representing the related Client clinic balance entity, amount the client has on their balance for this clinic.
        clientId:
          format: uuid
          description: Unique identifier representing the related Client entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        clinicId:
          format: uuid
          description: Unique identifier representing the related Clinic entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        customerId:
          description: Unique identifier representing the related Customer entity.
          type: string
        dateVoided:
          format: date-time
          description: Date when the payment was voided.
          type: string
        invoicePayments:
          description: List of objects representing the related Invoice payment objects.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiPaymentController.InvoicePayment'
        isBanquest:
          description: Flag indicating whether payment is Banquest payment.
          type: boolean
        isDeleted:
          description: Flag indicating whether payment is deleted.
          type: boolean
        lastDigits:
          description: Last 4 digits of the card used for this payment.
          type: string
        note:
          description: Free text field for additional information regarding this payment.
          type: string
        payToCreditBalance:
          format: double
          description: Amount added to the client credit balance.
          type: number
        paymentDate:
          format: date-time
          description: Date when the payment was processed.
          type: string
        paymentMethod:
          $ref: '#/components/schemas/OpenApiPaymentController.PaymentMethod'
          description: Object representing the related Payment method entity used for this payment.
        paymentMethodId:
          format: uuid
          description: Unique identifier representing the related Payment method entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        paymentStatus:
          $ref: '#/components/schemas/OpenApiPaymentController.PaymentStatus'
          description: Object representing the related Payment status entity.
        paymentStatusId:
          format: uuid
          description: Unique identifier representing the related Payment status entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        processedByUser:
          $ref: '#/components/schemas/OpenApiPaymentController.Pav2User'
          description: Object representing the Pav2User who Processed this payment.
        processedByUserId:
          format: uuid
          description: Unique identifier representing the related Pav2user entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        referenceNumber:
          description: Payment's Reference number.
          type: string
        refundPayments:
          description: List of objects representing the Refunded payment entities.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiPaymentController.RefundPayment'
        refundedPayment:
          $ref: '#/components/schemas/OpenApiPaymentController.RefundedPayment'
          description: Object representing the related Refunded payment entity.
        refundedPaymentId:
          format: uuid
          description: Unique identifier representing the related Refunded payment entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        returnedAmount:
          format: double
          description: Returned amount.
          type: number
        roundingAdjustment:
          format: double
          description: Signed cash rounding adjustment applied to this payment. 0 when no rounding was applied.
          type: number
        roundingMethodUsed:
          $ref: '#/components/schemas/OpenApiPaymentController.CashRoundingMethodType'
          description: The cash rounding method type applied to this payment. Populated only when embed=roundingMethodUsed is requested; null when no rounding was applied.
        roundingMethodUsedId:
          format: uuid
          description: Unique identifier of the cash rounding method applied to this payment; null when no rounding was applied.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        transactionId:
          description: Transaction identifier assigned to this Payment.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    RESTCollectionModelBase_OpenApiPaymentController.Payment:
      type: object
      properties:
        embed:
          type: string
        item:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiPaymentController.Payment'
        page:
          format: int32
          type: integer
        recordsPerPage:
          format: int32
          type: integer
        searchQuery:
          type: string
        sort:
          type: string
        totalRecords:
          format: int32
          type: integer
    OpenApiPaymentController.PaymentFilterModel:
      description: Payment Filter REST model
      type: object
      properties:
        clientIds:
          description: Comma-separated list of Client identifiers.
          type: string
        clinicIds:
          description: 'Comma-separated list of clinic identifiers. Defaults to null.

            This filter applies only if the group to which the clinic belongs shares clients and patients.

            If provided, only Payments data from the specified clinics will be returned - but only if the clinic is the patient''s home clinic (regardless of the x-clinic-id in the header).

            If null, data from all clinics in the group will be returned.'
          type: string
        paymentStatusIds:
          description: Comma-separated list of PaymentStatus identifiers.
          type: string
        withDeleted:
          description: Flag filtering by deleted status. Defaults to null (fetches both deleted and non-deleted payments).
          type: boolean
        dateCreatedFrom:
          format: date-time
          description: 'Sets the start of the date range filter on the entity creation date. Must not be later than DateCreatedTo, or

            the request returns 400. Defaults to null.'
          type: string
        dateCreatedTo:
          format: date-time
          description: The end of the date range filter on the entity creation date. Defaults to null.
          type: string
        dateUpdatedFrom:
          format: date-time
          description: 'The start of the date range filter on the entity last update date. Must not be later than DateUpdatedTo, or the

            request returns 400. Defaults to null.'
          type: string
        dateUpdatedTo:
          format: date-time
          description: The end of the date range filter on the entity last update date. Defaults to null.
          type: string
        embed:
          description: Comma-separated list of embedded properties to fetch. Nested fetches can be specified using dot notation (e.g., "client.clientPhones"). Defaults to null.
          type: string
        excludeIds:
          description: Comma-separated list of IDs representing entities that you wish to exclude from your search. Defaults to null.
          type: string
        ids:
          description: Comma-separated list of IDs representing entities that you wish to include in your search. Defaults to null.
          type: string
        page:
          format: int32
          description: The page number. Defaults to 1.
          type: integer
        rpp:
          format: int32
          description: The number of items to return per page. The max is 1000. Defaults to 10.
          type: integer
        sort:
          description: Which field to sort by. Needs to be in "field|order" format, where order is either "asc" or "desc". The default sort field depends on the endpoint, typically "id|asc"
          type: string
    OpenApiPaymentController.InvoicePayment:
      description: InvoicePayment Rest model
      type: object
      properties:
        clinicId:
          format: uuid
          description: Unique identifier representing the related Clinic entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        closedAmount:
          format: double
          description: Amount used for closing this invoice payment.
          type: number
        closedDate:
          format: date-time
          description: Date of closing the Invoice payment.
          type: string
        description:
          description: Free-text field for description of this invoice payment.
          type: string
        invoiceId:
          description: Unique identifier representing the related Invoice entity.
          type: string
        isFullyPaid:
          description: Flag indicating whether this invoice payment is fully paid.
          type: boolean
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiPaymentController.RefundedPayment:
      description: RefundedPayment REST model.
      type: object
      properties:
        amount:
          format: double
          description: Amount that was refunded.
          type: number
        amountBeforeRounding:
          format: double
          description: Total amount before any cash rounding was applied. Equal to Amount.
          type: number
        cashTotal:
          format: double
          description: Actual cash total collected for this payment (Amount + RoundingAdjustment).
          type: number
        clientClinicBalance:
          $ref: '#/components/schemas/OpenApiPaymentController.ClientClinicBalance'
          description: Object representing the related Client clinic balance, amount the client has on their balance for this clinic.
        paymentDate:
          format: date-time
          description: Date when the payment was processed.
          type: string
        paymentStatusId:
          format: uuid
          description: Unique identifier representing the related Payment status entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        referenceNumber:
          description: Reference number assigned to this Refunded payment.
          type: string
        roundingAdjustment:
          format: double
          description: Signed cash rounding adjustment applied to this payment. 0 when no rounding was applied.
          type: number
        roundingMethodUsed:
          $ref: '#/components/schemas/OpenApiPaymentController.CashRoundingMethodType'
          description: The cash rounding method type applied to this payment. Populated only when embed=roundingMethodUsed is requested; null when no rounding was applied.
        roundingMethodUsedId:
          format: uuid
          description: Unique identifier of the cash rounding method applied to this payment; null when no rounding was applied.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        transactionId:
          description: Transaction ID assigned to this Refunded payment.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string