# List payment instruments

Returns a paginated list of payment instruments for the specified customer.

Endpoint: POST /payment-instruments/list
Version: 2.0.0
Security: bearerAuth

## Request fields (application/json):

  - `customer_id` (string, required)
    Identifier of the customer who owns the payment instruments.
    Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"

  - `filters` (object)
    Filters for payment instruments.

  - `filters.status` (object)
    Operator and value for payment instrument status filter.

  - `filters.status.operator` (string, required)
    Comparison operator.
    Enum: "EQ"

  - `filters.status.value` (string, required)
    Payment instrument status value to filter by.
    Enum: "ACTIVE", "REVOKED", "EXPIRED"

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. It is empty on the last page.
    Example: "eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ=="

## Response 200 fields (application/json):

  - `items` (array, required) — one of:
    List of payment instruments for the current page.
    - Card payment:
      - `id` (string, required)
        Unique payment instrument identifier.
        Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"
      - `customer_id` (string, required)
        Identifier of the customer who owns the payment instrument.
        Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"
      - `status` (string, required)
        Payment instrument status.
        Enum: same as `filters.status.value` (3 values)
      - `recurring_token` (string, required)
        Token used to charge the payment instrument for recurring payments.
        Example: "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
      - `expired_at` (string)
        Date and time when the payment instrument expired.
        Example: "2027-01-01T10:00:00.000000Z"
      - `revocation_reason` (string)
        Reason why the payment instrument was revoked.
        Enum: "MERCHANT_INITIATED", "SYSTEM_INITIATED"
      - `created_at` (string, required)
        Date and time when the payment instrument was created.
        Example: "2024-01-01T10:00:00.000000Z"
      - `updated_at` (string, required)
        Date and time when the payment instrument was updated.
        Example: "2024-01-02T15:00:00.000000Z"
      - `payment_method` (string, required)
        Payment method.
        Example: "CARD"
      - `card_details` (object, required)
        Card details for a payment instrument.
      - `card_details.last_four` (string, required)
        Last four digits of the card number.
        Example: "4242"
      - `card_details.bin` (string, required)
        Bank identification number of the card.
        Example: "424242"
      - `card_details.brand` (string, required)
        Card brand.
        Example: "VISA"
      - `card_details.type` (string, required)
        Card type.
        Example: "DEBIT"
      - `card_details.bank` (string, required)
        Issuing bank name.
        Example: "Chase Bank"
      - `card_details.expiry_month` (string, required)
        Card expiration month in MM format.
        Example: "12"
      - `card_details.expiry_year` (string, required)
        Card expiration year in YYYY format.
        Example: "2030"
    - Alternative payment method:
      - `id` (string, required)
        Unique payment instrument identifier.
        Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"
      - `customer_id` (string, required)
        Identifier of the customer who owns the payment instrument.
        Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"
      - `status` (string, required)
        Payment instrument status.
        Enum: same as `filters.status.value` (3 values)
      - `recurring_token` (string, required)
        Token used to charge the payment instrument for recurring payments.
        Example: "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
      - `expired_at` (string)
        Date and time when the payment instrument expired.
        Example: "2027-01-01T10:00:00.000000Z"
      - `revocation_reason` (string)
        Reason why the payment instrument was revoked.
        Enum: same as `revocation_reason` in "Card payment" (2 values)
      - `created_at` (string, required)
        Date and time when the payment instrument was created.
        Example: "2024-01-01T10:00:00.000000Z"
      - `updated_at` (string, required)
        Date and time when the payment instrument was updated.
        Example: "2024-01-02T15:00:00.000000Z"
      - `payment_method` (string, required)
        Payment method.
        Example: "PAYPAL"
      - `paypal_details` (object, required)
        PayPal details for a payment instrument.
      - `paypal_details.email` (string, required)
        PayPal account email.
        Example: "customer@example.com"

  - `pagination` (object, required)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. It is empty on the last page.
    Example: "eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ=="

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: "One or more fields failed validation due to constraints"

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.
    Example: {"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: "Credentials are invalid or missing"

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: "Permission denied"

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: "Rate limit exhausted"

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: "2024-12-31T23:59:59.000000Z"