# Funding Events ## List funding events `funding_events.list(**kwargs) -> PageNumberSchema<{ id, amount, created_at, 10 more}>` **get** `/v1/funding_events` Retrieves a list of funding events for your account. This endpoint supports advanced sorting and filtering options. ### Parameters - `created_from: Date` The start date of the range to filter by using the `YYYY-MM-DD` format. - `created_to: Date` The end date of the range to filter by using the `YYYY-MM-DD` format. - `direction: :deposit | :withdrawal` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `:deposit` - `:withdrawal` - `event_type: :charge_deposit | :charge_reversal | :payout_return | :payout_withdrawal` The funding event types describes the direction and reason for the funding event. - `:charge_deposit` - `:charge_reversal` - `:payout_return` - `:payout_withdrawal` - `page_number: Integer` Results page number. Starts at page 1. - `page_size: Integer` Results page size. Max value: 1000 - `search_text: String` Search text. - `sort_by: :transfer_date | :id | :amount` The field to sort the results by. - `:transfer_date` - `:id` - `:amount` - `sort_order: :asc | :desc` The order in which to sort the results. - `:asc` - `:desc` - `status: Array[:created | :scheduled | :failed | 6 more]` Funding Event status. - `:created` - `:scheduled` - `:failed` - `:cancelled` - `:on_hold` - `:pending` - `:paid` - `:reversed` - `:validating` - `status_reason: Array[:insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more]` Reason for latest payment status change. - `:insufficient_funds` - `:closed_bank_account` - `:invalid_bank_account` - `:invalid_routing` - `:disputed` - `:payment_stopped` - `:owner_deceased` - `:frozen_bank_account` - `:risk_review` - `:fraudulent` - `:duplicate_entry` - `:invalid_paykey` - `:payment_blocked` - `:amount_too_large` - `:too_many_attempts` - `:internal_system_error` - `:user_request` - `:ok` - `:other_network_return` - `:payout_refused` - `:cancel_request` - `:failed_verification` - `:require_review` - `:blocked_by_system` - `:watchtower_review` - `:validating` - `:auto_hold` - `status_source: Array[:watchtower | :bank_decline | :customer_dispute | 2 more]` Source of latest payment status change. - `:watchtower` - `:bank_decline` - `:customer_dispute` - `:user_action` - `:system` - `trace_id: String` Trace Id. - `trace_number: String` Trace number. - `correlation_id: String` - `request_id: String` - `straddle_account_id: String` ### Returns - `{ id, amount, created_at, 10 more}` - `id: String` Unique identifier for the funding event. - `amount: Integer` The amount of the funding event in cents. - `created_at: Time` Created at. - `direction: :deposit | :withdrawal` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `:deposit` - `:withdrawal` - `event_type: :charge_deposit | :charge_reversal | :payout_return | :payout_withdrawal` The funding event types describes the direction and reason for the funding event. - `:charge_deposit` - `:charge_reversal` - `:payout_return` - `:payout_withdrawal` - `payment_count: Integer` The number of payments associated with the funding event. - `trace_ids: Hash[Symbol, String]` Trace Ids. - `trace_numbers: Array[String]` Trace number. - `transfer_date: Date` The date on which the funding event occurred. For `deposits` and `returns`, this is the date the funds were credited to your bank account. For `withdrawals` and `reversals`, this is the date the funds were debited from your bank account. - `updated_at: Time` Updated at. - `status: :created | :scheduled | :failed | 6 more` The current status of the `charge` or `payout`. - `:created` - `:scheduled` - `:failed` - `:cancelled` - `:on_hold` - `:pending` - `:paid` - `:reversed` - `:validating` - `status_details: { changed_at, message, reason, 2 more}` - `changed_at: Time` The time the status change occurred. - `message: String` A human-readable description of the current status. - `reason: :insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more` - `:insufficient_funds` - `:closed_bank_account` - `:invalid_bank_account` - `:invalid_routing` - `:disputed` - `:payment_stopped` - `:owner_deceased` - `:frozen_bank_account` - `:risk_review` - `:fraudulent` - `:duplicate_entry` - `:invalid_paykey` - `:payment_blocked` - `:amount_too_large` - `:too_many_attempts` - `:internal_system_error` - `:user_request` - `:ok` - `:other_network_return` - `:payout_refused` - `:cancel_request` - `:failed_verification` - `:require_review` - `:blocked_by_system` - `:watchtower_review` - `:validating` - `:auto_hold` - `source: :watchtower | :bank_decline | :customer_dispute | 2 more` - `:watchtower` - `:bank_decline` - `:customer_dispute` - `:user_action` - `:system` - `code: String` The status code if applicable. - `trace_number: String` The trace number of the funding event. ### Example ```ruby require "straddle" straddle = Straddle::Client.new( api_key: "My API Key", environment: "production" # defaults to "sandbox" ) page = straddle.funding_events.list puts(page) ``` #### Response ```json { "data": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "amount": 100000, "created_at": "2019-12-27T18:11:19.117Z", "direction": "deposit", "event_type": "charge_deposit", "payment_count": 0, "trace_ids": { "foo": "string" }, "trace_numbers": [ "string" ], "transfer_date": "2019-12-27", "updated_at": "2019-12-27T18:11:19.117Z", "status": "created", "status_details": { "changed_at": "2019-12-27T18:11:19.117Z", "message": "Bank account sucesfully validated", "reason": "insufficient_funds", "source": "watchtower", "code": "code" }, "trace_number": "trace_number" } ], "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" } ``` ## Lookup a funding event `funding_events.get(id, **kwargs) -> FundingEventSummaryItemV1` **get** `/v1/funding_events/{id}` Retrieves the details of an existing funding event. Supply the unique funding event `id`, and Straddle will return the individual transaction items that make up the funding event. ### Parameters - `id: String` - `correlation_id: String` - `request_id: String` - `straddle_account_id: String` ### Returns - `class FundingEventSummaryItemV1` - `data: { id, amount, created_at, 10 more}` - `id: String` Unique identifier for the funding event. - `amount: Integer` The amount of the funding event in cents. - `created_at: Time` Created at. - `direction: :deposit | :withdrawal` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `:deposit` - `:withdrawal` - `event_type: :charge_deposit | :charge_reversal | :payout_return | :payout_withdrawal` The funding event types describes the direction and reason for the funding event. - `:charge_deposit` - `:charge_reversal` - `:payout_return` - `:payout_withdrawal` - `payment_count: Integer` The number of payments associated with the funding event. - `trace_ids: Hash[Symbol, String]` Trace Ids. - `trace_numbers: Array[String]` Trace number. - `transfer_date: Date` The date on which the funding event occurred. For `deposits` and `returns`, this is the date the funds were credited to your bank account. For `withdrawals` and `reversals`, this is the date the funds were debited from your bank account. - `updated_at: Time` Updated at. - `status: :created | :scheduled | :failed | 6 more` The current status of the `charge` or `payout`. - `:created` - `:scheduled` - `:failed` - `:cancelled` - `:on_hold` - `:pending` - `:paid` - `:reversed` - `:validating` - `status_details: { changed_at, message, reason, 2 more}` - `changed_at: Time` The time the status change occurred. - `message: String` A human-readable description of the current status. - `reason: :insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more` - `:insufficient_funds` - `:closed_bank_account` - `:invalid_bank_account` - `:invalid_routing` - `:disputed` - `:payment_stopped` - `:owner_deceased` - `:frozen_bank_account` - `:risk_review` - `:fraudulent` - `:duplicate_entry` - `:invalid_paykey` - `:payment_blocked` - `:amount_too_large` - `:too_many_attempts` - `:internal_system_error` - `:user_request` - `:ok` - `:other_network_return` - `:payout_refused` - `:cancel_request` - `:failed_verification` - `:require_review` - `:blocked_by_system` - `:watchtower_review` - `:validating` - `:auto_hold` - `source: :watchtower | :bank_decline | :customer_dispute | 2 more` - `:watchtower` - `:bank_decline` - `:customer_dispute` - `:user_action` - `:system` - `code: String` The status code if applicable. - `trace_number: String` The trace number of the funding event. - `meta: ResponseMetadata` Metadata about the API request, including an identifier and timestamp. - `api_request_id: String` Unique identifier for this API request, useful for troubleshooting. - `api_request_timestamp: Time` Timestamp for this API request, useful for troubleshooting. - `response_type: :object | :array | :error | :none` 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` - `:array` - `:error` - `:none` ### Example ```ruby require "straddle" straddle = Straddle::Client.new( api_key: "My API Key", environment: "production" # defaults to "sandbox" ) funding_event_summary_item_v1 = straddle.funding_events.get("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e") puts(funding_event_summary_item_v1) ``` #### Response ```json { "data": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "amount": 100000, "created_at": "2019-12-27T18:11:19.117Z", "direction": "deposit", "event_type": "charge_deposit", "payment_count": 0, "trace_ids": { "foo": "string" }, "trace_numbers": [ "string" ], "transfer_date": "2019-12-27", "updated_at": "2019-12-27T18:11:19.117Z", "status": "created", "status_details": { "changed_at": "2019-12-27T18:11:19.117Z", "message": "Bank account sucesfully validated", "reason": "insufficient_funds", "source": "watchtower", "code": "code" }, "trace_number": "trace_number" }, "meta": { "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "api_request_timestamp": "2019-12-27T18:11:19.117Z" }, "response_type": "object" } ``` ## Domain Types ### Funding Event Summary Item V1 - `class FundingEventSummaryItemV1` - `data: { id, amount, created_at, 10 more}` - `id: String` Unique identifier for the funding event. - `amount: Integer` The amount of the funding event in cents. - `created_at: Time` Created at. - `direction: :deposit | :withdrawal` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `:deposit` - `:withdrawal` - `event_type: :charge_deposit | :charge_reversal | :payout_return | :payout_withdrawal` The funding event types describes the direction and reason for the funding event. - `:charge_deposit` - `:charge_reversal` - `:payout_return` - `:payout_withdrawal` - `payment_count: Integer` The number of payments associated with the funding event. - `trace_ids: Hash[Symbol, String]` Trace Ids. - `trace_numbers: Array[String]` Trace number. - `transfer_date: Date` The date on which the funding event occurred. For `deposits` and `returns`, this is the date the funds were credited to your bank account. For `withdrawals` and `reversals`, this is the date the funds were debited from your bank account. - `updated_at: Time` Updated at. - `status: :created | :scheduled | :failed | 6 more` The current status of the `charge` or `payout`. - `:created` - `:scheduled` - `:failed` - `:cancelled` - `:on_hold` - `:pending` - `:paid` - `:reversed` - `:validating` - `status_details: { changed_at, message, reason, 2 more}` - `changed_at: Time` The time the status change occurred. - `message: String` A human-readable description of the current status. - `reason: :insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more` - `:insufficient_funds` - `:closed_bank_account` - `:invalid_bank_account` - `:invalid_routing` - `:disputed` - `:payment_stopped` - `:owner_deceased` - `:frozen_bank_account` - `:risk_review` - `:fraudulent` - `:duplicate_entry` - `:invalid_paykey` - `:payment_blocked` - `:amount_too_large` - `:too_many_attempts` - `:internal_system_error` - `:user_request` - `:ok` - `:other_network_return` - `:payout_refused` - `:cancel_request` - `:failed_verification` - `:require_review` - `:blocked_by_system` - `:watchtower_review` - `:validating` - `:auto_hold` - `source: :watchtower | :bank_decline | :customer_dispute | 2 more` - `:watchtower` - `:bank_decline` - `:customer_dispute` - `:user_action` - `:system` - `code: String` The status code if applicable. - `trace_number: String` The trace number of the funding event. - `meta: ResponseMetadata` Metadata about the API request, including an identifier and timestamp. - `api_request_id: String` Unique identifier for this API request, useful for troubleshooting. - `api_request_timestamp: Time` Timestamp for this API request, useful for troubleshooting. - `response_type: :object | :array | :error | :none` 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` - `:array` - `:error` - `:none` ### Funding Event Summary Paged V1 - `class FundingEventSummaryPagedV1` - `data: Array[{ id, amount, created_at, 10 more}]` - `id: String` Unique identifier for the funding event. - `amount: Integer` The amount of the funding event in cents. - `created_at: Time` Created at. - `direction: :deposit | :withdrawal` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `:deposit` - `:withdrawal` - `event_type: :charge_deposit | :charge_reversal | :payout_return | :payout_withdrawal` The funding event types describes the direction and reason for the funding event. - `:charge_deposit` - `:charge_reversal` - `:payout_return` - `:payout_withdrawal` - `payment_count: Integer` The number of payments associated with the funding event. - `trace_ids: Hash[Symbol, String]` Trace Ids. - `trace_numbers: Array[String]` Trace number. - `transfer_date: Date` The date on which the funding event occurred. For `deposits` and `returns`, this is the date the funds were credited to your bank account. For `withdrawals` and `reversals`, this is the date the funds were debited from your bank account. - `updated_at: Time` Updated at. - `status: :created | :scheduled | :failed | 6 more` The current status of the `charge` or `payout`. - `:created` - `:scheduled` - `:failed` - `:cancelled` - `:on_hold` - `:pending` - `:paid` - `:reversed` - `:validating` - `status_details: { changed_at, message, reason, 2 more}` - `changed_at: Time` The time the status change occurred. - `message: String` A human-readable description of the current status. - `reason: :insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more` - `:insufficient_funds` - `:closed_bank_account` - `:invalid_bank_account` - `:invalid_routing` - `:disputed` - `:payment_stopped` - `:owner_deceased` - `:frozen_bank_account` - `:risk_review` - `:fraudulent` - `:duplicate_entry` - `:invalid_paykey` - `:payment_blocked` - `:amount_too_large` - `:too_many_attempts` - `:internal_system_error` - `:user_request` - `:ok` - `:other_network_return` - `:payout_refused` - `:cancel_request` - `:failed_verification` - `:require_review` - `:blocked_by_system` - `:watchtower_review` - `:validating` - `:auto_hold` - `source: :watchtower | :bank_decline | :customer_dispute | 2 more` - `:watchtower` - `:bank_decline` - `:customer_dispute` - `:user_action` - `:system` - `code: String` The status code if applicable. - `trace_number: String` The trace number of the funding event. - `meta: { api_request_id, api_request_timestamp, max_page_size, 6 more}` - `api_request_id: String` Unique identifier for this API request, useful for troubleshooting. - `api_request_timestamp: Time` Timestamp for this API request, useful for troubleshooting. - `max_page_size: Integer` Maximum allowed page size for this endpoint. - `page_number: Integer` Page number for paginated results. - `page_size: Integer` Number of items per page in this response. - `sort_by: String` The field that the results were sorted by. - `sort_order: :asc | :desc` - `:asc` - `:desc` - `total_items: Integer` - `total_pages: Integer` The number of pages available. - `response_type: :object | :array | :error | :none` 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` - `:array` - `:error` - `:none`