> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment

> Read payroll and contractor related payments by the company.



## OpenAPI

````yaml get /employer/payment
openapi: 3.1.0
info:
  title: API Reference
  version: '2020-09-17'
  contact: {}
  description: >-
    The Finch HRIS API provides a unified way to connect to a multitide of HRIS
    systems. The API requires an access token issued by Finch.


    By default, Organization and Payroll requests use Finch's [Data
    Syncs](/developer-resources/Data-Syncs). If a request is made before the
    initial sync has completed, Finch will request data live from the provider.
    The latency on live requests may range from seconds to minutes depending on
    the provider and batch size.

    For automated integrations, Deductions requests (both read and write) are
    always made live to the provider. Latencies may range from seconds to
    minutes depending on the provider and batch size.



    Employer products are specified by the product parameter, a space-separated
    list of products that your application requests from an employer
    authenticating through Finch Connect. Valid product names are—

    - `company`: Read basic company data


    - `directory`: Read company directory and organization structure


    - `individual`: Read individual data, excluding income and employment data


    - `employment`: Read individual employment and income data


    - `payment`: Read payroll and contractor related payments by the company


    - `pay_statement`: Read detailed pay statements for each individual


    - `benefits`: Create and manage deductions and contributions and enrollment
    for an employer


    [![Open in
    Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4?action=collection%2Ffork&collection-url=entityId%3D21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4%26entityType%3Dcollection%26workspaceId%3D1edf19bc-e0a8-41e9-ac55-481a4b50790b)
servers:
  - url: https://api.tryfinch.com
    description: ''
security: []
tags:
  - name: Organization
  - name: Payroll
  - name: Deductions
  - name: Management
  - name: Sandbox
paths:
  /employer/payment:
    get:
      tags:
        - Payroll
      summary: Payment
      description: Read payroll and contractor related payments by the company.
      operationId: get-payment
      parameters:
        - name: entity_ids
          in: query
          required: false
          description: The entity IDs to specify which entities' data to access.
          schema:
            type: array
            items:
              type: string
              format: uuid
            minItems: 1
            maxItems: 1
            example:
              - 550e8400-e29b-41d4-a716-446655440000
          style: form
          explode: true
        - name: start_date
          in: query
          required: true
          description: >-
            The start date to retrieve payments by a company (inclusive) in
            `YYYY-MM-DD` format. Filters payments by their **pay_date** field.
          schema:
            type: string
            format: date
            example: '2021-01-01'
        - name: end_date
          in: query
          required: true
          description: >-
            The end date to retrieve payments by a company (inclusive) in
            `YYYY-MM-DD` format. Filters payments by their **pay_date** field.
          schema:
            type: string
            format: date
            example: '2021-01-01'
        - $ref: '#/components/parameters/API-Version'
      responses:
        '200':
          description: Payment data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentsResponse'
              examples:
                Success:
                  value:
                    - id: 20aa7cf2-949d-4d4e-9c01-499b59501ded
                      pay_period:
                        start_date: '2019-08-01'
                        end_date: '2019-08-15'
                      pay_date: '2019-08-22'
                      debit_date: '2019-08-22'
                      company_debit:
                        amount: 5300000
                        currency: usd
                      gross_pay:
                        amount: 4000000
                        currency: usd
                      net_pay:
                        amount: 3200000
                        currency: usd
                      employer_taxes:
                        amount: 200000
                        currency: usd
                      employee_taxes:
                        amount: 350000
                        currency: usd
                      individual_ids:
                        - 54719e14-5ea7-4fda-9898-f4d9ccb83c1a
                        - 0ab620fc-203e-44ad-916c-facc69250f6f
                      pay_group_ids:
                        - 5d0b10a1-a09a-430f-81f1-20be735dc5e9
                        - 9349eed4-4064-4641-ba8e-9e1ad7e1d014
                      pay_frequencies:
                        - monthly
                        - weekly
        '202':
          description: >-
            The request has been accepted for processing, but data is not yet
            available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
              examples:
                DataSyncInProgress:
                  value:
                    code: 202
                    name: sync_in_progress
                    finch_code: data_sync_in_progress
                    message: >-
                      The data being requested is being fetched. Please check
                      back later.
                AuthorizationPending:
                  value:
                    code: 202
                    name: authorization_pending
                    finch_code: pending
                    message: Authorization to this company's data is pending
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Finch from '@tryfinch/finch-api';

            const client = new Finch({
              accessToken: 'My Access Token',
            });

            // Automatically fetches more pages as needed.
            for await (const payment of client.hris.payments.list({
              end_date: '2021-01-01',
              start_date: '2021-01-01',
            })) {
              console.log(payment.id);
            }
        - lang: Python
          source: |-
            from datetime import date
            from finch import Finch

            client = Finch(
                access_token="My Access Token",
            )
            page = client.hris.payments.list(
                end_date=date.fromisoformat("2021-01-01"),
                start_date=date.fromisoformat("2021-01-01"),
            )
            page = page.items[0]
            print(page.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n\n\t\"github.com/Finch-API/finch-api-go\"\n\t\"github.com/Finch-API/finch-api-go/option\"\n)\n\nfunc main() {\n\tclient := finchgo.NewClient(\n\t\toption.WithAccessToken(\"My Access Token\"),\n\t)\n\tpage, err := client.HRIS.Payments.List(context.TODO(), finchgo.HRISPaymentListParams{\n\t\tEndDate:   finchgo.F(time.Now()),\n\t\tStartDate: finchgo.F(time.Now()),\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
        - lang: Java
          source: |-
            package com.tryfinch.api.example;

            import com.tryfinch.api.client.FinchClient;
            import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
            import com.tryfinch.api.models.HrisPaymentListPage;
            import com.tryfinch.api.models.HrisPaymentListParams;
            import java.time.LocalDate;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    FinchClient client = FinchOkHttpClient.builder()
                        .fromEnv()
                        .accessToken("My Access Token")
                        .build();

                    HrisPaymentListParams params = HrisPaymentListParams.builder()
                        .endDate(LocalDate.parse("2021-01-01"))
                        .startDate(LocalDate.parse("2021-01-01"))
                        .build();
                    HrisPaymentListPage page = client.hris().payments().list(params);
                }
            }
        - lang: Kotlin
          source: |-
            package com.tryfinch.api.example

            import com.tryfinch.api.client.FinchClient
            import com.tryfinch.api.client.okhttp.FinchOkHttpClient
            import com.tryfinch.api.models.HrisPaymentListPage
            import com.tryfinch.api.models.HrisPaymentListParams
            import java.time.LocalDate

            fun main() {
                val client: FinchClient = FinchOkHttpClient.builder()
                    .fromEnv()
                    .accessToken("My Access Token")
                    .build()

                val params: HrisPaymentListParams = HrisPaymentListParams.builder()
                    .endDate(LocalDate.parse("2021-01-01"))
                    .startDate(LocalDate.parse("2021-01-01"))
                    .build()
                val page: HrisPaymentListPage = client.hris().payments().list(params)
            }
        - lang: Ruby
          source: >-
            require "finch_api"


            finch = FinchAPI::Client.new(access_token: "My Access Token")


            page = finch.hris.payments.list(end_date: "2021-01-01", start_date:
            "2021-01-01")


            puts(page)
components:
  parameters:
    API-Version:
      name: Finch-API-Version
      in: header
      required: true
      schema:
        type: string
        default: '2020-09-17'
        format: date
        pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))
      description: >-
        Header used to specify the version for a given API request. Current
        version is 2020-09-17.
  schemas:
    GetPaymentsResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            format: uuid
            description: The unique id for the payment.
          pay_period:
            type: object
            nullable: true
            properties:
              start_date:
                $ref: '#/components/schemas/Date'
              end_date:
                $ref: '#/components/schemas/Date'
            required:
              - start_date
              - end_date
            description: The pay period object.
          pay_date:
            $ref: '#/components/schemas/Date'
          debit_date:
            $ref: '#/components/schemas/Date'
          company_debit:
            $ref: '#/components/schemas/Money'
          gross_pay:
            $ref: '#/components/schemas/Money'
          net_pay:
            $ref: '#/components/schemas/Money'
          employer_taxes:
            $ref: '#/components/schemas/Money'
          employee_taxes:
            $ref: '#/components/schemas/Money'
          individual_ids:
            type: array
            nullable: true
            items:
              type: string
              format: uuid
            description: Array of every individual on this payment.
          pay_group_ids:
            type: array
            nullable: true
            items:
              type: string
              format: uuid
            description: >-
              Array of the Finch id (uuidv4) of every pay group associated with
              this payment.
          pay_frequencies:
            type: array
            nullable: true
            items:
              $ref: '#/components/schemas/PayFrequency'
            description: List of pay frequencies associated with this payment.
        required:
          - id
          - pay_period
          - pay_date
          - debit_date
          - company_debit
          - gross_pay
          - net_pay
          - employer_taxes
          - employee_taxes
          - individual_ids
          - pay_group_ids
          - pay_frequencies
    AcceptedResponse:
      type: object
      properties:
        code:
          type: number
          default: 202
        name:
          type: string
        finch_code:
          type: string
        message:
          type: string
      required:
        - name
        - finch_code
        - message
    Date:
      type: string
      title: Date
      nullable: true
      pattern: (\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))
    Money:
      type: object
      nullable: true
      properties:
        amount:
          type: integer
          nullable: true
          description: Amount for money object (in cents)
        currency:
          type: string
      required:
        - amount
        - currency
      title: Money
      x-tags:
        - Models
    PayFrequency:
      type: string
      enum:
        - annually
        - bi_weekly
        - daily
        - monthly
        - other
        - quarterly
        - semi_annually
        - semi_monthly
        - weekly
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Please use your Access Token

````