---
title: "Retrieve payments"
method: GET
path: "/payments"
tags: ["Payments"]
---

# Retrieve payments

`GET /payments`

The ability to get the details of payments using various pieces of information, e.g. using Account ID, retrieve all payments in that account. Can get details of one particular payment based on the unique payment reference number.

## Query parameters

- `id` string — Payment ID. If specified then all other parameters are ignored. Use ids to search for multiple payment IDs
- `ids` string[]
- `fromCreatedDate` string — Payments created date equal or after to this date. Mandatory Parameter(except when 'id', 'ids', 'fxQuoteId' or 'modifiedSince' parameter is used)
- `toCreatedDate` string — Payments created date equal or before to this date
- `modifiedSince` string — Payments modified date equal or before to this date
- `fromUpdatedDate` string — Payments updated date equal or after to this date.
- `toUpdatedDate` string — Payments updated date equal or before to this date.
- `sourceAccountId` string — The source account ID
- `hasExternalReference` boolean — True if the API should return all items that have externalReference. False the API should return all items that don't have externalReference
- `externalReference` string — External reference can only have alphanumeric characters plus underscore, hyphen and space
- `status` string[]
- `type` 'PAYIN' | 'PAYOUT' | 'RETURN' — The payment type to search for.
- `excludeBatchPayments` boolean — Exclude payments which are part of a batch with submission type BATCH
- `batchPaymentId` string — Filter on batch
- `reversals` boolean — Filter on reversals
- `schemeId` string — Filter on scheme ID
- `approvalStatus` string[] — Payment approval status, multiple statuses can be specified by repeating the parameter
- `currency` string[]
- `minAmount` number — Payments amount equal or greater than this amount
- `maxAmount` number — Payments amount equal or less than this amount
- `fromPaymentScheduledDate` string, date-time — Payments scheduled date equal or after to this date
- `toPaymentScheduledDate` string, date-time — Payments scheduled date equal or before to this date and in absence of fromPaymentDate, payments executed prior to 180 days from this date
- `customerId` string[] — Filter on customer ID
- `currentUserCanApprove` boolean — Only return payments the current user can approve.
- `sortField` string — Sort by field. Sorted by createdDate if not present
- `sortOrder` string — Sorting order: 1. asc -> ascending 2. desc -> descending
- `page` integer — The page to fetch. 0 indexed
- `size` integer — The size of the page(s)

## Response `200`

OK

- PaymentPaymentPageResponse
  - `content` PaymentPaymentResponse[], required — List of responses on the current page
    - `id` string, required — Unique id for the Payment request. 10 characters long
    - `status` 'SUBMITTED' | 'SCREENING_REQ' | 'VALIDATED' | 'PENDING_FOR_DATE' | 'PENDING_FOR_FUNDS' | 'EXT_PROC' | 'PROCESSED' | 'RECONCILED' | 'ER_INVALID' | 'ER_EXTCONN' | 'ER_EXTSYS' | 'ER_EXPIRED' | 'ER_GENERAL' | 'ER_BATCH' | 'EXT_SENT' | 'UNALLOCATED' | 'HELD' | 'RETURNED' | 'CANCELLED' | 'REPROCESSING' | 'VOID' | 'CLEARING' | 'HELD_IN_SUSPENSE', required — Current status of payment.
    - `createdDate` string, date-time — Datetime the request was created. Format is 'yyyy-MM-dd'T'HH:mm:ss.sssZ' where Z is UTC offset. e.g '2017-01-28T01:01:01.010+0000'
    - `externalReference` string, required — external reference if provided
    - `details` unknown, required
    - `approvalStatus` 'NOTNEEDED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'DELETED' — Current approval status of payment
    - `message` string — Information about payment (if available)
    - `schemeInfo` PaymentSchemeInfo
      - `name` string
      - `id` string
      - `message` string
      - `responseCode` string
    - `createdBy` string — ID of the user that created the payment
    - `type` 'PAYIN' | 'PAYOUT' | 'RETURN'
    - `paymentScheduledDate` string, date-time — Datetime of the payment scheduled at. Format is 'yyyy-MM-dd'T'HH:mm:ss.sssZ' where Z is UTC offset. e.g '2017-01-28T01:01:01.010+0000'
    - `currentUserCanApprove` boolean — Indicates if current user can approve the payment
    - `approvals` PaymentPaymentApproval[] — List of approvals performed on the payment
      - `approvedBy` string — ID of user who approved this batch payment request
      - `approvedOn` string, date — Date this approval was applied
  - `size` integer, required — Page size
  - `totalSize` integer, required — Total count
  - `page` integer, required — Current page number, 0-based, i.e first page = 0, second page = 1
  - `totalPages` integer, required — Total pages

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/modulrfinance/apis/modulr-api.md) · [All operations](https://skmtc.net/modulrfinance/apis/modulr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/modulrfinance/modulr-api/revisions/cbd52524c8ef/schema)