An incoming_payment_detail represents a payment where your bank is the RDFI (receiving bank) and your account is the receiving account, as opposed to a payment you originate via a Payment Order. The incoming payment detail will be reconciled to a transaction when the payment arrives in your bank account. These are typically used for more advanced use cases, such as return initiation or inbound payment attribution using virtual accounts.
| Attribute | Description |
|---|---|
| idstring | Unique identifier for the incoming payment detail |
| typestring | One of: ach, au_becs, bacs, book, check, eft, interac, neft, nz_becs, rtp, sepa, signet, wire, stablecoin. |
| amountint32 | Value in specified currency's smallest unit. e.g. $10 would be represented as 1000. |
| currencystring | The currency of the incoming payment detail. |
| directionstring | One of credit, debit |
| as_of_datedate | The date on which the corresponding transaction will occur. |
| internal_account_idstring | The ID of the Internal Account for the incoming payment detail. This is always present. |
| virtual_account_idstring | If the incoming payment detail is in a virtual account, the ID of the Virtual Account. |
| virtual_accountobject | If the incoming payment detail is in a virtual account, the serialized virtual account object. |
| transaction_line_item_idstring | The ID of the reconciled Transaction Line Item or null. |
| transaction_idstring | The ID of the reconciled Transaction or null. |
| ledger_transaction_idstring | The ID of the ledger transaction linked to the incoming payment detail or null. |
| dataobject | The raw data from the payment pre-notification file that we get from the bank. This field may contain sensitive information and is not included in API responses by default. Learn more about changing your settings here. |
| statusstring | The current status of the incoming payment detail. One of pending, completed, returned, held, or failed. An incoming payment detail is held while the payment is under review. |
| failure_reasonstring | The reason the incoming payment detail failed, or null. |
| metadataobject | Additional data represented as key-value pairs. Both the key and value must be strings. See Metadata. |
| reconciliation_statusstring | The current reconciliation status. One of unreconciled, tenatively_reconciled, or reconciled. |
| live_modeboolean | This field will be true if this object exists in the live environment or false if it exists in the test environment. |
| originating_account_number_safestring | The last 4 digits of the originating account_number for the incoming payment detail. |
| originating_account_number_typestring | The type of the originating account number for the incoming payment detail. |
| originating_routing_numberstring | The routing number of the originating account for the incoming payment detail. |
| originating_routing_number_typestring | The type of the originating routing number for the incoming payment detail. |
| vendor_idstring | An identifier given to this payment detail by the bank. |
| created_atdatetime | The time at which the incoming payment detail was created. |
| updated_atdatetime | The time at which the incoming payment detail was last updated. |
{
"id": "4844bda1-eb57-4129-afb4-fc663a395ca0",
"object": "incoming_payment_detail",
"internal_account_id": "487b9a5c-6737-43ea-b11c-593f39226b92",
"virtual_account_id": null,
"virtual_account": null,
"transaction_line_item_id": null,
"transaction_id": null,
"type": "ach",
"data": { // This field may contain PII and is not included in API responses by default
"batch_header_record": {
"batch_number": "999",
"company_name": "moderntreasury.com",
"settlement_date": 17,
"service_class_code": "200",
"effective_entry_date": "2019-01-30",
"company_identification": "9999999999",
"originator_status_code": "1",
"company_descriptive_date": "",
"company_entry_description": "moderntreasury.co",
"standard_entry_class_code": "CCD",
"company_discretionary_data": "",
"originating_dfi_identification": "99999999"
},
"detail_record": {
"amount": 10000,
"trace_number": "999999999999999",
"transaction_code": "27",
"dfi_account_number": "99999",
"discretionary_data": "",
"identification_number": "moderntreasury.com",
"receiving_company_name": "EXAMPLE INC",
"addenda_record_indicator": true
},
"payment_related_information": "Lorem Ipsum",
},
"amount": 10000,
"currency": "USD",
"direction": "debit",
"status": "pending",
"reconciliation_status": "unreconciled",
"metadata": {},
"as_of_date": "2020-10-17",
"live_mode": true,
"created_at": "2020-10-15T04:23:11Z",
"updated_at": "2020-10-15T04:23:11Z"
}Example webhooks
An incoming payment detail can be created as held while the payment is under review, or as failed if the payment failed before it posted (for example, it was automatically returned). A held incoming payment detail that is rejected after review receives a failed event. The reason is in failure_reason. See Incoming Payment Detail Webhooks for all events.
{
"event": "created",
"data": {
"id": "4844bda1-eb57-4129-afb4-fc663a395ca0",
"object": "incoming_payment_detail",
"live_mode": true,
"internal_account_id": "487b9a5c-6737-43ea-b11c-593f39226b92",
"virtual_account_id": null,
"virtual_account": null,
"transaction_line_item_id": null,
"transaction_id": null,
"ledger_transaction_id": null,
"type": "rtp",
"data": {
"role": "receiving",
"payment_type": "rtp",
"message": "Credit Transfer",
"originating_party_name": "Example Corp",
"originating_routing_number": "021000021",
"originating_account_number": "123456789012"
},
"amount": 10000,
"currency": "USD",
"direction": "credit",
"status": "held",
"failure_reason": null,
"originating_routing_number": "021000021",
"originating_routing_number_type": null,
"originating_account_number": "123456789012",
"originating_account_number_safe": "9012",
"originating_account_number_type": null,
"originating_party_name": null,
"originating_party_address": null,
"originating_party_vendor_identifier": "5f2b8e1c9a7d4e3f6b0c2a9d8e7f1b3c4a5d6e7f8091a2b3c4d5e6f708192a3b",
"receiving_account_number": null,
"receiving_account_number_safe": null,
"metadata": {},
"as_of_date": "2026-10-16",
"vendor_id": "b2c4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
"subtype": null,
"reconciliation_status": "unreconciled",
"created_at": "2026-10-16T20:26:43Z",
"updated_at": "2026-10-16T20:26:43Z"
}
}{
"event": "failed",
"data": {
"id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"object": "incoming_payment_detail",
"live_mode": true,
"internal_account_id": "487b9a5c-6737-43ea-b11c-593f39226b92",
"virtual_account_id": null,
"virtual_account": null,
"transaction_line_item_id": null,
"transaction_id": null,
"ledger_transaction_id": null,
"type": "ach",
"data": {
"role": "receiving",
"payment_type": "ach",
"payment_subtype": "PPD",
"receiving_party_name": "Jane Doe",
"message": "Transfer",
"originating_party_name": "Example Corp",
"originating_ach_identifier": "9999999999"
},
"amount": 10000,
"currency": "USD",
"direction": "debit",
"status": "failed",
"failure_reason": "Insufficient funds",
"originating_routing_number": "021000021",
"originating_routing_number_type": null,
"originating_account_number": null,
"originating_account_number_safe": null,
"originating_account_number_type": null,
"originating_party_name": "Example Corp",
"originating_party_address": null,
"originating_party_vendor_identifier": "3c9e1a7b5d2f4086a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f3a5b7c9d1e3f5",
"receiving_account_number": null,
"receiving_account_number_safe": null,
"metadata": {},
"as_of_date": "2026-10-19",
"vendor_id": "c3d5e7f9-2b4c-4d6e-9f8a-0b1c2d3e4f5a",
"subtype": null,
"reconciliation_status": "unreconciled",
"created_at": "2026-10-19T14:21:40Z",
"updated_at": "2026-10-19T14:21:40Z"
}
}Example objects
Here are some sample bodies for what an incoming payment detail would look like, depending on the type of payment.
{
"id": "4844bda1-eb57-4129-afb4-fc663a395ca0",
"object": "incoming_payment_detail",
"internal_account_id": "487b9a5c-6737-43ea-b11c-593f39226b92",
"virtual_account_id": null,
"virtual_account": null,
"transaction_line_item_id": null,
"transaction_id": null,
"type": "ach",
"data": { // This field may contain PII and is not included in API responses by default
"batch_header_record": {
"batch_number": "999",
"company_name": "moderntreasury.com",
"settlement_date": 17,
"service_class_code": "200",
"effective_entry_date": "2019-01-30",
"company_identification": "9999999999",
"originator_status_code": "1",
"company_descriptive_date": "",
"company_entry_description": "moderntreasury.co",
"standard_entry_class_code": "CCD",
"company_discretionary_data": "",
"originating_dfi_identification": "99999999"
},
"detail_record": {
"amount": 10000,
"trace_number": "999999999999999",
"transaction_code": "27",
"dfi_account_number": "99999",
"discretionary_data": "",
"identification_number": "moderntreasury.com",
"receiving_company_name": "EXAMPLE INC",
"addenda_record_indicator": true
},
"payment_related_information": "Lorem Ipsum",
},
"amount": 10000,
"currency": "USD",
"direction": "debit",
"status": "pending",
"reconciliation_status": "unreconciled",
"metadata": {},
"as_of_date": "2020-10-17",
"live_mode": true,
"created_at": "2020-10-15T04:23:11Z",
"updated_at": "2020-10-15T04:23:11Z"
}{
"id": "4844bda1-eb57-4129-afb4-fc663a395ca0",
"object": "incoming_payment_detail",
"internal_account_id": "487b9a5c-6737-43ea-b11c-593f39226b92",
"virtual_account_id": null,
"virtual_account": null,
"transaction_line_item_id": null,
"transaction_id": null,
"type": "ach",
"data": { // This field may contain PII and is not included in API responses by default
"batch_header_record": {
"service_class_code": "200",
"standard_entry_class_code": "IAT",
"company_entry_description": "EXAMPLE",
"effective_entry_date": "2020-10-22",
"settlement_date": 296,
"originator_status_code": "1",
"originating_dfi_identification": "098765431",
"batch_number": "487",
"iat_indicator": "",
"foreign_exchange_indicator": "FF",
"foreign_exchange_reference_indicator": "3",
"foreign_exchange_reference": "",
"iso_destination_country_code": "US",
"originator_identification": "1234567890",
"iso_originating_currency_code": "USD",
"iso_destination_currency_code": "USD"
},
"detail_record": {
"transaction_code": "22",
"amount": 10000,
"addenda_record_indicator": true,
"trace_number": "999999999999999",
"number_of_addenda_records": 10,
"dfi_account_number": "99999",
"gateway_operator_ofac_screening_indicator": "",
"secondary_ofac_screening_indicator": "0"
},
"addenda_record": {
"transaction_type_code": "MIS",
"foreign_payment_amount": 0,
"foreign_trace_number": "",
"receiving_name": "EXAMPLE INC",
"originator_name": "Jane Doe",
"originator_street_address": "123 Main St",
"originator_locality_and_region": "San Francisco*CA\\",
"originator_country_and_postal_code": "US*94109\\",
"originating_dfi_name": "Wells Fargo",
"originating_dfi_identification_number_qualifier": "01",
"originating_dfi_identification": "99999999",
"originating_dfi_branch_country_code": "US",
"receiving_dfi_name": "SILICON VALLEY BANK",
"receiving_dfi_identification_number_qualifier": "01",
"receiving_dfi_identification": "99999999",
"receiving_dfi_branch_country_code": "US",
"receiver_identification_number": "99999999",
"receiver_street_address": "123 Main Street",
"receiver_locality_and_region": "San Francisco*CA\\",
"receiver_country_and_postal_code": "US*94107\\"
},
"payment_related_information": "Lorem Ipsum",
"foreign_corresponent_bank_records": [
{
"foreign_correspondent_bank_name": "AS LHV Pank",
"foreign_correspondent_bank_identification_number_qualifier": "02",
"foreign_correspondent_bank_identification_number": "LHVBXX00",
"foreign_correspondent_bank_branch_country_code": "EE"
}
]
},
"amount": 10000,
"currency": "USD",
"direction": "debit",
"status": "pending",
"reconciliation_status": "unreconciled",
"metadata": {},
"as_of_date": "2020-10-17",
"live_mode": true,
"created_at": "2020-10-15T04:23:11Z",
"updated_at": "2020-10-15T04:23:11Z"
}{
"id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
"data": { // This field may contain PII and is not included in API responses by default
"imad": "20210121L1B77D1C001602",
"omad": "20210121GMQFMP0100602801210908",
"reference": "20210210840500",
"sender_aba": "121140399",
"wire_amount": 10000,
"currency_code": "USD",
"originator_id": "1234567",
"account_number": "987654321",
"beneficiary_id": "987654321",
"payment_method": "Fed",
"originator_name": "BERKSHIRE HATHAWAY.",
"beneficiary_name": "BERKSHIRE HATHAWAY.",
"transaction_date": "2021-01-21",
"reference_for_bank": "",
"beneficiary_id_code": "D",
"originator_address_1": "1 Main St",
"originator_address_2": "10TH FLOOR",
"originator_address_3": "SAN FRANCISCO, CA 94104",
"wire_sequence_number": "45137763",
"beneficiary_address_1": "2 Main St.",
"beneficiary_address_2": "UNIT 12",
"beneficiary_address_3": "US",
"business_function_code": "CTR",
"transaction_description": "I",
"bank_to_bank_information": "",
"originator_to_beneficiary_information": "16E1042F27E540E5 /ROC/16E1042F27E540E5/OBI GOES HERE"
},
"type": "wire",
"amount": 10000,
"object": "incoming_payment_detail",
"status": "pending",
"reconciliation_status": "unreconciled",
"currency": "USD",
"metadata": {},
"direction": "credit",
"live_mode": true,
"as_of_date": "2021-01-21",
"created_at": "2021-01-21T17:05:39Z",
"updated_at": "2021-01-21T17:05:39Z",
"transaction_id": "00dea47c-2011-480d-ab02-44cfea7b2890",
"virtual_account_id": null,
"virtual_account": null,
"internal_account_id": "07d61aca-e5ba-4008-b00d-cfca8d7c5290",
"transaction_line_item_id": "9dde4e56-30a9-452e-a196-e0858c4dced5"
}{
"id": "9f4e35df-87d7-469e-ba1b-4d67ce10ce11",
"data": { // This field may contain PII and is not included in API responses by default
"wire_reference": "010203040506",
"fed_reference": "0003",
"ogb": "MAIN BANK POST OFFICE BOX 101 ANYTOWN, CALIFORNIA 94567-1234",
"org": "ACME FURNITURE 12345 PARKSIDE AVE. ANYTOWN , CA, 94567",
"obi": "GROUP NO 21212 3",
"bnf": "33300000222210000 ABC"
},
"type": "wire",
"amount": 20000,
"object": "incoming_payment_detail",
"status": "completed",
"reconciliation_status": "reconciled",
"currency": "USD",
"metadata": {},
"direction": "credit",
"live_mode": true,
"as_of_date": "2021-06-27",
"created_at": "2021-06-27T15:59:40Z",
"updated_at": "2021-06-27T15:59:40Z",
"transaction_id": "02464daf-84ac-416d-b0c3-8c95d8ac7b8e",
"virtual_account_id": null,
"virtual_account": null,
"internal_account_id": "168f0508-c47c-4b61-9852-213112f14ddb",
"transaction_line_item_id": "f7572374-bbec-495f-84e7-f2278df74bef"
}{
"id": "ad5e5509-0777-49d3-ac6e-25d7b46cffe8",
"data": { // This field may contain PII and is not included in API responses by default
"lockbox_number": "24869",
"deposit_date": "10/25/2018",
"check_number": "3077786220",
"remitter_name": "MODERN TREASURY",
"memo_field": "TEST"
},
"object": "incoming_payment_detail",
"live_mode": true,
"internal_account_id": "0039eb61-b3d2-49af-9f39-dddf7077ad98",
"virtual_account_id": null,
"virtual_account": null,
"transaction_line_item_id": "b6652435-df85-4e79-9cb0-c01af5e37b93",
"transaction_id": "07612f5a-24d6-4b28-8a34-70d4377abcf4",
"ledger_transaction_id": null,
"type": "check",
"amount": 115124,
"currency": "USD",
"direction": "credit",
"status": "completed",
"metadata": {},
"as_of_date": "2018-10-25",
"vendor_id": null,
"created_at": "2023-10-04T17:38:10Z",
"updated_at": "2023-11-01T22:28:15Z"
}