---
title: "Get list of payments"
method: GET
path: "/v3/payments"
tags: ["payments"]
---

# Get list of payments

`GET /v3/payments`

Get a list of payment objects. By default, you get 20 results on one page of results. Set `max` in your request to get up to 100 results on one page.

See [Search operations with lists](https://developer.bill.com/docs/search-op-with-lists) in the Guides section for filtering, sorting, and pagination examples.

## Query parameters

- `max` integer, nullable — Maximum number of results
- `sort` string, nullable — Field name and sort order. Both simple and compound sorting is available. The format is `sort={field_01}:{sort_order},{field_02}:{sort_order}`. **NOTE**: Sorting occurs in the specified order.
- `filters` string, nullable — Field name, operator, and value. Both simple and compound filtering is available. The format is `filters={field_01}:{op}:{value},{field_02}:{op}:{value}`.
- `page` string, nullable — Next page of results. When a list has multiple pages, the `nextPage` and `prevPage` values in the response enable you to navigate between the pages of results. Set `page` as the `nextPage` or `prevPage` value for navigation.

## Headers

- `sessionId` string, nullable — API session ID generated with `/v3/login`
- `devKey` string, nullable — Developer key generated with your BILL developer account

## Response `200`

Get list of payments response

- ListPaymentResponseDto — Response from a list API request with paging references.
  - `nextPage` string
  - `prevPage` string
  - `results` PaymentResponseDto[]
    - `id` string — BILL-generated ID of the payment. The value begins with `stp`.
    - `vendorId` string — BILL-generated ID of the vendor to be paid. The value begins with `009`.
    - `vendorName` string — Vendor name
    - `billId` string — BILL-generated ID of the bill to be paid. The value begins with `00n`.
    - `billPayments` BillPayment[] — List of bill payments. When a payment is applied to a bill, the bill payment is identified by a bill payment `id`. The value begins with `blp`.
      - `id` string — BILL-generated ID of the bill payment. The value begins with `blp`.
      - `billId` string — BILL-generated ID of the bill to be paid. The value begins with `00n`.
      - `amount` number — Payment amount. For a payment in an international currency (not USD), this value is in the local currency.
      - `vendorCredits` PaymentVendorCreditResponseDto[] — Vendor credits applied to the bill payment
        - `id` string — BILL-generated ID of the vendor credit applied to the bill payment. The value begins with `vcr`.
        - `amount` number — Credit amount
    - `description` string — Bill payment description. This value is included in the check memo or in the bank descriptor for electronic payments.
    - `processDate` string, date — Payment process date in the `yyyy-MM-dd` format. On this date, BILL starts processing the payment and starts withdrawing funds from the sender's funding account.
    - `fundingAccount` object — Payment funding information
      - `type` 'BANK_ACCOUNT' | 'CARD_ACCOUNT' | 'WALLET' | 'AP_CARD' | 'UNDEFINED', required — Payment funding type. * `BANK_ACCOUNT`: Bank account * `CARD_ACCOUNT`: Credit card or debit card * `WALLET`: BILL balance * `AP_CARD`: AP Card See the BILL Help FAQ sections for [BILL balance](https://help.bill.com/direct/s/article/4409933681677) and [AP Card](https://help.bill.com/direct/s/article/000003348) for more information.
      - `id` string — BILL-generated ID of the selected payment funding type. For the `WALLET` type, the `id` is not required.
    - `amount` number, required — Payment amount. For a payment in an international currency (not USD), this value is in the local currency.
    - `processingOptions` object — Payment processing options
      - `requestPayFaster` boolean — Set as `true` to use BILL Pay Faster. This field is required if `requestCheckDeliveryType` is set. See [Payments](https://developer.bill.com/docs/ap-payments) in the Guides section for information about BILL Pay Faster payments.
      - `createBill` boolean — * Set as `false` to create a vendor payment for an existing bill. * Set as `true` to create a bill for a vendor payment. If `createBill` is `true`, do not set `billId` in your payment request.
      - `requestCheckDeliveryType` 'STANDARD' | 'UPS_1DAY' | 'UPS_2DAY' | 'UPS_3DAY' | 'RTP_DELIVERY' | 'UNDEFINED' — BILL Pay Faster payment delivery type. The `RTP_DELIVERY` option is not available for vendor payments by check.
    - `transactionNumber` string — Payment transaction reference used as an external identifier. You can set this field as a unique alphanumeric value for your system to track the payment transaction. The value must be 50 characters or fewer. If you do not set `transactionNumber`, BILL sets this field as a unique alphanumeric payment identification value.
    - `confirmationNumber` string — BILL-generated bill payment confirmation value
    - `status` 'APPROVING' | 'SCHEDULED' | 'PAID' | 'CANCELLED' | 'VOID' | 'ESCHEATED' | 'UNDEFINED' — Payment status.
    - `exchangeRate` number — Exchange rate for the payment in an international currency (not USD)
    - `fundingAmount` number — Payment amount in USD
    - `onlinePayment` boolean — Payment source. * `true`: Payment is made with BILL (online) * `false`: Payment is made outside BILL and then recorded in BILL (offline)
    - `disbursementType` 'CHECK' | 'ACH' | 'RPPS' | 'PAYPAL' | 'OFFLINE' | 'INTERNATIONAL_E_PAYMENT' | 'AMEX' | 'VIRTUAL_CARD' | 'WALLET' | 'CREDIT_CARD' | 'UNDEFINED' — Disbursement type. This value is set when you create a payment. See `disbursementInfo` for information about the disbursement method used when BILL processes your payment.
    - `remittanceEmail` string — Remittance email address set for the vendor
    - `createdTime` string, date-time — Payment created date and time
    - `updatedTime` string, date-time — Payment updated date and time
    - `createdBy` string — BILL-generated ID of the user that created the payment. The value begins with `006`.
    - `voidInfo` VoidInfo[] — Void request information
      - `id` string — BILL-generated ID of the void payment request. The value begins with `vrq`.
      - `requestedBy` string — BILL-generated ID of the user that requested a void payment. The value begins with `006`.
      - `type` 'VOID_AND_CREDIT' | 'VOID_AND_REISSUE' | 'VOID_ONLY' | 'VOID_AND_REISSUE_VCARD' — Void payment request type.
      - `status` 'TO_BE_PROCESSED' | 'ACCEPTED' | 'REJECTED' | 'NO_OP' | 'ARCHIVED' — Void payment request status.
      - `reason` string — Void payment request reason
      - `createdTime` string, date-time — Void payment request created date and time
      - `updatedTime` string, date-time — Void payment request updated date and time
    - `disbursementStatus` 'SCHEDULE' | 'DONE' | 'FAILED' | 'VOID' | 'HOLD' | 'FXHOLD' | 'ESCHEATED' | 'UNDEFINED' — Payment disbursement status
    - `disbursementInfo` object — Payment disbursement information. This information is based on the disbursement method used when BILL processes your payment. For example, when BILL processes an ACH payment, `disbursementInfo` includes the `sentDate` and `arrivesByDate` fields.
      - `isVoidable` boolean — Set as `true` if the payment disbursement type can be voided
      - `checkDisbursement` object — Check payment disbursement information
        - `sentDate` string, date — Check payment sent date
        - `arrivesByDate` string, date — Check payment arrives by date
        - `checkNumber` integer — Check number
        - `trackingInformation` string — UPS tracking number for the check. You get a tracking number only for a BILL Pay Faster check payment.
      - `achDisbursement` object — ACH payment disbursement information
        - `sentDate` string, date — ACH payment sent date
        - `arrivesByDate` string, date — ACH payment arrives by date
      - `rppsDisbursement` object — ACH payment to verified national vendor disbursement information
        - `sentDate` string, date — ACH payment to verified national vendor sent date
        - `arrivesByDate` string, date — ACH payment to verified national vendor arrives by date
        - `traceNumber` integer — Payment trace number. This value is used to uniquely identify a payment in a batch.
        - `batchNumber` integer — Payment batch number
      - `internationalDisbursement` object — International ePayment disbursement information
        - `sentDate` string, date — International ePayment sent date
        - `arrivesByDate` string, date — International ePayment arrives by date
        - `amount` number — Disbursement amount
        - `disbursementSubType` 'NONE' | 'WIRE' | 'IACH' | 'LOCAL' | 'MULTIPLE' | 'ACH' | 'UNDEFINED' — Payment delivery method for making the International ePayment
      - `vcardDisbursement` object — Virtual card payment disbursement information
        - `arrivesByDate` string, date — Virtual card payment arrives by date
        - `validUntil` string, date — Date until when the card is valid
        - `last4CardNumber` string — Masked number for virtual card
      - `walletDisbursement` object — Instant Transfer (wallet) payment disbursement information
        - `arrivesByDate` string, date — Instant Transfer (wallet) payment arrives by date
    - `paymentPurpose` object — Payment purpose information
      - `text` string — Payment purpose text
      - `code` object — Payment purpose code
        - `name` string — Name
        - `value` string — Value
    - `cardFundingPurpose` string — Card funding purpose
    - `cancelRequestSubmitted` boolean — This field is set as `true` if a cancel payment request is submitted. **Note**: If the payment is cancelled, the payment `status` is set as `CANCELLED`.
    - `singleStatus` 'DISBURSEMENT_FAILED_ACTION_NEEDED' | 'DISBURSEMENT_FAILED_VENDOR_BANK_REJECTED' | 'FUNDING_FAILED_ACTION_NEEDED' | 'EXPIRING' | 'FUNDS_ESCHEATED' | 'CANCELED' | 'FUNDING_FAILED_VOIDED' | 'VOIDED' | 'CLEARED' | 'DELIVERED' | 'DISBURSEMENT_ON_HOLD' | 'VOID_PENDING' | 'SENT' | 'DISBURSEMENT_ON_HOLD_PAYER_IN_REVIEW' | 'PROCESSED' | 'FUNDING_STARTED' | 'FUNDING_ON_HOLD' | 'WAITING_ON_APPROVAL' | 'SCHEDULED' | 'READY_TO_FUND' | 'CANCELLATION_IN_PROGRESS' | 'UNDEFINED' | 'PARTIALLY_CLAIMED' | 'PAID_OFFLINE' — Unified payment status. This field provides BILL payment lifecycle updates based on the `status` and `disbursementStatus` values in the response. See [Single status payment values](https://developer.bill.com/docs/single-status-payment-values) in the Guides section for the list of available values.

## Other responses

- `4XX` — List of errors.
- `5XX` — List of errors.

---

[API](https://skmtc.net/bill/apis/bill-v3-api.md) · [All operations](https://skmtc.net/bill/apis/bill-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bill/bill-v3-api/versions/0483350c434e/schema)