Skip to content

feat(payments): add PaymentListFilterConstraints and payments_list_by_filter endpoint for v2 #8794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

ayush22667
Copy link
Contributor

@ayush22667 ayush22667 commented Jul 29, 2025

Type of Change

  • Bugfix
  • New feature
  • Enhancement
  • Refactoring
  • Dependency updates
  • Documentation
  • CI/CD

Description

Enhanced Payment Listing API with Multi-Value Filtering

This feature adds support for retrieving a filtered list of payments via a GET /v2/payments/list endpoint where multiple values can be provided for a single filter key (e.g. status, currency, connector, etc.).

Additional Changes

  • This PR modifies the API contract
  • This PR modifies the database schema
  • This PR modifies application configuration/environment variables

Motivation and Context

How did you test it?

GetRequest:

curl --location 'http://localhost:8080/v2/payments/list' \
--header 'api-key: dev_tP1IAK95c65hjO7NvF3dRliuiMuSIFhIeFjXBb1du3NZ1Ui6Av0XKyL3ONtB7tpy' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: pro_G9buhoAY3Mpu9cFIeWoZ' \
--header 'Authorization: api-key=dev_tP1IAK95c65hjO7NvF3dRliuiMuSIFhIeFjXBb1du3NZ1Ui6Av0XKyL3ONtB7tpy' \
--data ''

GetResponse:

{
    "count": 4,
    "total_count": 4,
    "data": [
        {
            "id": "12345_pay_01987e212eac7b23986ab9afee1d4f3f",
            "merchant_id": "cloth_seller_qNqGZXs31yvrAlmFG1Jj",
            "profile_id": "pro_G9buhoAY3Mpu9cFIeWoZ",
            "customer_id": null,
            "payment_method_id": null,
            "status": "requires_payment_method",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-06T06:46:00.627Z",
            "payment_method_type": null,
            "payment_method_subtype": null,
            "connector": null,
            "merchant_connector_id": null,
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "manual",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": null
        },
        {
            "id": "12345_pay_01987e212d6f7af18f54d484b9afad2f",
            "merchant_id": "cloth_seller_qNqGZXs31yvrAlmFG1Jj",
            "profile_id": "pro_G9buhoAY3Mpu9cFIeWoZ",
            "customer_id": null,
            "payment_method_id": null,
            "status": "requires_payment_method",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-06T06:46:00.316Z",
            "payment_method_type": null,
            "payment_method_subtype": null,
            "connector": null,
            "merchant_connector_id": null,
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "manual",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": null
        },
        {
            "id": "12345_pay_01987e212b497a7394a404b857f156bf",
            "merchant_id": "cloth_seller_qNqGZXs31yvrAlmFG1Jj",
            "profile_id": "pro_G9buhoAY3Mpu9cFIeWoZ",
            "customer_id": null,
            "payment_method_id": null,
            "status": "requires_payment_method",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-06T06:45:59.767Z",
            "payment_method_type": null,
            "payment_method_subtype": null,
            "connector": null,
            "merchant_connector_id": null,
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "manual",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": null
        },
        {
            "id": "12345_pay_01987e1fa70c7bb18fea2a1667c32e5e",
            "merchant_id": "cloth_seller_qNqGZXs31yvrAlmFG1Jj",
            "profile_id": "pro_G9buhoAY3Mpu9cFIeWoZ",
            "customer_id": null,
            "payment_method_id": null,
            "status": "requires_payment_method",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-06T06:44:20.386Z",
            "payment_method_type": null,
            "payment_method_subtype": null,
            "connector": null,
            "merchant_connector_id": null,
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "manual",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": null
        }
    ]
}

GETRequestWithMultipleFilters:

curl --location 'http://localhost:8080/v2/payments/list?status=requires_payment_method%2Crequires_capture%2Csucceeded&currency=USD' \
--header 'api-key: dev_0M1HsoPENAKVcLprxBkqXvtLLA8myjdVHFUDvvknNykT1jlEdww31C8VNcj3emYL' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: pro_qBIx1HzjxmvyeDgJmZLd' \
--header 'Authorization: api-key=dev_0M1HsoPENAKVcLprxBkqXvtLLA8myjdVHFUDvvknNykT1jlEdww31C8VNcj3emYL' \
--data ''

PostResponse:

{
    "count": 6,
    "total_count": 6,
    "data": [
        {
            "id": "12345_pay_019897db488f74b2ace8d4f34a1afd2e",
            "merchant_id": "cloth_seller_EWd2xVEKmKewu5gHgXMY",
            "profile_id": "pro_qBIx1HzjxmvyeDgJmZLd",
            "customer_id": null,
            "payment_method_id": null,
            "status": "succeeded",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": 100
            },
            "created": "2025-08-11T06:39:47.356Z",
            "payment_method_type": "card",
            "payment_method_subtype": "credit",
            "connector": "authorizedotnet",
            "merchant_connector_id": "mca_t6Qa8RtV3MHmRAHlu1Zi",
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": "80043331424",
            "connector_response_reference_id": "80043331424",
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "automatic",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": "2025-08-11T06:39:50.721Z"
        },
        {
            "id": "12345_pay_019897db458a7650b52dc95d1d2cedc5",
            "merchant_id": "cloth_seller_EWd2xVEKmKewu5gHgXMY",
            "profile_id": "pro_qBIx1HzjxmvyeDgJmZLd",
            "customer_id": null,
            "payment_method_id": null,
            "status": "requires_payment_method",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-11T06:39:46.589Z",
            "payment_method_type": null,
            "payment_method_subtype": null,
            "connector": null,
            "merchant_connector_id": null,
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "automatic",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": null
        },
        {
            "id": "12345_pay_019897db02ff7e10b129a3df71b09aaf",
            "merchant_id": "cloth_seller_EWd2xVEKmKewu5gHgXMY",
            "profile_id": "pro_qBIx1HzjxmvyeDgJmZLd",
            "customer_id": null,
            "payment_method_id": null,
            "status": "requires_payment_method",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-11T06:39:29.562Z",
            "payment_method_type": null,
            "payment_method_subtype": null,
            "connector": null,
            "merchant_connector_id": null,
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "automatic",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": null
        },
        {
            "id": "12345_pay_019897db003876b1b5f57f8d4c27072d",
            "merchant_id": "cloth_seller_EWd2xVEKmKewu5gHgXMY",
            "profile_id": "pro_qBIx1HzjxmvyeDgJmZLd",
            "customer_id": null,
            "payment_method_id": null,
            "status": "requires_payment_method",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-11T06:39:28.839Z",
            "payment_method_type": null,
            "payment_method_subtype": null,
            "connector": null,
            "merchant_connector_id": null,
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "automatic",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": null
        },
        {
            "id": "12345_pay_019897dafd2070c1956d1af439088873",
            "merchant_id": "cloth_seller_EWd2xVEKmKewu5gHgXMY",
            "profile_id": "pro_qBIx1HzjxmvyeDgJmZLd",
            "customer_id": null,
            "payment_method_id": null,
            "status": "requires_payment_method",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-11T06:39:28.045Z",
            "payment_method_type": null,
            "payment_method_subtype": null,
            "connector": null,
            "merchant_connector_id": null,
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "automatic",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": null
        },
        {
            "id": "12345_pay_019897dae26871f2be542d43fc570b13",
            "merchant_id": "cloth_seller_EWd2xVEKmKewu5gHgXMY",
            "profile_id": "pro_qBIx1HzjxmvyeDgJmZLd",
            "customer_id": null,
            "payment_method_id": null,
            "status": "succeeded",
            "amount": {
                "order_amount": 100,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 100,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": 100
            },
            "created": "2025-08-11T06:39:21.215Z",
            "payment_method_type": "card",
            "payment_method_subtype": "credit",
            "connector": "authorizedotnet",
            "merchant_connector_id": "mca_t6Qa8RtV3MHmRAHlu1Zi",
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": "80043331420",
            "connector_response_reference_id": "80043331420",
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "automatic",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": null,
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": "2025-08-11T06:39:26.628Z"
        }
    ]
}

GetRequestWithTimeDuration:

curl --location 'http://localhost:8080/v2/payments/list?status=requires_payment_method%2Crequires_capture%2Csucceeded&currency=USD&created.gte=2025-08-01T00%3A00%3A00Z&created.lte=2025-08-09T23%3A59%3A59Z' \
--header 'api-key: dev_SfzD1JfNBMBwIxi6S55ku8kCXpt665huoFrJv1hnIFERGXNIUWldBQaOMJiHE0de' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: pro_E7U8C0vjFGXvuaVEGH4M' \
--header 'Authorization: api-key=dev_SfzD1JfNBMBwIxi6S55ku8kCXpt665huoFrJv1hnIFERGXNIUWldBQaOMJiHE0de' \
--data ''

Response:

{
    "count": 0,
     "total_count": 0,
    "data": []
}

GetRequestWithTimeDuration:

curl --location 'http://localhost:8080/v2/payments/list?status=failed&currency=USD&created.gte=2025-08-01T00%3A00%3A00Z&created.lte=2025-08-31T23%3A59%3A59Z' \
--header 'api-key: dev_SfzD1JfNBMBwIxi6S55ku8kCXpt665huoFrJv1hnIFERGXNIUWldBQaOMJiHE0de' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: pro_E7U8C0vjFGXvuaVEGH4M' \
--header 'Authorization: api-key=dev_SfzD1JfNBMBwIxi6S55ku8kCXpt665huoFrJv1hnIFERGXNIUWldBQaOMJiHE0de' \
--data ''

Response:

{
    "count": 1,
     "total_count": 1,
    "data": [
        {
            "id": "12345_pay_01989e70b0fc7e219eb6352105ccd06f",
            "merchant_id": "cloth_seller_bdCHKB6LXsvpWlKKcios",
            "profile_id": "pro_E7U8C0vjFGXvuaVEGH4M",
            "customer_id": "12345_cus_01989e7025b471c0ace0c31e46b83360",
            "payment_method_id": null,
            "status": "failed",
            "amount": {
                "order_amount": 10000,
                "currency": "USD",
                "shipping_cost": null,
                "order_tax_amount": null,
                "external_tax_calculation": "skip",
                "surcharge_calculation": "skip",
                "surcharge_amount": null,
                "tax_on_surcharge": null,
                "net_amount": 10000,
                "amount_to_capture": null,
                "amount_capturable": 0,
                "amount_captured": null
            },
            "created": "2025-08-12T13:20:42.244Z",
            "payment_method_type": "card",
            "payment_method_subtype": "credit",
            "connector": "trustpay",
            "merchant_connector_id": "mca_Z9a58zhABpHduskbCsf9",
            "customer": null,
            "merchant_reference_id": null,
            "connector_payment_id": null,
            "connector_response_reference_id": null,
            "metadata": null,
            "description": null,
            "authentication_type": "no_three_ds",
            "capture_method": "automatic",
            "setup_future_usage": "on_session",
            "attempt_count": 0,
            "error": {
                "code": "4",
                "message": "4",
                "unified_code": null,
                "unified_message": null,
                "network_advice_code": null,
                "network_decline_code": null,
                "network_error_message": null
            },
            "cancellation_reason": null,
            "order_details": null,
            "return_url": null,
            "statement_descriptor": null,
            "allowed_payment_method_types": null,
            "authorization_count": 0,
            "modified_at": "2025-08-12T13:20:47.624Z"
        }
    ]
}

Closes #8792

Checklist

  • I formatted the code cargo +nightly fmt --all
  • I addressed lints thrown by cargo clippy
  • I reviewed the submitted code
  • I added unit tests for my changes where possible

@ayush22667 ayush22667 self-assigned this Jul 29, 2025
@ayush22667 ayush22667 requested review from a team as code owners July 29, 2025 14:30
Copy link

semanticdiff-com bot commented Jul 29, 2025

@hyperswitch-bot hyperswitch-bot bot added the M-api-contract-changes Metadata: This PR involves API contract changes label Jul 30, 2025
@ayush22667 ayush22667 force-pushed the feat/payments-list branch 2 times, most recently from b8b2dd9 to ece571d Compare July 30, 2025 09:22
@hyperswitch-bot hyperswitch-bot bot removed the M-api-contract-changes Metadata: This PR involves API contract changes label Aug 4, 2025
@tsdk02 tsdk02 changed the title feat(payments): add PaymentListFilterConstraints and payments_list_by… feat(payments): add PaymentListFilterConstraints and payments_list_by_filter endpoint for v2 Aug 7, 2025
… support multiple connectors and filter options
@hyperswitch-bot hyperswitch-bot bot added the M-api-contract-changes Metadata: This PR involves API contract changes label Aug 11, 2025
AnuthaDev
AnuthaDev previously approved these changes Aug 11, 2025
@tsdk02 tsdk02 removed request for a team August 11, 2025 09:41
@AnuthaDev AnuthaDev self-requested a review August 13, 2025 11:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
api-v2 M-api-contract-changes Metadata: This PR involves API contract changes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[FEATURE] Add Payments - List endpoint for v2
2 participants