Issue:
[FEATURE] allow payout_id to be configurable

### Feature Description

`payout_id` is an unique identifier for payout resource which is auto generated during payout creation. This field needs to be configurable during payout creation by accepting in the API.

Along with this, a `merchant_order_reference_id` needs to be added which is an unique identifier for the consumer of the API.

### Possible Implementation

Below changes are needed in payout flow across different components -

- Add `payout_id` to API models
- Add `PayoutId` domain type
- Add `merchant_order_reference_id` to API and diesel models
- Add DB queries for fetching orders using `merchant_order_reference_id`
- Add `merchant_order_reference_id` as a filter for OLAP APIs
- Use uuidv4 for payout ID creation for Wise

### Have you spent some time checking if this feature request has been raised before?

- [x] I checked and didn't find a similar issue

### Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/juspay/hyperswitch/blob/main/docs/CONTRIBUTING.md)

### Are you willing to submit a PR?

None

Resolution:
<think>
PR Context:
- Title: feat(payouts): add domain type for PayoutId
- Merged: 2025-07-01T14:45:02Z
- Files changed: 30 files
- Commits: 16 commits

Implementation approach:
feat(payouts): allow payout_id to be configurable in API request
feat(payouts): add merchant_order_reference_id for referencing payouts

## Type of Change
<!-- Put an `x` in the boxes that apply -->

- [ ] Bugfix
- [x] New feature
- [ ] Enhancement
- [x] Refactoring
- [ ] Dependency updates
- [ ] Documentation
- [ ] CI/CD

## Description
This pull request introduces two main features for payouts:

1.  **Configurable `payout_id` in API Requests**:
    *   The `payout_id` field i
</think>

To implement this, you'll need to modify:


**Detailed Implementation:**


**Commit 1:** feat(payouts): add domain type for PayoutId (#8395)
Co-authored-by: hyperswitch-bot[bot] <148525504+
Files to modify:


**crates/api_models/src/events/payouts.rs**
  Modify existing code

**crates/api_models/src/payouts.rs**
  Modify existing code

**crates/api_models/src/webhooks.rs**
  Modify existing code

**crates/common_utils/src/events.rs**
  Modify existing code

**crates/common_utils/src/id_type.rs**
  Add:
    - mod: private::payout

**crates/common_utils/src/id_type/payout.rs**
  Modify existing code

**crates/common_utils/src/link_utils.rs**
  Modify existing code

**crates/diesel_models/src/events.rs**
  Modify existing code

**crates/diesel_models/src/generic_link.rs**
  Modify existing code

**crates/diesel_models/src/payout_attempt.rs**
  Modify existing code

**crates/diesel_models/src/payouts.rs**
  Modify existing code

**crates/diesel_models/src/query/generic_link.rs**
  Modify existing code

**crates/diesel_models/src/query/payout_attempt.rs**
  Add:
    - function: pub::find_by_merchant_id_merchant_order_reference_id

**crates/diesel_models/src/query/payouts.rs**
  Modify existing code

**crates/diesel_models/src/schema.rs**
  Modify existing code

**crates/diesel_models/src/schema_v2.rs**
  Modify existing code

**crates/hyperswitch_connectors/src/connectors/adyen/transformers.rs**
  Modify existing code

**crates/hyperswitch_connectors/src/connectors/adyenplatform/transformers/payouts.rs**
  Modify existing code

**crates/hyperswitch_connectors/src/connectors/cybersource/transformers.rs**
  Modify existing code

**crates/hyperswitch_connectors/src/connectors/nomupay/transformers.rs**
  Modify existing code

**crates/hyperswitch_connectors/src/connectors/paypal/transformers.rs**
  Modify existing code

**crates/hyperswitch_connectors/src/connectors/stripe/transformers/connect.rs**
  Modify existing code

**crates/hyperswitch_connectors/src/connectors/wise/transformers.rs**
  Modify existing code

**crates/hyperswitch_domain_models/src/errors/api_error_response.rs**
  Modify existing code

**crates/hyperswitch_domain_models/src/payouts.rs**
  Modify existing code

**crates/hyperswitch_domain_models/src/payouts/payout_attempt.rs**
  Modify existing code

**crates/hyperswitch_domain_models/src/payouts/payouts.rs**
  Modify existing code

**crates/hyperswitch_domain_models/src/router_request_types.rs**
  Modify existing code

**crates/router/src/compatibility/stripe/errors.rs**
  Modify existing code

**crates/router/src/compatibility/stripe/webhooks.rs**
  Modify existing code

**crates/router/src/core/payments/routing.rs**
  Modify existing code

**crates/router/src/core/payout_link.rs**
  Modify existing code

**crates/router/src/core/payouts.rs**
  Modify existing code

**crates/router/src/core/payouts/helpers.rs**
  Modify existing code

**crates/router/src/core/payouts/retry.rs**
  Modify existing code

**crates/router/src/core/payouts/transformers.rs**
  Modify existing code

**crates/router/src/core/payouts/validator.rs**
  Modify existing code

**crates/router/src/core/utils.rs**
  Remove:
    - function: pub::get_or_generate_uuid
    - function: pub::validate_uuid

**crates/router/src/core/webhooks/incoming.rs**
  Modify existing code

**crates/router/src/db/kafka_store.rs**
  Add:
    - function: private::find_payout_attempt_by_merchant_id_merchant_order_reference_id

**crates/router/src/events/outgoing_webhook_logs.rs**
  Modify existing code

**crates/router/src/routes/payout_link.rs**
  Modify existing code

**crates/router/src/routes/payouts.rs**
  Modify existing code

**crates/router/src/services/kafka/payout.rs**
  Modify existing code

**crates/router/src/utils.rs**
  Remove:
    - function: pub::generate_uuid

**crates/router/src/workflows/outgoing_webhook_retry.rs**
  Modify existing code

**crates/router/tests/connectors/utils.rs**
  Modify existing code

**crates/storage_impl/src/lib.rs**
  Modify existing code

**crates/storage_impl/src/mock_db/payout_attempt.rs**
  Add:
    - function: private::find_payout_attempt_by_merchant_id_merchant_order_reference_id

**crates/storage_impl/src/mock_db/payouts.rs**
  Modify existing code

**crates/storage_impl/src/payouts/payout_attempt.rs**
  Add:
    - function: private::find_payout_attempt_by_merchant_id_merchant_order_reference_id
    - function: private::find_payout_attempt_by_merchant_id_merchant_order_reference_id

**crates/storage_impl/src/payouts/payouts.rs**
  Modify existing code

**crates/storage_impl/src/redis/kv_store.rs**
  Modify existing code