Incoming Payment Details

An incoming_payment_detail is a pre-notification for an incoming payment that you will be receiving, as opposed to one you originated with a payment order, for example. 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. They are currently supported at the following banks:

  • Increase (ACH)
  • Silicon Valley Bank (ACH)
  • Metropolitan Commercial Bank (ACH and wires)
  • JP Morgan Chase (ACH and wires)
  • Silvergate Bank (wires)
  • Wells Fargo (wires)
  • Signature Bank NY (Signet)
  • BankProv (wires, available only on file-based integrations)
  • Goldman Sachs (ACH and wires)
AttributeDescription
id
string
Unique identifier for the incoming payment detail
type
string
One of: ach, book, check, eft, interac, rtp, sepa, signet, wire.
amount
int32
Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
currency
string
The currency of the incoming payment detail.
direction
string
One of credit, debit
as_of_date
date
The date on which the corresponding transaction will occur.
internal_account_id
string
The ID of the Internal Account for the incoming payment detail. This is always present.
virtual_account_id
string
If the incoming payment detail is in a virtual account, the ID of the Virtual Account.
virtual_account
object
If the incoming payment detail is in a virtual account, the serialized virtual account object.
transaction_line_item_id
string
The ID of the reconciled Transaction Line Item or null.
transaction_id
string
The ID of the reconciled Transaction or null.
data
object
The raw data from the payment pre-notification file that we get from the bank.
status
string
The current status of the incoming payment order. One of pending, completed, or returned.
metadata
object
Additional data represented as key-value pairs. Both the key and value must be strings. See Metadata.
live_mode
boolean
This field will be true if this object exists in the live environment or false if it exists in the test environment.
{
  "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": {
    "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",
  "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 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": {
    "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",
  "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": {
    "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",
  "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": {
    "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",
  "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": "147f8392-48c1-46b4-ada2-cb54834bcb62",
  "data": {
    "imad": "20210319192392139213",
    "omad": "20210319QIFJEIHR129312932193",
    "reference": "123213213FS",
    "sender_aba": "021000021",
    "sender_name": "SENDER NAME",
    "wire_amount": 10000,
    "currency_code": "USD",
    "originator_id": "/IJF1232h2312h3",
    "account_number": "19232182",
    "beneficiary_id": "19232182",
    "payment_method": "Fed",
    "originator_name": "1/ORIGINATOR NAME",
    "beneficiary_name": "1/BENEFICIARY NAME",
    "transaction_date": "2021-03-19",
    "reference_for_bank": "SWF OF 21/03/19",
    "beneficiary_id_code": "D",
    "originator_address_1": "1 MAIN ST",
    "originator_address_2": "",
    "originator_address_3": "1/US/SAN FRANCISCO",
    "originator_bank_id": "123456789",
    "originator_bank_name": "GRINGOTTS WIZARDING BANK",
    "originator_bank_address_1": "1 DIAGON ALLEY",
    "originator_bank_address_2": "",
    "originator_bank_address_3": "",
    "intermediary_bank_id": "",
    "intermediary_bank_name": "",
    "intermediary_bank_address_1": "",
    "intermediary_bank_address_2": "",
    "intermediary_bank_address_3": "",
    "wire_sequence_number": "12321312",
    "beneficiary_bank_id": "987654321",
    "beneficiary_bank_name": "METROPOLITAN COMMERCIAL BANK",
    "beneficiary_address_1": "2/BENEFICIARY NAME",
    "beneficiary_address_2": "2/2 MAIN ST",
    "beneficiary_address_3": "3/US/DELAWARE 19801",
    "business_function_code": "CTP",
    "transaction_description": "I",
    "bank_to_bank_information": "",
    "originator_to_beneficiary_information": "KDJFKJ2132",
    "foreign_exchange_indicator": "F", 
    "country": "GB"
  },
  "type": "wire",
  "amount": 10000,
  "object": "incoming_payment_detail",
  "status": "completed",
  "currency": "USD",
  "metadata": {},
  "direction": "credit",
  "live_mode": true,
  "as_of_date": "2021-03-19",
  "created_at": "2021-03-19T15:05:44Z",
  "updated_at": "2021-03-20T10:01:18Z",
  "transaction_id": "3e433c03-2eaf-43c8-bc5a-b526ceb0dcba",
  "virtual_account_id": null,
  "virtual_account": null,
  "internal_account_id": "ce4a1697-d832-4cbe-a0ee-ff77a7eff912",
  "transaction_line_item_id": "513165b7-2371-420a-9235-4bca2e44cebf"
}
{
  "id": "9f4e35df-87d7-469e-ba1b-4d67ce10ce11",
  "data": {
    "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",
  "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": "1eb782a9-1dc8-463d-bb99-d311cc27c82b",
  "data": {
    "UserId": "", // Signet user id that initiated the transfer
    "Approver": "", // Signet user that approved the transfer
    "Approve Time": "2021/09/27 18:23:26 UTC",
    "Counterparty": "Normal-No MA4- API", // Sender party name
    "SenderAddress": "0x1234d8809828f366bf67f142a6ec471752445ad" // Sender's wallet address
  },
  "type": "signet",
  "amount": 10000,
  "object": "incoming_payment_detail",
  "status": "completed",
  "currency": "USD",
  "metadata": {},
  "direction": "credit",
  "live_mode": true,
  "vendor_id": "0x12340a03dc6b8173b87f6c54174a44d0da1a2d09d4305e14e4c084568a6d3ad5",
  "as_of_date": "2021-09-27",
  "created_at": "2021-10-20T07:29:18Z",
  "updated_at": "2021-10-20T07:29:18Z",
  "transaction_id": "1234851b-bb85-4006-8492-7df9f9c10e2b",
  "virtual_account": null,
  "virtual_account_id": null,
  "internal_account_id": "1234bf7a-05e2-4f93-b26c-02904a281f81",
  "transaction_line_item_id": "123469a0-42fd-4e98-b352-ccd07bb84ba7"
}