## Search payments

`PaymentSummaryPagedV1 Payments.List(PaymentListParams?parameters, CancellationTokencancellationToken = default)`

**get** `/v1/payments`

Search for payments, including `charges` and `payouts`, using a variety of criteria. This endpoint supports advanced sorting and filtering options.

### Parameters

- `PaymentListParams parameters`

  - `string customerID`

    Query param: Search using the `customer_id` of a `charge` or `payout`.

  - `Int defaultPageSize`

    Query param

  - `DefaultSort defaultSort`

    Query param: The field to sort the results by.

    - `"created_at"CreatedAt`

    - `"payment_date"PaymentDate`

    - `"effective_at"EffectiveAt`

    - `"id"ID`

    - `"amount"Amount`

  - `DefaultSortOrder defaultSortOrder`

    Query param

    - `"asc"Asc`

    - `"desc"Desc`

  - `string externalID`

    Query param: Search using the `external_id` of a `charge` or `payout`.

  - `string fundingID`

    Query param: Search using the `funding_id` of a `charge` or `payout`.

  - `Boolean includeMetadata`

    Query param: Include the metadata for payments in the returned data.

  - `Int maxAmount`

    Query param: Search using a maximum `amount` of a `charge` or `payout`.

  - `DateTimeOffset maxCreatedAt`

    Query param: Search using the latest `created_at` date of a `charge` or `payout`.

  - `DateTimeOffset maxEffectiveAt`

    Query param: Search using the latest `effective_date` of a `charge` or `payout`.

  - `DateOnly maxPaymentDate`

    Query param: Search using the latest `payment_date` of a `charge` or `payout`.

  - `Int minAmount`

    Query param: Search using the minimum `amount of a`charge`or`payout`.

  - `DateTimeOffset minCreatedAt`

    Query param: Search using the earliest `created_at` date of a `charge` or `payout`.

  - `DateTimeOffset minEffectiveAt`

    Query param: Search using the earliest `effective_date` of a `charge` or `payout`.

  - `DateOnly minPaymentDate`

    Query param: Search using the earliest ``of a `charge` or `payout`.

  - `Int pageNumber`

    Query param: Results page number. Starts at page 1.

  - `Int pageSize`

    Query param: Results page size. Max value: 1000

  - `string paykey`

    Query param: Search using the `paykey` of a `charge` or `payout`.

  - `string paykeyID`

    Query param: Search using the `paykey_id` of a `charge` or `payout`.

  - `string paymentID`

    Query param: Search using the `id` of a `charge` or `payout`.

  - `IReadOnlyList<PaymentStatus> paymentStatus`

    Query param: Search by the status of a `charge` or `payout`.

    - `"created"Created`

    - `"scheduled"Scheduled`

    - `"failed"Failed`

    - `"cancelled"Cancelled`

    - `"on_hold"OnHold`

    - `"pending"Pending`

    - `"paid"Paid`

    - `"reversed"Reversed`

    - `"validating"Validating`

  - `IReadOnlyList<PaymentType> paymentType`

    Query param: Search by the type of a `charge` or `payout`.

    - `"charge"Charge`

    - `"payout"Payout`

  - `string searchText`

    Query param: Search using a text string associated with a `charge` or `payout`.

  - `SortBy sortBy`

    Query param: The field to sort the results by.

    - `"created_at"CreatedAt`

    - `"payment_date"PaymentDate`

    - `"effective_at"EffectiveAt`

    - `"id"ID`

    - `"amount"Amount`

  - `SortOrder sortOrder`

    Query param

    - `"asc"Asc`

    - `"desc"Desc`

  - `IReadOnlyList<StatusReason> statusReason`

    Query param: Reason for latest payment status change.

    - `"insufficient_funds"InsufficientFunds`

    - `"closed_bank_account"ClosedBankAccount`

    - `"invalid_bank_account"InvalidBankAccount`

    - `"invalid_routing"InvalidRouting`

    - `"disputed"Disputed`

    - `"payment_stopped"PaymentStopped`

    - `"owner_deceased"OwnerDeceased`

    - `"frozen_bank_account"FrozenBankAccount`

    - `"risk_review"RiskReview`

    - `"fraudulent"Fraudulent`

    - `"duplicate_entry"DuplicateEntry`

    - `"invalid_paykey"InvalidPaykey`

    - `"payment_blocked"PaymentBlocked`

    - `"amount_too_large"AmountTooLarge`

    - `"too_many_attempts"TooManyAttempts`

    - `"internal_system_error"InternalSystemError`

    - `"user_request"UserRequest`

    - `"ok"Ok`

    - `"other_network_return"OtherNetworkReturn`

    - `"payout_refused"PayoutRefused`

    - `"cancel_request"CancelRequest`

    - `"failed_verification"FailedVerification`

    - `"require_review"RequireReview`

    - `"blocked_by_system"BlockedBySystem`

    - `"watchtower_review"WatchtowerReview`

    - `"validating"Validating`

    - `"auto_hold"AutoHold`

  - `IReadOnlyList<StatusSource> statusSource`

    Query param: Source of latest payment status change.

    - `"watchtower"Watchtower`

    - `"bank_decline"BankDecline`

    - `"customer_dispute"CustomerDispute`

    - `"user_action"UserAction`

    - `"system"System`

  - `string correlationID`

    Header param: Optional client generated identifier to trace and debug a series of requests.

  - `string requestID`

    Header param: Optional client generated identifier to trace and debug a request.

  - `string straddleAccountID`

    Header param: For use by platforms to specify an account id and set scope of a request.

### Returns

- `class PaymentSummaryPagedV1:`

  - `required IReadOnlyList<Data> Data`

    - `required string ID`

      Unique identifier for the `charge` or `payout`.

    - `required Int Amount`

      The amount of the `charge` or `payout` in cents.

    - `required DateTimeOffset CreatedAt`

      The time the `charge` or `payout` was created.

    - `required string Currency`

      The currency of the `charge` or `payout`. Only USD is supported.

    - `required string? Description`

      An arbitrary description for the `charge` or `payout`.

    - `required string ExternalID`

      Unique identifier for the `charge` or `payout` in your database. This value must be unique across all charges or payouts.

    - `required IReadOnlyList<string> FundingIds`

      Funding ids.

    - `required string Paykey`

      Value of the `paykey` used for the `charge` or `payout`.

    - `required DateOnly PaymentDate`

      The desired date on which the payment should be occur. For charges, this means the date you want the customer to be debited on. For payouts, this means the date you want the funds to be sent from your bank account.

    - `required PaymentType PaymentType`

      The type of payment. Valid values are `charge` or `payout`.

      - `"charge"Charge`

      - `"payout"Payout`

    - `required Status Status`

      The current status of the `charge` or `payout`.

      - `"created"Created`

      - `"scheduled"Scheduled`

      - `"failed"Failed`

      - `"cancelled"Cancelled`

      - `"on_hold"OnHold`

      - `"pending"Pending`

      - `"paid"Paid`

      - `"reversed"Reversed`

      - `"validating"Validating`

    - `required StatusDetailsV1 StatusDetails`

      Details about the current status of the `charge` or `payout`.

      - `required DateTimeOffset ChangedAt`

        The time the status change occurred.

      - `required string Message`

        A human-readable description of the current status.

      - `required Reason Reason`

        A machine-readable identifier for the specific status, useful for programmatic handling.

        - `"insufficient_funds"InsufficientFunds`

        - `"closed_bank_account"ClosedBankAccount`

        - `"invalid_bank_account"InvalidBankAccount`

        - `"invalid_routing"InvalidRouting`

        - `"disputed"Disputed`

        - `"payment_stopped"PaymentStopped`

        - `"owner_deceased"OwnerDeceased`

        - `"frozen_bank_account"FrozenBankAccount`

        - `"risk_review"RiskReview`

        - `"fraudulent"Fraudulent`

        - `"duplicate_entry"DuplicateEntry`

        - `"invalid_paykey"InvalidPaykey`

        - `"payment_blocked"PaymentBlocked`

        - `"amount_too_large"AmountTooLarge`

        - `"too_many_attempts"TooManyAttempts`

        - `"internal_system_error"InternalSystemError`

        - `"user_request"UserRequest`

        - `"ok"Ok`

        - `"other_network_return"OtherNetworkReturn`

        - `"payout_refused"PayoutRefused`

        - `"cancel_request"CancelRequest`

        - `"failed_verification"FailedVerification`

        - `"require_review"RequireReview`

        - `"blocked_by_system"BlockedBySystem`

        - `"watchtower_review"WatchtowerReview`

        - `"validating"Validating`

        - `"auto_hold"AutoHold`

      - `required Source Source`

        Identifies the origin of the status change (e.g., `bank_decline`, `watchtower`). This helps in tracking the cause of status updates.

        - `"watchtower"Watchtower`

        - `"bank_decline"BankDecline`

        - `"customer_dispute"CustomerDispute`

        - `"user_action"UserAction`

        - `"system"System`

      - `string? Code`

        The status code if applicable.

    - `required IReadOnlyDictionary<string, string> TraceIds`

      Trace ids.

    - `required DateTimeOffset UpdatedAt`

      The time the `charge` or `payout` was last updated.

    - `CustomerDetailsV1 CustomerDetails`

      Information about the customer associated with the charge or payout.

      - `required string ID`

        Unique identifier for the customer

      - `required CustomerType CustomerType`

        The type of customer

        - `"individual"Individual`

        - `"business"Business`

      - `required string Email`

        The customer's email address

      - `required string Name`

        The name of the customer

      - `required string Phone`

        The customer's phone number in E.164 format

    - `DateTimeOffset? EffectiveAt`

      The actual date on which the payment occurred. For charges, this is the date the customer was debited. For payouts, this is the date the funds were sent from your bank account.

    - `string? FundingID`

      Unique identifier for the funding event associated with the `charge` or `payout`.

    - `IReadOnlyDictionary<string, string>? Metadata`

      Metadata for payment - only included if requested.

    - `PaykeyDetailsV1 PaykeyDetails`

      Information about the paykey used for the `charge` or `payout`.

      - `required string ID`

        Unique identifier for the paykey.

      - `required string CustomerID`

        Unique identifier for the customer associated with the paykey.

      - `required string Label`

        Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI

      - `Int? Balance`

        The most recent balance of the bank account associated with the paykey in dollars.

  - `required Meta Meta`

    - `required string ApiRequestID`

      Unique identifier for this API request, useful for troubleshooting.

    - `required DateTimeOffset ApiRequestTimestamp`

      Timestamp for this API request, useful for troubleshooting.

    - `required Int MaxPageSize`

      Maximum allowed page size for this endpoint.

    - `required Int PageNumber`

      Page number for paginated results.

    - `required Int PageSize`

      Number of items per page in this response.

    - `required string SortBy`

      The field that the results were sorted by.

    - `required SortOrder SortOrder`

      - `"asc"Asc`

      - `"desc"Desc`

    - `required Int TotalItems`

    - `required Int TotalPages`

      The number of pages available.

  - `required ResponseType ResponseType`

    Indicates the structure of the returned content.

    - "object" means the `data` field contains a single JSON object.
    - "array" means the `data` field contains an array of objects.
    - "error" means the `data` field contains an error object with details of the issue.
    - "none" means no data is returned.

    - `"object"Object`

    - `"array"Array`

    - `"error"Error`

    - `"none"None`

### Example

```csharp
PaymentListParams parameters = new();

var page = await client.Payments.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
```

#### Response

```json
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "amount": 10000,
      "created_at": "2019-12-27T18:11:19.117Z",
      "currency": "currency",
      "description": "Invoice payment for 100 widgets",
      "external_id": "external_id",
      "funding_ids": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "paykey": "paykey",
      "payment_date": "2019-12-27",
      "payment_type": "charge",
      "status": "created",
      "status_details": {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Payment successfully created and awaiting validation.",
        "reason": "insufficient_funds",
        "source": "system",
        "code": null
      },
      "trace_ids": {
        "foo": "string"
      },
      "updated_at": "2019-12-27T18:11:19.117Z",
      "customer_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_type": "individual",
        "email": "ron@swanson.com",
        "name": "Ron Swanson",
        "phone": "+1234567890"
      },
      "effective_at": "2019-12-27T18:11:19.117Z",
      "funding_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "metadata": {
        "foo": "string"
      },
      "paykey_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "label": "Bank of America ****1234",
        "balance": 0
      }
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}
```