# Funding Events ## List funding events **get** `/v1/funding_events` Retrieves a list of funding events for your account. This endpoint supports advanced sorting and filtering options. ### Query Parameters - `created_from: optional string` The start date of the range to filter by using the `YYYY-MM-DD` format. - `created_to: optional string` The end date of the range to filter by using the `YYYY-MM-DD` format. - `direction: optional "deposit" or "withdrawal"` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `"deposit"` - `"withdrawal"` - `event_type: optional "charge_deposit" or "charge_reversal" or "payout_return" or "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: optional number` Results page number. Starts at page 1. - `page_size: optional number` Results page size. Max value: 1000 - `search_text: optional string` Search text. - `sort_by: optional "transfer_date" or "id" or "amount"` The field to sort the results by. - `"transfer_date"` - `"id"` - `"amount"` - `sort_order: optional "asc" or "desc"` The order in which to sort the results. - `"asc"` - `"desc"` - `status: optional array of "created" or "scheduled" or "failed" or 6 more` Funding Event status. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `status_reason: optional array of "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 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: optional array of "watchtower" or "bank_decline" or "customer_dispute" or 2 more` Source of latest payment status change. - `"watchtower"` - `"bank_decline"` - `"customer_dispute"` - `"user_action"` - `"system"` - `trace_id: optional string` Trace Id. - `trace_number: optional string` Trace number. ### Header Parameters - `"Correlation-Id": optional string` - `"Request-Id": optional string` - `"Straddle-Account-Id": optional string` ### Returns - `FundingEventSummaryPagedV1 = object { data, meta, response_type }` - `data: array of object { id, amount, created_at, 10 more }` - `id: string` Unique identifier for the funding event. - `amount: number` The amount of the funding event in cents. - `created_at: string` Created at. - `direction: "deposit" or "withdrawal"` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `"deposit"` - `"withdrawal"` - `event_type: "charge_deposit" or "charge_reversal" or "payout_return" or "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: number` The number of payments associated with the funding event. - `trace_ids: map[string]` Trace Ids. - `trace_numbers: array of string` Trace number. - `transfer_date: string` 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: string` Updated at. - `status: optional "created" or "scheduled" or "failed" or 6 more` The current status of the `charge` or `payout`. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `status_details: optional object { changed_at, message, reason, 2 more }` - `changed_at: string` The time the status change occurred. - `message: string` A human-readable description of the current status. - `reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 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" or "bank_decline" or "customer_dispute" or 2 more` - `"watchtower"` - `"bank_decline"` - `"customer_dispute"` - `"user_action"` - `"system"` - `code: optional string` The status code if applicable. - `trace_number: optional string` The trace number of the funding event. - `meta: object { 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: string` Timestamp for this API request, useful for troubleshooting. - `max_page_size: number` Maximum allowed page size for this endpoint. - `page_number: number` Page number for paginated results. - `page_size: number` Number of items per page in this response. - `sort_by: string` The field that the results were sorted by. - `sort_order: "asc" or "desc"` - `"asc"` - `"desc"` - `total_items: number` - `total_pages: number` The number of pages available. - `response_type: "object" or "array" or "error" or "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 ```http curl https://sandbox.straddle.com/v1/funding_events \ -H "Authorization: Bearer $STRADDLE_API_KEY" ``` #### 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 **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. ### Path Parameters - `id: string` ### Header Parameters - `"Correlation-Id": optional string` - `"Request-Id": optional string` - `"Straddle-Account-Id": optional string` ### Returns - `FundingEventSummaryItemV1 = object { data, meta, response_type }` - `data: object { id, amount, created_at, 10 more }` - `id: string` Unique identifier for the funding event. - `amount: number` The amount of the funding event in cents. - `created_at: string` Created at. - `direction: "deposit" or "withdrawal"` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `"deposit"` - `"withdrawal"` - `event_type: "charge_deposit" or "charge_reversal" or "payout_return" or "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: number` The number of payments associated with the funding event. - `trace_ids: map[string]` Trace Ids. - `trace_numbers: array of string` Trace number. - `transfer_date: string` 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: string` Updated at. - `status: optional "created" or "scheduled" or "failed" or 6 more` The current status of the `charge` or `payout`. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `status_details: optional object { changed_at, message, reason, 2 more }` - `changed_at: string` The time the status change occurred. - `message: string` A human-readable description of the current status. - `reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 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" or "bank_decline" or "customer_dispute" or 2 more` - `"watchtower"` - `"bank_decline"` - `"customer_dispute"` - `"user_action"` - `"system"` - `code: optional string` The status code if applicable. - `trace_number: optional 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: string` Timestamp for this API request, useful for troubleshooting. - `response_type: "object" or "array" or "error" or "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 ```http curl https://sandbox.straddle.com/v1/funding_events/$ID \ -H "Authorization: Bearer $STRADDLE_API_KEY" ``` #### 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 - `FundingEventSummaryItemV1 = object { data, meta, response_type }` - `data: object { id, amount, created_at, 10 more }` - `id: string` Unique identifier for the funding event. - `amount: number` The amount of the funding event in cents. - `created_at: string` Created at. - `direction: "deposit" or "withdrawal"` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `"deposit"` - `"withdrawal"` - `event_type: "charge_deposit" or "charge_reversal" or "payout_return" or "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: number` The number of payments associated with the funding event. - `trace_ids: map[string]` Trace Ids. - `trace_numbers: array of string` Trace number. - `transfer_date: string` 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: string` Updated at. - `status: optional "created" or "scheduled" or "failed" or 6 more` The current status of the `charge` or `payout`. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `status_details: optional object { changed_at, message, reason, 2 more }` - `changed_at: string` The time the status change occurred. - `message: string` A human-readable description of the current status. - `reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 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" or "bank_decline" or "customer_dispute" or 2 more` - `"watchtower"` - `"bank_decline"` - `"customer_dispute"` - `"user_action"` - `"system"` - `code: optional string` The status code if applicable. - `trace_number: optional 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: string` Timestamp for this API request, useful for troubleshooting. - `response_type: "object" or "array" or "error" or "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 - `FundingEventSummaryPagedV1 = object { data, meta, response_type }` - `data: array of object { id, amount, created_at, 10 more }` - `id: string` Unique identifier for the funding event. - `amount: number` The amount of the funding event in cents. - `created_at: string` Created at. - `direction: "deposit" or "withdrawal"` Describes the direction of the funding event from the perspective of the `linked_bank_account`. - `"deposit"` - `"withdrawal"` - `event_type: "charge_deposit" or "charge_reversal" or "payout_return" or "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: number` The number of payments associated with the funding event. - `trace_ids: map[string]` Trace Ids. - `trace_numbers: array of string` Trace number. - `transfer_date: string` 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: string` Updated at. - `status: optional "created" or "scheduled" or "failed" or 6 more` The current status of the `charge` or `payout`. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `status_details: optional object { changed_at, message, reason, 2 more }` - `changed_at: string` The time the status change occurred. - `message: string` A human-readable description of the current status. - `reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 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" or "bank_decline" or "customer_dispute" or 2 more` - `"watchtower"` - `"bank_decline"` - `"customer_dispute"` - `"user_action"` - `"system"` - `code: optional string` The status code if applicable. - `trace_number: optional string` The trace number of the funding event. - `meta: object { 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: string` Timestamp for this API request, useful for troubleshooting. - `max_page_size: number` Maximum allowed page size for this endpoint. - `page_number: number` Page number for paginated results. - `page_size: number` Number of items per page in this response. - `sort_by: string` The field that the results were sorted by. - `sort_order: "asc" or "desc"` - `"asc"` - `"desc"` - `total_items: number` - `total_pages: number` The number of pages available. - `response_type: "object" or "array" or "error" or "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"`